FaceMgmt » History » Revision 20
Revision 17 (Alex Afanasyev, 02/15/2014 09:13 PM) → Revision 20/118 (Junxiao Shi, 03/18/2014 11:28 AM)
# NFD Face Management protocol The **Face Management** is a module of [[Management|NFD Management protocol]]. It provides: * commands protocol** allows an entity to request NFD daemon create and destroy faces * commands faces. The Face Management protocol uses [[Command Interests|Signed Command Interests]] to enable authenticate each issued command. ## Command format ### Request Request is a [[Command Interests|Command Interest]] with the following name: /localhost/nfd/faces/<command-verb>/<command-options>/..................... \ / \ / \ / -------- -------- ------------- --------------- -------- --------- \/ \/ \/ NFD Control Command FaceManager command Command Interest to FaceManager and disable [[LocalControlHeader]] features on command options related information Command options is defined as a face TLV-encoded `FaceManagementOptions` block. * Each individual command defines a dataset subset of required and optional elements in the `FaceManagementOptions` block. FaceManagementOptions ::= FACE-MANAGEMENT-OPTIONS-TYPE TLV-LENGTH FaceId? Uri? FaceId ::= FACEID-TYPE TLV-LENGTH nonNegativeInteger Uri ::= URI-TYPE TLV-LENGTH RFC3986 URI in UTF-8 encoding ### Response Command response is a Data packet that contains TLV-encoded ``ControlResponse`` block, defined in [[ControlCommand|NFD Control Command specification]]. Content of ``ControlResponse`` on success: Field in ``ControlResponse`` block | Value ---------------------------------- | ----- ``StatusCode`` | 200 ``StatusText`` | "Success" ``<StatusBody>`` | ``FaceManagementOptions`` block, either echoed or with updated ``Uri``---hostname replaced with IP address---and ``FaceId`` fields Content of ``ControlResponse`` on error: Field in ``ControlResponse`` block | Value ---------------------------------- | ----- ``StatusCode`` | 4xx, 500x, or other error codes based on RFC2616 ``StatusText`` | Human-readable description of all active faces and their counters the error * a notification stream for face creating and destroying events ``<StatusBody>`` | Not present Face Management commands, datasets, and notifications are published in namespace `ndn:/localhost/nfd/faces`. ## FaceUri URI A FaceUri indicates the The underlying protocol and underlying address of a Face. Face is expressed as a URI. ### UDP unicast `udp[4|6]://<remote-IP-or-host>[:<remote-port>]` Examples: * `udp4://192.0.2.1:6363` `udp://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://[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: * `tcp4://192.0.2.1:6363` `tcp://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://[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` ## Control Commands Operations [[ControlCommand]] **management-module**: `faces` **Face management protocol** protocol supports two operations: * create a face (command-verb: `create`) * destroy a face (command-verb: `destroy`) ### Create a face **command-verb**: **command-verb:** `create` ControlParameters fields: Required fields in `FaceManagementOptions` block: * Uri (required): a FaceUri that represents a UDP unicast tunnel or a TCP tunnel `Uri` 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 URI 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: Required fields in `FaceManagementOptions` block: * FaceId (required) `FaceId` 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 `FaceEvent` block: FaceEvent := FACE-EVENT-TYPE TLV-LENGTH FaceId Uri FaceEventKind FaceEventKind := FACE-EVENT-KIND-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 ## TLV-TYPE assignments Type | Assigned value | Assigned value (hex) ------------------------------------------- | ----------------- | -------------------- FaceStatus FaceManagementOptions | 128 108 | 0x80 0x6c NInInterests FaceId | 144 105 | 0x90 0x69 NInDatas Uri | 145 114 | 0x91 NOutInterests | 146 | 0x92 NOutDatas | 147 | 0x93 FaceEvent | 192 | 0xc0 FaceEventKind | 193 | 0xc1 0x72