FaceMgmt » History » Revision 17
Revision 16 (Alex Afanasyev, 02/15/2014 09:13 PM) → Revision 17/118 (Alex Afanasyev, 02/15/2014 09:13 PM)
# 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 [[|Command Interests|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