NFD Face Management protocol¶

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

The Face Management protocol uses [[|Command Interests|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