FaceMgmt » History » Revision 12
Revision 10 (Junxiao Shi, 02/09/2014 09:29 PM) → Revision 12/118 (Alex Afanasyev, 02/10/2014 11:08 AM)
# NFD Face Management protocol
The **Face Management protocol** allows an entity to request NFD daemon create and destroy faces.
The Face Management protocol uses [[Signed Interests]]-Data exchange.
The command request and response follows the [[ControlCommand|NFD Control Command specification]]
## Command format
### Request
Request is a signed Interest with the following name:
/localhost/nfd/faces/<command-verb>/<command-options>/<timestamp>/<SignatureInfo>/<SignatureValue>
\ / \ / \ /
-------- -------- ------------- --------------- -------------------- --------------------
\/ \/ \/
NFD Control Command FaceManager command Signed Interest related information
to FaceManager and command options
Command options is defined as a TLV-encoded `FaceManagementOptions` block.
Each individual command defines a 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
UTF-8 string
### Response
Command response is a Data packet that contains TLV-encoded ``ControlResponse`` `ControlResponse` block, defined in [[ControlCommand|NFD Control Command specification]].
Content of ``ControlResponse`` on success:
Field in ``ControlResponse`` block | Value
---------------------------------- | -----
``StatusCode`` | The response has StatusCode 200
``StatusText`` | "Success"
``<StatusBody>`` | ``FaceManagementOptions`` block, either echoed or with updated ``Uri``---hostname replaced with IP address---and ``FaceId`` fields if the command succeeds.
Content of ``ControlResponse`` on error:
Field in ``ControlResponse`` block | Value
---------------------------------- | -----
``StatusCode`` | 4xx, 500x, or Any other error codes based on RFC2616 status code (4xx, 5xx, [?]) means error.
``StatusText`` | Human-readable description Description of the error
``<StatusBody>`` | Not can be present
in `StatusText` field of `ControlResponse` command.
## URI
The underlying protocol and underlying address of a Face is expressed as a URI.
### UDP unicast
`udp[4|6]://<remote-IP-or-host>[:<remote-port>]`
Examples:
* `udp://192.0.2.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:
* `tcp://192.0.2.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`
## Operations
**Face management protocol** protocol supports two operations:
* create a face (command-verb: `create`)
* destroy a face (command-verb: `destroy`)
### Create a face
**command-verb:** `create`
Required fields in `FaceManagementOptions` block:
* `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 that face is returned.
### Destroy a face
**command-verb:** `destroy`
Required fields in `FaceManagementOptions` block:
* `FaceId`
If the specified face does not exist, this command does nothing, but is still considered successful.
## TLV-TYPE assignments
Type | Assigned value | Assigned value (hex)
------------------------------------------- | ----------------- | --------------------
FaceManagementOptions | 108 | 0x6c
FaceId | 105 | 0x69
Uri | |