FaceMgmt » History » Revision 39
Revision 38 (Alex Afanasyev, 08/11/2014 12:07 PM) → Revision 39/118 (Junxiao Shi, 08/18/2014 03:26 PM)
# 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 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:
FaceStatus ::= FACE-STATUS-TYPE TLV-LENGTH
FaceId
Uri (remote FaceUri)
LocalUri
ExpirationPeriod?
ScopePolicy
CreationReason
ChannelCategory
FaceFlags
NInInterests
NInDatas
NOutInterests
NOutDatas
NInBytes
NOutBytes
LocalUri ::= LOCAL-URI-TYPE TLV-LENGTH
RFC3986 URI in UTF-8 encoding
ScopePolicy FaceFlags ::= SCOPE-POLICY-TYPE FACE-FLAGS-TYPE TLV-LENGTH
nonNegativeInteger
CreationReason NInInterests ::= CREATION-REASON-TYPE TLV-LENGTH
nonNegativeInteger
ChannelCategory ::= CHANNEL-CATEGORY-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
NInBytes ::= N-IN-BYTES-TYPE TLV-LENGTH
nonNegativeInteger
NOutBytes ::= N-OUT-BYTES-TYPE TLV-LENGTH
nonNegativeInteger
* **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.
* **ScopePolicy** indicates whether **FaceFlags** is a bitset providing additional information about the face.
The following bits are currently defined:
* **1**: face is local for [[ScopeControl|scope control]] purposes.
* non-local(=0)
* local(=1)
* **CreationReason** indicates why the **2**: face is created.
* initiated(=0), created by `faces/create` command
* on-demand(=1), on demand - accepted incoming connection, instead of initiated outgoing connection
* **ChannelCategory** indicates the category of communication channel
* point-to-point(=0), communicate with one peer
* multi-access(=1), communicate with zero or more peers
* **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.
* **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?
ScopePolicy?
CreationReason?
ChannelCategory? IsMultiAccess?
UriScheme ::= URI-SCHEME-TYPE TLV-LENGTH
string in UTF-8
IsMultiAccess ::= IS-MULTI-ACCESS-TYPE TLV-LENGTH
(0x00 | 0x01)
* **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
* **ScopePolicy** **IsMultiAccess** permits a face if its *ScopePolicy* *isMultiAccess* attribute equals the value
* **CreationReason** permits a face if its *CreationReason* attribute equals the value
* **ChannelCategory** permits a face if its *ChannelCategory* attribute equals the value
A face must satisfy ALL conditions to satisfy the filter.
Faces that satisfy the filter are represented represents 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 what would appear in face dataset: 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 & ChannelCategory=multi-access IsMultiAccess=1
* 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
ScopePolicy
CreationReason
ChannelCategory FaceFlags
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
ScopePolicy FaceFlags | 132 194 | 0x84 0xc2
CreationReason | 133 | 0x85
ChannelCategory | 134 | 0x86
NInInterests | 144 | 0x90
NInDatas | 145 | 0x91
NOutInterests | 146 | 0x92
NOutDatas | 147 | 0x93
NInBytes | 148 | 0x94
NOutBytes | 149 | 0x95
UriScheme | 131 | 0x83
IsMultiAccess | 132 | 0x84
FaceEventNotification | 192 | 0xc0
FaceEventKind | 193 | 0xc1
(reserved, formerly FaceFlags) | 194 | 0xc2