Project

General

Profile

FaceMgmt » History » Revision 114

Revision 113 (Eric Newberry, 03/26/2020 08:32 PM) → Revision 114/118 (Davide Pesavento, 03/26/2020 11:38 PM)

# Face Management 

 {{>toc}} 

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

 * commands to create, modify, and destroy faces 
 * a dataset containing the description of all active faces and their counters 
 * a dataset containing the description of all active channels 
 * a notification stream for face 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) 
 * `udp6://[fe80::1068:dddb:fe26:fe3f%en0]:6363` (canonical form for link-local IPv6 addresses) 
 * `udp6://[fe80::1068:dddb:fe26:fe3f%25en0]:6363` (equivalent, but not canonical, version of the above FaceUri) 
 * `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) 

 LocalUri of a netdev-bound UDP face has the form: 

 `udp[4|6]+dev://<interface-name>:<port>` 

 This is only used in face dataset. 

 Examples: 

 * `udp4+dev://eth1:6363` 
 * `udp6+dev://en0:6363` 

 ### TCP 

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

 Examples: 

 * `tcp4://192.0.2.1:6363` (canonical form) 
 * `tcp6://[2001:db8::1]:6363` (canonical form) 
 * `tcp6://[fe80::1068:dddb:fe26:fe3f%en0]:6363` (canonical form for link-local IPv6 addresses) 
 * `tcp6://[fe80::1068:dddb:fe26:fe3f%25en0]:6363` (equivalent, but not canonical, version of the above FaceUri) 
 * `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 that 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://<interface-name>` 

 Examples: 

 * `dev://eth0` 

 ### Underlying protocol and FaceUri schemes 

 Underlying protocol       | Remote FaceUri scheme              | Local FaceUri scheme 
 ----------------------- | -------------------------------- | -------------------------- 
 IPv4 UDP unicast          | udp4                               | udp4 
 IPv6 UDP unicast          | udp6                               | udp6 
 IPv4 UDP multicast        | udp4 (multicast group)             | udp4 
 IPv6 UDP multicast        | udp6 (multicast group)             | udp6 
 IPv4 UDP netdev-bound     | udp4                               | udp4+dev 
 IPv6 UDP netdev-bound     | udp6                               | udp6+dev 
 IPv4 TCP                  | tcp4                               | tcp4 
 IPv6 TCP                  | tcp6                               | tcp6 
 UNIX stream               | fd (file descriptor on NFD side) | unix (socket path) 
 Ethernet unicast          | ether                              | dev 
 Ethernet multicast        | ether                              | dev 
 WebSocket                 | wsclient                           | ws 

 ## Face Properties 

 **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 
 * ad-hoc(=2), communication over a wireless ad hoc network 

 **LocalFieldsEnabled** indicates whether the face allows [[NDNLPv2]] NextHopFaceId, CachePolicy, IncomingFaceId fields. 

 * yes(=1), allows these fields; this is valid only if FaceScope=local 
 * no(=0), disallows these fields 

 **LpReliabilityEnabled** indicates whether the face has the [[NDNLPv2]] reliability feature enabled. 

 * yes(=1), enables this feature 
 * no(=0), disables this feature 

 **CongestionMarkingEnabled** indicates whether the face has congestion marking based upon send queue length enabled. 

 * yes(=1), enables this feature 
 * no(=0), disables this feature 

 **BaseCongestionMarkingInterval** indicates the base marking interval for congestion marking. 

 * The value of this attribute is the base marking interval in nanoseconds, which is used to compute the interval at which congested packets will be marked. 

 **DefaultCongestionThreshold** indicates the default congestion threshold if the face does not support retrieving the send queue capacity. 

 * The value of this attribute is the default congestion threshold in bytes. 

 **Mtu** contains a user-specified MTU to override the automatic MTU of the transport. 

 * The value of this attribute is the override MTU of the transport in bytes. The face will use the lesser of this value and the automatic MTU of the underlying transport. 

 ### Flags and Mask 

 Some attributes are collected as inclusive OR into a **Flags** field in commands and datasets. 
 These attributes are: (bit 0 is the least significant bit) 

 * bit 0: LocalFieldsEnabled 
 * bit 1: LpReliabilityEnabled 
 * bit 2: CongestionMarkingEnabled 

 ## Control Commands 

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

 ### Create a face 

 **command-verb**: `create` 

 ControlParameters fields: 

 * **Uri** (required): canonical remote FaceUri of the face to create. 
 * **LocalUri** (optional): canonical local FaceUri of the face to create; e.g., FaceUri of the local interface for an Ethernet unicast face. 
 * **FacePersistency** (optional): either *persistent* or *permanent*; creating *on-demand* faces is not permitted. The default is *persistent*. See "face properties" for more information. 
 * **BaseCongestionMarkingInterval** (optional): see "face properties". 
 * **DefaultCongestionThreshold** (optional): see "face properties". 
 * **Mtu** (optional): see "face properties". 
 * **Flags** (optional): see "face properties". 
 * **Mask** (optional): MUST be specified if *Flags* is present, and omitted if *Flags* is omitted. 

 This command allows the creation of UDP unicast, Ethernet unicast, and TCP faces only.   
 If the command succeeds, the \<body> of the ControlResponse block contains the ControlParameters describing the current properties of the created face: 

 * **FaceId** 
 * **Uri** 
 * **LocalUri** 
 * **FacePersistency** 
 * **BaseCongestionMarkingInterval** (optional) 
 * **DefaultCongestionThreshold** (optional) 
 * **Mtu** (optional): effective MTU, see below. 
 * **Flags**: contains effective values for the *LocalFieldsEnabled*, *LpReliabilityEnabled*, and *CongestionMarkingEnabled* bits. 

 If this creation would conflict with an existing face (e.g., same underlying protocol and remote endpoint), the command fails with StatusCode 409, and the \<body> of the ControlResponse block contains the ControlParameters describing the existing face, with the same fields as above. 

 If the request attempts to create a face other than UDP unicast, Ethernet unicast, or TCP, or if a property specified in the request is not acceptable, the command fails with StatusCode 406. 

 If face creation fails due to a socket error (e.g. TCP connection timeout), the command fails with StatusCode 504. 

 If *BaseCongestionMarkingInterval* or *DefaultCongestionThreshold* are omitted from the ControlParameters sent with the creation command, the omitted properties are left at their implementation-defined default values. 

 If *Mtu* is omitted from the ControlParameters sent with the creation command, no override MTU is specified and the automatic MTU of the transport will be used. A forwarder MAY impose an implementation-defined minimum and maximum to the override MTU specified during face creation. The current minimum and maximum in NFD are 64 and `MAX_NDN_PACKET_SIZE` (8800) bytes, respectively. In the response, the *Mtu* field in ControlParameters contains the effective MTU of the face (in bytes), capped at a maximum of `MAX_NDN_PACKET_SIZE` (8800 bytes), even if the MTU of the underlying transport is infinite. If *Mtu* is omitted from the response, the face and/or forwarder does not support MTU reporting. 

 ### Update the properties of a face 

 **command-verb**: `update` 

 ControlParameters fields: 

 * **FaceId** (optional) 
 * **FacePersistency** (optional): one of *on-demand*, *persistent*, or *permanent*. See "face properties" for more information. 
 * **BaseCongestionMarkingInterval** (optional): see "face properties". 
 * **DefaultCongestionThreshold** (optional): see "face properties". 
 * **Mtu** (optional): see "face properties". 
 * **Flags** (optional): allows *LocalFieldsEnabled*, *LpReliabilityEnabled*, and *CongestionMarkingEnabled* only. See "face properties" for more information. 
 * **Mask** (optional): MUST be specified if *Flags* is present, and omitted if *Flags* is omitted. 

 If *FaceId* is omitted or is set to zero, it is implied to be that of the requesting face (self-update). 
 If the face does not exist, the command fails with StatusCode 404. 

 The properties of the face are updated as indicated. 
 If an optional property field is omitted or a bitfield is zero in *Mask*, that property remains unchanged. 
 If no properties are changed, this command does nothing, but is still considered successful. 

 As with `faces/create`, a forwarder may bound the or clamp the allowed MTU values specified when updating a face. The implementation-specific bounds still apply for NFD. 

 If the command succeeds, \<body> in ControlResponse block contains ControlParameters describing the current properties of the face: 

 * **FaceId** 
 * **FacePersistency** 
 * **BaseCongestionMarkingInterval** (optional) 
 * **DefaultCongestionThreshold** (optional) 
 * **Mtu** (optional): effective MTU. 
 * **Flags**: contains effective values for *LocalFieldsEnabled*, *LpReliabilityEnabled*, and *CongestionMarkingEnabled* bits. 

 If any of the requested changes is invalid, none of the changes should be performed, and this command fails with StatusCode 409. 
 The \<body> in ControlResponse block contains ControlParameters that includes only invalid fields; if some of the bit fields chosen in *Flags*+*Mask* is invalid, the \<body> block should also contain a *Mask* field indicating which bits are invalid, and echo back the original *Flags* field. 
 If the request had been sent without those fields (or bitfields in *Mask*), it would have been successful. 

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

 ## 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 
                           LocalUri 
                           ExpirationPeriod? 
                           FaceScope 
                           FacePersistency 
                           LinkType 
                           BaseCongestionMarkingInterval? 
                           DefaultCongestionThreshold? 
                           Mtu? 
                           NInInterests 
                           NInData 
                           NInNacks 
                           NOutInterests 
                           NOutData 
                           NOutNacks 
                           NInBytes 
                           NOutBytes 
                           Flags 

     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 "face properties" for more information. 
 * **FacePersistency** indicates whether the face is persistent. 
   See "face properties" for more information. 
 * **LinkType** indicates the type of communication link 
   See "face properties" for more information. 
 * **BaseCongestionMarkingInterval** indicates the base interval used to compute the interval at which congested packets will be marked (in nanoseconds). 
   See "face properties" for more information. 
 * **DefaultCongestionThreshold** indicates the default threshold for congestion if the face does not support retrieving the send queue capacity (in bytes). 
   See "face properties" for more information. 
 * **Mtu** contains the effective MTU of the face (in bytes), capped at `MAX_NDN_PACKET_SIZE` (8800 bytes), even if the MTU of the underlying transport is infinite. If this field is omitted, the forwarder and/or face does not support MTU reporting. 
 * **NInInterests**: number of incoming Interest packets since the face is established. 
 * **NInData** 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. 
 * **NOutData** 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. 
 * **Flags** contains these bitfields: *LocalFieldsEnabled*, *LpReliabilityEnabled*, *CongestionMarkingEnabled*. 
   See "face properties" for more information. 

 ### 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 domain name, include port number) 
 * all TCP tunnels: `UriScheme=tcp`   
   (note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6") 
 * all UDP multi-access faces: `UriScheme=udp` && `LinkType=multi-access` 
 * all Ethernet faces: `UriScheme=ether`   
   (note: UriScheme matches against 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 the channel's 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 
                                 Flags 
    
     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 
 * 3 = face goes UP (from DOWN state) 
 * 4 = face goes DOWN (from UP state) 

 ## TLV-TYPE assignments 

 Type                                          | Assigned value      | Assigned value (hex) 
 ------------------------------------------- | ----------------- | -------------------- 
 FaceStatus                                    | 128                 | 0x80 
 LocalUri                                      | 129                 | 0x81 
 ChannelStatus                                 | 130                 | 0x82 
 UriScheme                                     | 131                 | 0x83 
 FaceScope                                     | 132                 | 0x84 
 FacePersistency                               | 133                 | 0x85 
 LinkType                                      | 134                 | 0x86 
 BaseCongestionMarkingInterval                 | 135                 | 0x87 
 DefaultCongestionThreshold                    | 136                 | 0x88 
 Mtu                                           | 137                 | 0x89 
 NInInterests                                  | 144                 | 0x90 
 NInData                                       | 145                 | 0x91 
 NInNacks                                      | 151                 | 0x97 
 NOutInterests                                 | 146                 | 0x92 
 NOutData                                      | 147                 | 0x93 
 NOutNacks                                     | 152                 | 0x98 
 NInBytes                                      | 148                 | 0x94 
 NOutBytes                                     | 149                 | 0x95 
 FaceQueryFilter                               | 150                 | 0x96 
 FaceEventNotification                         | 192                 | 0xc0 
 FaceEventKind                                 | 193                 | 0xc1 
 (reserved, formerly FaceFlags)                | 194                 | 0xc2