NFD

# NFD Face Management protocol

The **Face Management protocol** allows an entity to request NFD daemon create and destroy faces.

The Face Management protocol uses [[Signed Command Interests]] to authenticate each issued command.

## Command format

### Request

Request is a [[Command Interests|Command Interest]] with the following name:

    /localhost/nfd/faces/<command-verb>/<command-options>/.....................

    \                  / \                              / \                   /

     --------  --------   -------------  ---------------   --------  ---------

             \/                        \/                          \/

    NFD Control Command       FaceManager command           Command Interest

    to FaceManager            and command options          related information

Command options is defined as a TLV-encoded `FaceManagementOptions` block.

Each individual command defines a subset of required and optional elements in the `FaceManagementOptions` block.

    FaceManagementOptions ::= FACE-MANAGEMENT-OPTIONS-TYPE TLV-LENGTH

                               FaceId?

                               Uri?

    FaceId                ::= FACEID-TYPE TLV-LENGTH

                                nonNegativeInteger

    Uri                   ::= URI-TYPE TLV-LENGTH

                                RFC3986 URI in UTF-8 encoding

### Response

Command response is a Data packet that contains TLV-encoded ``ControlResponse`` block, defined in [[ControlCommand|NFD Control Command specification]].

Content of ``ControlResponse`` on success:

Field in ``ControlResponse`` block | Value

---------------------------------- | -----

``StatusCode``                     | 200

``StatusText``                     | "Success"

``<StatusBody>``                   | ``FaceManagementOptions`` block, either echoed or with updated ``Uri``---hostname replaced with IP address---and ``FaceId`` fields

Content of ``ControlResponse`` on error:

Field in ``ControlResponse`` block | Value

---------------------------------- | -----

``StatusCode``                     | 4xx, 500x, or other error codes based on RFC2616

``StatusText``                     | Human-readable description of the error

``<StatusBody>``                   | Not present

## URI

The underlying protocol and underlying address of a Face is expressed as a URI.

### UDP unicast

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

Examples:

* `udp://192.0.2.1:6363` (canonical form)

* `udp://192.0.2.1` (remote-port defaults to 6363)

* `udp://[2001:db8::1]:6363` (canonical form)

* `udp://example.net:6363`

* `udp4://example.net:6363` (resolve hostname to IPv4 address only)

* `udp6://example.net:6363` (resolve hostname to IPv6 address only)

### UDP multicast

`udp-mcast://<multicast-IP>:<multicast-port>`

Examples:

* `udp://224.0.23.170:56363`

### TCP

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

Examples:

* `tcp://192.0.2.1:6363` (canonical form)

* `tcp://192.0.2.1` (remote-port defaults to 6363)

* `tcp://[2001:db8::1]:6363` (canonical form)

* `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 there are three forward-slashes after 'unix')

URI is available for the channel only.

Accepted UNIX stream faces do not have URI.

### Ethernet unicast

`ether://<remote-MAC>`

Examples:

* `ether://08:00:27:01:01:01`

### Ethernet multicast

`ether-mcast://<multicast-MAC>`

Examples:

* `ether-mcast://33:33:01:01:01:01`

## Operations

**Face management protocol** protocol supports two operations:

* create a face (command-verb: `create`)

* destroy a face (command-verb: `destroy`)

### Create a face

**command-verb:** `create`

Required fields in `FaceManagementOptions` block:

* `Uri`

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

If the command succeeds, the `ControlResponse` block in the response contains a `FaceManagementOptions` block, which contains:

* `FaceId`

* `Uri`, the canonical URI

If another face exists for the same underlying protocol and address, the command is considered successful, and that face is returned.

### Destroy a face

**command-verb:** `destroy`

Required fields in `FaceManagementOptions` block:

* `FaceId`

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

## TLV-TYPE assignments

Type                                        | Assigned value    | Assigned value (hex)

------------------------------------------- | ----------------- | --------------------

FaceManagementOptions                       | 108               | 0x6c

FaceId                                      | 105               | 0x69

Uri                                         | 114               | 0x72