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