NFD

# Face Management

{{toc}}

**Face Management** is a module of [[Management|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 multicast  | ether                       | dev

WebSocket             | wsclient                  | ws

## Static Face Attributes

**FaceScope** indicates whether the face is local for [[ScopeControl|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

### 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

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): a canonical remote FaceUri of the face to create (e.g., UDP unicast, Ethernet unicast, or TCP)

* LocalUri (optional): a canonical local FaceUri of the face to create (e.g., FaceUri for the local interface for Ethernet unicast face)

* FacePersistency (optional): either *persistent* or *permanent*; creating on-demand faces is disallowed.  

  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 creation of UDP unicast and TCP faces only.  

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

* FaceId

* FacePersistency

* Flags: contains effective value for *LocalFieldsEnabled* bit

If this creation would conflict with another existing face (e.g. same underlying protocol and remote address, or a NIC-associated permanent face), the command fails with StatusCode 409, and \<body> in ControlResponse block contains ControlParameters describing the existing face including these fields:

* FaceId

* Uri

* FacePersistency

* Flags: contains effective value for *LocalFieldsEnabled* bit

If the request attempts to create a face other than UDP unicast and TCP faces, or a static property specified 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* only, see "static face attributes".

* Mask (optional): see "static face attributes".

FaceId is the FaceId returned in [[FaceMgmt|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 value for *LocalFieldsEnabled* bit

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 [[StatusDataset|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

                          NInDatas

                          NInNacks

                          NOutInterests

                          NOutDatas

                          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 [[ScopeControl|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*.

  See "static face attributes" for more information.

* **NInInterests**: number of incoming Interest packets since the face is established.

* **NInDatas** 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.

* **NOutDatas** 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 [[StatusDataset|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|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

NInDatas                                    | 145               | 0x91

NInNacks                                    | 151               | 0x97

NOutInterests                               | 146               | 0x92

NOutDatas                                   | 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