Project

General

Profile

Actions
History

Management »

Face Management

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

  • commands to create, modify, and destroy faces
  • a dataset containing the description of all active faces and their counters
  • a dataset containing the description of all active channels
  • a notification stream for face 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)
  • udp6://[fe80::1068:dddb:fe26:fe3f%en0]:6363 (canonical form for link-local IPv6 addresses)
  • udp6://[fe80::1068:dddb:fe26:fe3f%25en0]:6363 (equivalent, but not canonical, version of the above FaceUri)
  • 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 netdev-bound UDP face has the form:

udp[4|6]+dev://<interface-name>:<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)
  • tcp6://[fe80::1068:dddb:fe26:fe3f%en0]:6363 (canonical form for link-local IPv6 addresses)
  • tcp6://[fe80::1068:dddb:fe26:fe3f%25en0]:6363 (equivalent, but not canonical, version of the above FaceUri)
  • 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 schemes

Underlying protocol Remote FaceUri scheme Local FaceUri scheme
IPv4 UDP unicast udp4 udp4
IPv6 UDP unicast udp6 udp6
IPv4 UDP multicast udp4 (multicast group) udp4
IPv6 UDP multicast udp6 (multicast group) udp6
IPv4 UDP netdev-bound udp4 udp4+dev
IPv6 UDP netdev-bound 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

Face Properties

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
  • ad-hoc(=2), communication over a wireless ad hoc network

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

LpReliabilityEnabled indicates whether the face has the NDNLPv2 reliability feature enabled.

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

CongestionMarkingEnabled indicates whether the face has congestion marking based upon send queue length enabled.

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

BaseCongestionMarkingInterval indicates the base marking interval for congestion marking.

  • The value of this attribute is the base marking interval in nanoseconds, which is used to compute the interval at which congested packets will be marked.

DefaultCongestionThreshold indicates the default congestion threshold if the face does not support retrieving the send queue capacity.

  • The value of this attribute is the default congestion threshold in bytes.

Mtu contains a user-specified MTU to override the automatic MTU of the transport.

  • The value of this attribute is the override MTU of the transport in bytes. The face will use the lesser of this value and the automatic MTU of the underlying transport.

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: LpReliabilityEnabled
  • bit 2: CongestionMarkingEnabled

Control Commands

ControlCommand management-module: faces

Create a face

command-verb: create

ControlParameters fields:

  • Uri (required): canonical remote FaceUri of the face to create.
  • 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 "face properties" for more information.
  • BaseCongestionMarkingInterval (optional): see "face properties".
  • DefaultCongestionThreshold (optional): see "face properties".
  • Mtu (optional): see "face properties".
  • Flags (optional): see "face properties".
  • Mask (optional): MUST be specified if Flags is present, and omitted if Flags is omitted.

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
  • BaseCongestionMarkingInterval (optional)
  • DefaultCongestionThreshold (optional)
  • Mtu (optional): effective MTU, see below.
  • Flags: contains effective values for the LocalFieldsEnabled, LpReliabilityEnabled, and CongestionMarkingEnabled bits.

If this creation would conflict with an existing face (e.g., same underlying protocol and remote endpoint), 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 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.

If BaseCongestionMarkingInterval or DefaultCongestionThreshold are omitted from the ControlParameters sent with the creation command, the omitted properties are left at their implementation-defined default values.

If Mtu is omitted from the ControlParameters sent with the creation command, no override MTU is specified and the automatic MTU of the transport will be used. A forwarder MAY impose an implementation-defined minimum and maximum to the override MTU specified during face creation. The current minimum and maximum in NFD are 64 and MAX_NDN_PACKET_SIZE (8800) bytes, respectively. In the response, the Mtu field in ControlParameters contains the effective MTU of the face (in bytes), capped at a maximum of MAX_NDN_PACKET_SIZE (8800 bytes), even if the MTU of the underlying transport is infinite. If Mtu is omitted from the response, the face and/or forwarder does not support MTU reporting.

Update the properties of a face

command-verb: update

ControlParameters fields:

  • FaceId (optional)
  • FacePersistency (optional): one of on-demand, persistent, or permanent. See "face properties" for more information.
  • BaseCongestionMarkingInterval (optional): see "face properties".
  • DefaultCongestionThreshold (optional): see "face properties".
  • Mtu (optional): see "face properties".
  • Flags (optional): allows LocalFieldsEnabled, LpReliabilityEnabled, and CongestionMarkingEnabled only. See "face properties" for more information.
  • Mask (optional): MUST be specified if Flags is present, and omitted if Flags is omitted.

If FaceId is omitted or is set to zero, it is implied to be that of the requesting face (self-update).
If the face does not exist, the command fails with StatusCode 404.

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

As with faces/create, a forwarder may clamp the MTU value specified when updating a face. The aforementioned implementation-specific bounds still apply for NFD.

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

  • FaceId
  • FacePersistency
  • BaseCongestionMarkingInterval (optional)
  • DefaultCongestionThreshold (optional)
  • Mtu (optional): effective MTU.
  • Flags: contains effective values for LocalFieldsEnabled, LpReliabilityEnabled, and CongestionMarkingEnabled 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
                    LocalUri
                    [ExpirationPeriod]
                    FaceScope
                    FacePersistency
                    LinkType
                    [BaseCongestionMarkingInterval]
                    [DefaultCongestionThreshold]
                    [Mtu]
                    NInInterests
                    NInData
                    NInNacks
                    NOutInterests
                    NOutData
                    NOutNacks
                    NInBytes
                    NOutBytes
                    Flags

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

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

(all 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 "face properties" for more information.
  • FacePersistency indicates whether the face is persistent. See "face properties" for more information.
  • LinkType indicates the type of communication link See "face properties" for more information.
  • BaseCongestionMarkingInterval indicates the base interval used to compute the interval at which congested packets will be marked (in nanoseconds). See "face properties" for more information.
  • DefaultCongestionThreshold indicates the default threshold for congestion if the face does not support retrieving the send queue capacity (in bytes). See "face properties" for more information.
  • Mtu contains the effective MTU of the face (in bytes), capped at MAX_NDN_PACKET_SIZE (8800 bytes), even if the MTU of the underlying transport is infinite. If this field is omitted, the forwarder and/or face does not support MTU reporting.
  • 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.
  • Flags contains these bitfields: LocalFieldsEnabled, LpReliabilityEnabled, CongestionMarkingEnabled. See "face properties" for more information.

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 UTF-8-STRING
  • 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 domain name, include port number)
  • all TCP tunnels: UriScheme=tcp
    (note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6")
  • all UDP multi-access faces: UriScheme=udp && LinkType=multi-access
  • all Ethernet faces: UriScheme=ether
    (note: UriScheme matches against 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 the channel's 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
UriScheme 131 0x83
FaceScope 132 0x84
FacePersistency 133 0x85
LinkType 134 0x86
BaseCongestionMarkingInterval 135 0x87
DefaultCongestionThreshold 136 0x88
Mtu 137 0x89
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
FaceEventNotification 192 0xc0
FaceEventKind 193 0xc1
(reserved, formerly FaceFlags) 194 0xc2

Updated by Davide Pesavento over 4 years ago · 107 revisions