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