Project

General

Profile

FaceMgmt » History » Revision 47

Revision 46 (Junxiao Shi, 08/20/2015 02:00 PM) → Revision 47/118 (Yukai Tu, 08/23/2015 10:12 AM)

# Face Management 

 {{toc}} 

 **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 dataset of description of all active channels 
 * a notification stream for face creating and destroying events 

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


 ## FaceUri 

 A FaceUri represents the underlying protocol and address used by a Face.   
 Every Face has two FaceUris: one for local endpoint, and the other for remote endpoint. 

 ### UDP 

 `udp[4|6]://<IP-or-host>[:<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) 
 * `udp4://224.0.23.170:56363` (multicast, canonical form) 

 ### TCP 

 `tcp[4|6]://<IP-or-host>[:<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') 

 ### File Descriptor 

 `fd://<file-descriptor>` 

 Examples: 

 * `fd://6` 

 ### Ethernet 

 `ether://[<MAC>]` 

 Examples: 

 * `ether://[08:00:27:01:01:01]` 
 * `ether://[33:33:01:01:01:01]` (multicast) 

 ### Network Device 

 `dev://<ifname>` 

 Examples: 

 * `dev://eth0` 

 ### Underlying protocol and FaceUri scheme 

 Underlying protocol | remote FaceUri scheme              | local FaceUri scheme 
 ------------------- | -------------------------------- | -------------------------- 
 IPv4 UDP unicast      | udp4                               | udp4 
 IPv6 UDP unicast      | udp6                               | udp6 
 IPv4 UDP multicast    | udp4 (multicast IP)                | udp4 (local IP, same port) 
 IPv4 TCP              | tcp4                               | tcp4 
 IPv6 TCP              | tcp6                               | tcp6 
 UNIX stream           | fd (file descriptor on NFD side) | unix (socket path) 
 Ethernet multicast    | ether                              | dev 

 ## Static Face Attributes 

 **FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes. 

 * non-local(=0) 
 * local(=1) 

 **FacePersistency** indicates whether the face is persistent. 

 * on-demand(=1), face closes if it remains idle for some time 
 * persistent(=0), face remains open until it's explicitly destroyed or there's a transport failure 
 * permanent(=2), face remains open until it's explicitly destroyed; transport failures will be recovered internally 

 **LinkType** indicates the type of communication link. 

 * point-to-point(=0), communication with one peer 
 * multi-access(=1), communication with a multicast group 

 ## Control Commands 

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

 ### Create a face 

 **command-verb**: `create` 

 ControlParameters fields: 

 * Uri (required): a canonical UDP unicast or TCP FaceUri 
 * FacePersistency (optional): either *persistent* or *permanent*; creating on-demand faces is disallowed.   
   The default is *persistent*.   
   See "static face attributes" for more information. 

 This command allows creation of UDP unicast and TCP faces only.   
 If another face with same underlying protocol and remote address exists, the command is considered successful, and FaceId of that face is returned; 
 If the existing face has a different FacePersistency property, the transition on the direction of *on-demand* -> *persistent* -> *permanent* is allowed. 

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

 * FaceId 
 * FacePersistency 

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

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

 This command can only operate on the requesting face. 

 ### Disable a LocalControlHeader feature 

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

 ControlParameters fields: 

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

 This command can only operate on the requesting face. 

 ## 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** block: 

     FaceStatus        ::= FACE-STATUS-TYPE TLV-LENGTH 
                           FaceId 
                           Uri (remote FaceUri) 
                           LocalUri 
                           ExpirationPeriod? 
                           FaceScope 
                           FacePersistency 
                           LinkType 
                           NInInterests 
                           NInDatas 
                           NInNacks 
                           NOutInterests 
                           NOutDatas 
                           NOutNacks 

     Uri               ::= URI-TYPE TLV-LENGTH 
                           FaceUri in UTF-8 encoding 

     LocalUri          ::= LOCAL-URI-TYPE TLV-LENGTH 
                           FaceUri in UTF-8 encoding 
    
     ; other TLVs have nonNegativeInteger as value 

 * **Uri** is a FaceUri representing remote endpoint. 
 * **LocalUri** is a FaceUri representing local endpoint. 
 * **ExpirationPeriod** is the remaining lifetime of this face. 
   If this field is omitted, the face has infinite lifetime. 
   Currently, this is applicable to on-demand datagram faces only. 
 * **FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes. 
   See "static face attributes" for more information. 
 * **FacePersistency** indicates whether the face is persistent. 
   See "static face attributes" for more information. 
 * **LinkType** indicates the type of communication link 
   See "static face attributes" for more information. 
 * **NInInterests**: number of incoming Interest packets since the face is established. 
 * **NInDatas** counts the number of incoming Data packets since the face is established. 
 * **NInNacks** counts the number of incoming Nack packets since the face is established. 
 * **NOutInterests** counts the number of outgoing Interest packets since the face is established. 
 * **NOutDatas** counts the number of outgoing Data packets since the face is established. 
 * **NOutNacks** counts the number of outgoing Nack packets since the face is established. 
 * **NInBytes** counts the number of bytes of link layer packets received via this face. 
   This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range. 
 * **NOutBytes** counts the number of bytes of link layer packets sent via this face. 
   This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range. 

 ### Query Operation 

 The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter. 

 To run a query, the consumer should express an Interest with Name: `ndn:/localhost/nfd/faces/query/<filter>`, where `<filter>` is a **FaceQueryFilter** block that specifies zero or more conditions. 

     FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH 
                           FaceId? 
                           UriScheme? 
                           Uri? 
                           LocalUri? 
                           FaceScope? 
                           FacePersistency? 
                           LinkType? 
    
     UriScheme         ::= URI-SCHEME-TYPE TLV-LENGTH 
                           string in UTF-8 

 * **FaceId** permits a face if its FaceId equals the value 
 * **UriScheme** permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value 
 * **Uri** permits a face if its remote FaceUri equals the value 
 * **LocalUri** permits a face if its local FaceUri equals the value 
 * **FaceScope** permits a face if its *FaceScope* attribute equals the value 
 * **FacePersistency** permits a face if its *FacePersistency* attribute equals the value 
 * **LinkType** permits a face if its *LinkType* attribute equals the value 

 A face must satisfy ALL conditions to satisfy the filter. 
 Faces that satisfy the filter are represented by **FaceStatus** blocks, and published as a [[StatusDataset]] under the Interest Name (a Data packet's Name would be `ndn:/localhost/nfd/faces/query/<filter>/<version>/<segment>`). 

 Examples of filters: 

 * a specific face: FaceId=260 
 * a specific TCP tunnel: Uri=tcp4://192.0.2.1:6363   
   note: FaceUri must precisely match the canonical form: use either "tcp4" or "tcp6" instead of "tcp", use IP address instead of DNS name, include port number 
 * all TCP tunnels: UriScheme=tcp   
   note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6" 
 * all UDP multicast faces: UriScheme=udp & LinkType=multi-access 
 * all Ethernet faces: UriScheme=ether 
   note: UriScheme matches on both local and remote FaceUri, "dev" also works 
 * all faces: no condition   
   note: this is equivalent to face dataset, and face dataset should be preferred for this purpose 

 ## Channel Dataset 

 Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`. 

 Each channel is represented by a **ChannelStatus** block: 

     ChannelStatus      := CHANNEL-STATUS-TYPE TLV-LENGTH 
                           LocalUri 

 * **LocalUri** is a FaceUri representing local endpoint. 

 ## Face Status Change Notification 

 Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`. 
 Notifications 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 
                                 LocalUri 
                                 FaceScope 
                                 FacePersistency 
                                 LinkType 
    
     FaceEventKind           ::= FACE-EVENT-KIND-TYPE TLV-LENGTH 
                                 nonNegativeInteger 

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

 * **1**: face is created 
 * **2**: face is destroyed 

 ## TLV-TYPE assignments 

 Type                                          | Assigned value      | Assigned value (hex) 
 ------------------------------------------- | ----------------- | -------------------- 
 FaceStatus                                    | 128                 | 0x80 
 LocalUri                                      | 129                 | 0x81 
 ChannelStatus                                 | 130                 | 0x82 
 FaceScope                                     | 132                 | 0x84 
 FacePersistency                               | 133                 | 0x85 
 LinkType                                      | 134                 | 0x86 
 NInInterests                                  | 144                 | 0x90 
 NInDatas                                      | 145                 | 0x91 
 NOutInterests                                 | 146                 | 0x92 
 NOutDatas                                     | 147                 | 0x93 
 NInBytes                                      | 148                 | 0x94 
 NOutBytes                                     | 149                 | 0x95 
 FaceQueryFilter                               | 150                 | 0x96 
 UriScheme                                     | 131                 | 0x83 
 FaceEventNotification                         | 192                 | 0xc0 
 FaceEventKind                                 | 193                 | 0xc1 
 (reserved, formerly FaceFlags)                | 194                 | 0xc2