NFD

Management »

FaceMgmt » History » Revision 9

Revision 4 (Alex Afanasyev, 01/30/2014 05:37 PM) → Revision 9/120 (Junxiao Shi, 02/09/2014 08:21 PM)

# NFD Face Management protocol 

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

 The Face ace 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 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` ``FaceManagementOptions`` block. 
 Each individual command defines a subset of required and optional elements in the `FaceManagementOptions` ``FaceManagementOptions`` block. 

     FaceManagementOptions ::= FACE-MANAGEMENT-OPTIONS-TYPE TLV-LENGTH 
                                FaceId? 
                                Uri? 
                                ChannelName? ... TBD 
    
     // Name defined in NDN-TLV spec 

     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` ``ControlResponse`` block, defined in [[ControlCommand|NFD Control Command specification]]. 

 The response has StatusCode 200 if the command succeeds. 

 <!-- Alex: Should positive responses contain TLV-Encoded ``FaceManagementOptions`` block related to the command (after StatusText)? --> 

 Any other status code (4xx, 5xx, [?]) means mean error. 
 Description of the error can be present in `StatusText` ``StatusText`` field of `ControlResponse` ``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 five operations: 

 * create a face (command-verb: `create`) ``create``) 
 * destroy a face (command-verb: `destroy`) ``destroy``) 

 ### ## Create a face 

 **command-verb:** `create` ``create`` 

 Required fields in `FaceManagementOptions` ``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 [[ConfigFileFormat|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` ``destroy`` 

 Required fields in `FaceManagementOptions` ``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                                   |                     |