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 Interests]]-Data exchange.

The command request and response follows the [[ControlCommand|NFD Control Command specification]]

## Command format

### Request

Request is a signed Interest with the following name:

    /localhost/nfd/faces/<command-verb>/<command-options>/<timestamp>/<SignatureInfo>/<SignatureValue>

    \                  / \                              / \                                          /

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

             \/                        \/                                      \/

    NFD Control Command       FaceManager command            Signed Interest related information

    to FaceManager            and command options

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?

                               ChannelName?

    FaceId               ::= FACEID-TYPE TLV-LENGTH

                               nonNegativeInteger

    Uri                  ::= URI-TYPE TLV-LENGTH

                               UTF-8 string

    ChannelName          ::= CHANNEL-NAME-TYPE TLV-LENGTH

                               UTF-8 string

### Response

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

The response has StatusCode 200 if the command succeeds.

Any other status code (4xx, 5xx, [?]) means error.

Description of the error can be present in `StatusText` field of `ControlResponse` command.

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

Optional fields in `FaceManagementOptions` block:

* `ChannelName`

The `ChannelName` field chooses a channel to create the new face within. Channel names are defined in [[ConfigFileFormat|configuration file]].

If this field is omitted, NFD can create the face under any channel of a compatible underlying protocol.

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 resolved URI

* `ChannelName`

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

ChannelName                                 |                   |