FaceMgmt » History » Revision 32
Revision 30 (Junxiao Shi, 03/28/2014 11:26 PM) → Revision 32/118 (Junxiao Shi, 03/29/2014 09:06 PM)
# 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 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 ## Control Commands [[ControlCommand]] **management-module**: `faces` ### Create a face **command-verb**: `create` ControlParameters fields: * Uri (required): a UDP unicast or TCP FaceUri 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 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: * LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId 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 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: blocks: FaceStatus := FACE-STATUS-TYPE TLV-LENGTH FaceId Uri (remote FaceUri) LocalUri FaceFlags NInInterests NInDatas NOutInterests NOutDatas LocalUri := ::= LOCAL-URI-TYPE TLV-LENGTH RFC3986 URI in UTF-8 encoding FaceFlags := FACE-FLAGS-TYPE TLV-LENGTH nonNegativeInteger 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 * **Uri** Uri is a FaceUri representing remote endpoint. * **LocalUri** LocalUri is a FaceUri representing local endpoint. * **FaceFlags** NInInterests is a bitset providing additional information about the face. The following bits are currently defined: * **1**: face is local * **2**: face is on demand - accepted incoming connection, instead of initiated outgoing connection * **NInInterests** is the total number of incoming Interests since the face is established. * **NInDatas** NInDatas is the total number of incoming Datas since the face is established. * **NOutInterests** NOutInterests is the total number of outgoing Interests since the face is established. * **NOutDatas** 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`. 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 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 * **2**: face is destroyed **FaceFlags** is a bitset, providing additional information about the face. The following bits are currently defined: * **1**: face is local * **2**: face is on demand - accepted incoming connection, instead of initiated outgoing connection ## TLV-TYPE assignments Type | Assigned value | Assigned value (hex) ------------------------------------------- | ----------------- | -------------------- FaceStatus | 128 | 0x80 LocalUri | 129 | 0x81 FaceFlags | 194 | 0xc2 NInInterests | 144 | 0x90 NInDatas | 145 | 0x91 NOutInterests | 146 | 0x92 NOutDatas | 147 | 0x93 FaceEventNotification | 192 | 0xc0 FaceEventKind | 193 | 0xc1 FaceFlags | 194 | 0xc2