Face Management¶

• Table of contents
• Face Management
  • FaceUri
    • UDP
    • TCP
    • UNIX stream
    • File Descriptor
    • Ethernet
    • Network Device
    • Underlying protocol and FaceUri scheme
  • Static Face Attributes
    • Flags and Mask
  • Control Commands
    • Create a face
    • Update static properties
    • Destroy a face
  • Face Dataset
    • Query Operation
  • Channel Dataset
  • Face Status Change Notification
  • TLV-TYPE assignments

Face Management is a module of NFD Management protocol.
It provides:

• commands to create and destroy faces
• commands to enable and disable LocalControlHeader features on a face
• a dataset of description of all active faces and their counters
• a dataset of description of all active channels
• a notification stream for face creating and destroying events

Face Management commands, datasets, and notifications are available under namespace ndn:/localhost/nfd/faces.

FaceUri¶

A FaceUri represents the underlying protocol and address used by a Face.

Every Face has two FaceUris: one for local endpoint, and the other for remote endpoint.

UDP¶

udp[4|6]://<IP-or-host>[:<port>]

Examples:

• udp4://192.0.2.1:6363 (canonical form)
• udp6://[2001:db8::1]:6363 (canonical form)
• udp://192.0.2.1 (remote-port defaults to 6363)
• udp://example.net:6363
• udp4://example.net:6363 (resolve hostname to IPv4 address only)
• udp6://example.net:6363 (resolve hostname to IPv6 address only)
• udp4://224.0.23.170:56363 (multicast, canonical form)

LocalUri of a NIC-associated UDP face has the form:

udp[4|6]+dev://<NIC>:<port>

This is only used in face dataset.

Examples:

• udp4+dev://eth1:6363
• udp6+dev://en0:6363

TCP¶

tcp[4|6]://<IP-or-host>[:<port>]

Examples:

• tcp4://192.0.2.1:6363 (canonical form)
• tcp6://[2001:db8::1]:6363 (canonical form)
• tcp://192.0.2.1 (remote-port defaults to 6363)
• tcp://example.net:6363
• tcp4://example.net:6363 (resolve hostname to IPv4 address only)
• tcp6://example.net:6363 (resolve hostname to IPv6 address only)

UNIX stream¶

unix://<path>

Examples:

• unix:///var/run/nfd.sock (note that there are three forward-slashes after 'unix:')

File Descriptor¶

fd://<file-descriptor>

Examples:

• fd://6

Ethernet¶

ether://[<MAC>]

Examples:

• ether://[08:00:27:01:01:01]
• ether://[33:33:01:01:01:01] (multicast)

Network Device¶

dev://<interface-name>

Examples:

• dev://eth0

Underlying protocol and FaceUri scheme¶

Underlying protocol	Remote FaceUri scheme	Local FaceUri scheme
IPv4 UDP unicast	udp4	udp4
IPv6 UDP unicast	udp6	udp6
IPv4 UDP multicast	udp4 (multicast IP)	udp4 (local IP, same port)
IPv4 UDP NIC-associated	udp4	udp4+dev
IPv6 UDP NIC-associated	udp6	udp6+dev
IPv4 TCP	tcp4	tcp4
IPv6 TCP	tcp6	tcp6
UNIX stream	fd (file descriptor on NFD side)	unix (socket path)
Ethernet unicast	ether	dev
Ethernet multicast	ether	dev
WebSocket	wsclient	ws

Static Face Attributes¶

FaceScope indicates whether the face is local for scope control purposes.

• non-local(=0)
• local(=1)

FacePersistency indicates whether the face is persistent.

• on-demand(=1), face closes if it remains idle for some time
• persistent(=0), face remains open until it's explicitly destroyed or there's a transport failure
• permanent(=2), face remains open until it's explicitly destroyed; transport failures will be recovered internally

LinkType indicates the type of communication link.

• point-to-point(=0), communication with one peer
• multi-access(=1), communication with a multicast group

LocalFieldsEnabled indicates whether the face allows NDNLPv2 NextHopFaceId, CachePolicy, IncomingFaceId fields.

• yes(=1), allows these fields; this is valid only if FaceScope=local
• no(=0), disallows these fields

ReliabilityEnabled indicates whether the face has the reliability feature enabled.

• yes(=1), enables this feature
• no(=0), disables this feature

Flags and Mask¶

Some attributes are collected as inclusive OR into a Flags field in commands and datasets.
These attributes are: (bit 0 is the least significant bit)

• bit 0: LocalFieldsEnabled
• bit 1: ReliabilityEnabled

In create and update commands, the Flags field must be accompanied by a Mask field which indicates which static attributes should be set; in other words, Flags and Mask fields must be both specified or both omitted.
Bits in the Mask field is arranged in the same order as the Flags field.
If a bit in Mask is zero, faces/create command keeps the default setting of the attribute, faces/update command keeps the old value of the attribute.

Control Commands¶

ControlCommand management-module: faces

Create a face¶

command-verb: create

ControlParameters fields:

• Uri (required): canonical remote FaceUri of the face to create (e.g., UDP unicast, Ethernet unicast, or TCP)
• LocalUri (optional): canonical local FaceUri of the face to create (e.g., FaceUri of the local interface for an Ethernet unicast face)
• FacePersistency (optional): either persistent or permanent; creating on-demand faces is not permitted.
  The default is persistent.
  See "static face attributes" for more information.
• Flags (optional): see "static face attributes".
• Mask (optional): see "static face attributes".

This command allows the creation of UDP unicast, Ethernet unicast, and TCP faces only.

If the command succeeds, the <body> of the ControlResponse block contains the ControlParameters describing the current properties of the created face:

• FaceId
• Uri
• LocalUri
• FacePersistency
• Flags: contains effective values for LocalFieldsEnabled and ReliabilityEnabled bits

If this creation would conflict with an existing face (e.g., same underlying protocol and remote endpoint, or a NIC-associated permanent face), the command fails with StatusCode 409, and the <body> of the ControlResponse block contains the ControlParameters describing the existing face, with the same fields as above.

If the request attempts to create a face other than UDP unicast, Ethernet unicast, or TCP, or if a static property specified in the request is not acceptable, the command fails with StatusCode 406.

If face creation fails due to a socket error (e.g. TCP connection timeout), the command fails with StatusCode 504.

Update static properties¶

command-verb: update

ControlParameters fields:

• FaceId (optional)
• FacePersistency (optional): on-demand or persistent or permanent
  See "static face attributes" for more information.
• Flags (optional): allows LocalFieldsEnabled and ReliabilityEnabled only, see "static face attributes".
• Mask (optional): see "static face attributes".

FaceId is the FaceId returned in Face Management.
If FaceId is omitted or is set to zero, it is implied as the requesting face (self updating).

If face does not exist, this command fails with StatusCode 404.

Static properties of the face is updated.
If an optional property field is omitted or a bitfield is zero in Mask, that static property remains unchanged.
If no static property is changed, this command does nothing, but is still considered successful.

If the command succeeds, <body> in ControlResponse block contains ControlParameters describing the current properties of the face:

• FaceId
• FacePersistency
• Flags: contains effective values for LocalFieldsEnabled and ReliabilityEnabled bits

If any of the requested changes is invalid, none of the changes should be performed, and this command fails with StatusCode 409.
The <body> in ControlResponse block contains ControlParameters that includes only invalid fields; if some of the bit fields chosen in Flags+Mask is invalid, the <body> block should also contain a Mask field indicating which bits are invalid, and echo back the original Flags field.
If the request had been sent without those fields (or bitfields in Mask), it would have been successful.

Destroy a face¶

command-verb: destroy

ControlParameters fields:

• FaceId (required)

If the specified face does not exist, this command does nothing, but is still considered successful.

Face Dataset¶

Description and counters of all active faces are published as a Status Dataset at ndn:/localhost/nfd/faces/list.

Each face is represented by a FaceStatus block:

FaceStatus      ::= FACE-STATUS-TYPE TLV-LENGTH
                      FaceId
                      Uri (remote FaceUri)
                      LocalUri
                      ExpirationPeriod?
                      FaceScope
                      FacePersistency
                      LinkType
                      Flags
                      NInInterests
                      NInData
                      NInNacks
                      NOutInterests
                      NOutData
                      NOutNacks
                      NInBytes
                      NOutBytes

Uri             ::= URI-TYPE TLV-LENGTH
                      FaceUri in UTF-8 encoding

LocalUri        ::= LOCAL-URI-TYPE TLV-LENGTH
                      FaceUri in UTF-8 encoding

; other TLVs have nonNegativeInteger as value

• Uri is a FaceUri representing remote endpoint.
• LocalUri is a FaceUri representing local endpoint.
• ExpirationPeriod is the remaining lifetime of this face. If this field is omitted, the face has infinite lifetime. Currently, this is applicable to on-demand datagram faces only.
• FaceScope indicates whether the face is local for scope control purposes. See "static face attributes" for more information.
• FacePersistency indicates whether the face is persistent. See "static face attributes" for more information.
• LinkType indicates the type of communication link See "static face attributes" for more information.
• Flags contains these bitfields: LocalFieldsEnabled, ReliabilityEnabled. See "static face attributes" for more information.
• NInInterests: number of incoming Interest packets since the face is established.
• NInData counts the number of incoming Data packets since the face is established.
• NInNacks counts the number of incoming Nack packets since the face is established.
• NOutInterests counts the number of outgoing Interest packets since the face is established.
• NOutData counts the number of outgoing Data packets since the face is established.
• NOutNacks counts the number of outgoing Nack packets since the face is established.
• NInBytes counts the number of bytes of link layer packets received via this face. This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
• NOutBytes counts the number of bytes of link layer packets sent via this face. This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.

Query Operation¶

The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter.

To run a query, the consumer should express an Interest with Name: ndn:/localhost/nfd/faces/query/<filter>, where <filter> is a FaceQueryFilter block that specifies zero or more conditions.

FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH
                      FaceId?
                      UriScheme?
                      Uri?
                      LocalUri?
                      FaceScope?
                      FacePersistency?
                      LinkType?

UriScheme       ::= URI-SCHEME-TYPE TLV-LENGTH
                      string in UTF-8

• FaceId permits a face if its FaceId equals the value
• UriScheme permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value
• Uri permits a face if its remote FaceUri equals the value
• LocalUri permits a face if its local FaceUri equals the value
• FaceScope permits a face if its FaceScope attribute equals the value
• FacePersistency permits a face if its FacePersistency attribute equals the value
• LinkType permits a face if its LinkType attribute equals the value

A face must satisfy ALL conditions to satisfy the filter.
Faces that satisfy the filter are represented by FaceStatus blocks, and published as a StatusDataset under the Interest Name (a Data packet's Name would be ndn:/localhost/nfd/faces/query/<filter>/<version>/<segment>).

Examples of filters:

• a specific face: FaceId=260
• a specific TCP tunnel: Uri=tcp4://192.0.2.1:6363
  note: FaceUri must precisely match the canonical form: use either "tcp4" or "tcp6" instead of "tcp", use IP address instead of DNS name, include port number
• all TCP tunnels: UriScheme=tcp
  note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6"
• all UDP multicast faces: UriScheme=udp & LinkType=multi-access
• all Ethernet faces: UriScheme=ether note: UriScheme matches on both local and remote FaceUri, "dev" also works
• all faces: no condition
  note: this is equivalent to face dataset, and face dataset should be preferred for this purpose

Channel Dataset¶

Description of all active channels is published as a Status Dataset at ndn:/localhost/nfd/faces/channels.

Each channel is represented by a ChannelStatus block:

ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
                      LocalUri

• LocalUri is a FaceUri representing local endpoint.

Face Status Change Notification¶

Face status change events are published as a Notification Stream at ndn:/localhost/nfd/faces/events.
Notifications of all faces are sent into the same notification stream.

The Content of each notification Data packet is a FaceEventNotification block:

FaceEventNotification ::= FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
                            FaceEventKind
                            FaceId
                            Uri
                            LocalUri
                            FaceScope
                            FacePersistency
                            LinkType
                            Flags

FaceEventKind         ::= FACE-EVENT-KIND-TYPE TLV-LENGTH
                            nonNegativeInteger

FaceEventKind indicates the kind of event. Its possible values are:

• 1: face is created
• 2: face is destroyed
• 3: face goes UP (from DOWN state)
• 4: face goes DOWN (from UP state)

TLV-TYPE assignments¶

Type	Assigned value	Assigned value (hex)
FaceStatus	128	0x80
LocalUri	129	0x81
ChannelStatus	130	0x82
FaceScope	132	0x84
FacePersistency	133	0x85
LinkType	134	0x86
NInInterests	144	0x90
NInData	145	0x91
NInNacks	151	0x97
NOutInterests	146	0x92
NOutData	147	0x93
NOutNacks	152	0x98
NInBytes	148	0x94
NOutBytes	149	0x95
FaceQueryFilter	150	0x96
UriScheme	131	0x83
FaceEventNotification	192	0xc0
FaceEventKind	193	0xc1
(reserved, formerly FaceFlags)	194	0xc2