Project

General

Profile

FaceMgmt » History » Revision 25

Revision 24 (Alex Afanasyev, 03/20/2014 05:22 PM) → Revision 25/118 (Junxiao Shi, 03/24/2014 10:03 AM)

# Face Management 

 **Face Management** is a module of [[Management|NFD Management protocol]]. 
 It provides: 

 * commands to create and destroy faces 
 * commands to enable and disable [[LocalControlHeader]] features on a face 
 * a dataset of description of all active faces and their counters 
 * a notification stream for face creating and destroying events 

 Face Management commands, datasets, and notifications are published in namespace `ndn:/localhost/nfd/faces`. 



 ## FaceUri 

 A FaceUri indicates the underlying protocol and underlying address of a Face. 

 ### UDP unicast 

 `udp[4|6]://<remote-IP-or-host>[:<remote-port>]` 

 Examples: 

 * `udp4://192.0.2.1:6363` (canonical form) 
 * `udp6://[2001:db8::1]:6363` (canonical form) 
 * `udp://192.0.2.1` (remote-port defaults to 6363) 
 * `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: 

 * `tcp4://192.0.2.1:6363` (canonical form) 
 * `tcp6://[2001:db8::1]:6363` (canonical form) 
 * `tcp://192.0.2.1` (remote-port defaults to 6363) 
 * `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` 



 ## Control Commands 

 [[ControlCommand]] **management-module**: `faces` 

 ### Create a face 

 **command-verb**: `create` 

 ControlParameters fields: 

 * Uri (required): a FaceUri that represents a UDP unicast tunnel or a TCP tunnel 

 This command allows creation of UDP unicast and TCP faces only.   
 If another face exists for the same underlying protocol and address, the command is considered successful, and FaceId of that face is returned. 

 If the command succeeds, \<Body> in ControlResponse block contains updated ControlParameters: 

 * FaceId 
 * Uri: FaceUri in canonical form - hostname is substituted with IP address, scheme name indicates either IPv4 or IPv6 

 ### Destroy a face 

 **command-verb:** `destroy` 

 ControlParameters fields: 

 * FaceId (required) 

 If the specified face does not exist, this command does nothing, but is still considered successful. 

 ### Enable a LocalControlHeader feature 

 **command-verb**: `enable-local-control` 

 ControlParameters fields: 

 * FaceId (required) 
 * LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId 

 If the face doesn't exist, the command fails with code 404.   
 If the face is not local, the command fails with code 412. 

 ### Disable a LocalControlHeader feature 

 **command-verb**: `disable-local-control` 

 ControlParameters fields: 

 * FaceId (required) 
 * LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId 

 If the face doesn't exist, the command fails with code 404.   
 If the face is not local, the command fails with code 412. 



 ## Face Dataset 

 Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`. 

 Each face is represented by a **FaceStatus** blocks: 

     FaceStatus      := FACE-STATUS-TYPE TLV-LENGTH 
                        FaceId 
                        Uri 
                        NInInterests 
                        NInDatas 
                        NOutInterests 
                        NOutDatas 
    
     NInInterests    := N-IN-INTERESTS-TYPE TLV-LENGTH 
                        nonNegativeInteger 
    
     NInDatas        := N-IN-DATAS-TYPE TLV-LENGTH 
                        nonNegativeInteger 
    
     NOutInterests := N-OUT-INTERESTS-TYPE TLV-LENGTH 
                        nonNegativeInteger 
    
     NOutDatas       := N-OUT-DATAS-TYPE TLV-LENGTH 
                        nonNegativeInteger 

 * NInInterests is the total number of incoming Interests since the face is established. 
 * NInDatas is the total number of incoming Datas since the face is established. 
 * NOutInterests is the total number of outgoing Interests since the face is established. 
 * NOutDatas is the total number of outgoing Datas since the face is established. 

 ## Face Status Change Notification 

 Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`. 
 Events of all faces are sent into the same notification stream. 

 The Content of each notification Data packet is a `FaceEventNotification` block: 

     FaceEventNotification := FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH 
                                FaceEventKind 
                                FaceId 
                                Uri 
                                FaceFlags 
    
     FaceEventKind           := FACE-EVENT-KIND-TYPE TLV-LENGTH 
                                
                        nonNegativeInteger 

     FaceFlags               := FACE-FLAGS-TYPE TLV-LENGTH 
                                
                        nonNegativeInteger 

 **FaceEventKind** indicates the kind of event. Its possible values are: 

 * **1**: face is created or accepted 
 * **2**: face is destroyed or closed 

 **FaceFlags** is a bitset, providing additional information about the face.    The following bits are currently defined: 

 * **1**: face is local 
 * **2**: face is created on demand - accepted (e.g., as a response to an incoming connection, instead of initiated outgoing connection connection) 

 ## TLV-TYPE assignments 

 Type                                          | Assigned value      | Assigned value (hex) 
 ------------------------------------------- | ----------------- | -------------------- 
 FaceStatus                                    | 128                 | 0x80 
 NInInterests                                  | 144                 | 0x90 
 NInDatas                                      | 145                 | 0x91 
 NOutInterests                                 | 146                 | 0x92 
 NOutDatas                                     | 147                 | 0x93 
 FaceEventNotification                         | 192                 | 0xc0 
 FaceEventKind                                 | 193                 | 0xc1 
 FaceFlags                                     | 194                 | 0xc2