NFD

Management »

FaceMgmt » History » Revision 14

Revision 13 (Alex Afanasyev, 02/11/2014 02:46 PM) → Revision 14/118 (Junxiao Shi, 02/13/2014 09:49 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 [[Signed Interests]]-Data exchange. 
 The command request and response follows the [[ControlCommand|NFD Control Command specification]] 

 ## Command format 

 

 ### Request 

 Request is a [[Command Interests|Command Interest]] signed Interest with the following name: 

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

     \                    / \                                / \                                                                                                      / 
      --------    --------     -------------    ---------------     --------------------------- --------------------    --------------------------- -------------------- 
              \/                          \/                                                                                      \/ 
     NFD Control Command         FaceManager command                       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? 
    
     FaceId                                  ::= FACEID-TYPE TLV-LENGTH 
                                 
                                nonNegativeInteger 
    
     Uri                                        ::= URI-TYPE TLV-LENGTH 
                                 RFC3986 URI in 
                                UTF-8 encoding 

 string 

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