NFD

Management »

FaceMgmt » History » Revision 10

Revision 9 (Junxiao Shi, 02/09/2014 08:21 PM) → Revision 10/120 (Junxiao Shi, 02/09/2014 09:29 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 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` 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? 
                                ChannelName? 
    
     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` block, defined in [[ControlCommand|NFD Control Command specification]]. 

 The response has StatusCode 200 if the command succeeds. 

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

 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` 

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