Project

General

Profile

FaceMgmt » History » Version 76

Davide Pesavento, 01/25/2018 01:57 PM

1 20 Junxiao Shi
# Face Management
2 1 Junxiao Shi
3 38 Alex Afanasyev
{{toc}}
4
5 20 Junxiao Shi
**Face Management** is a module of [[Management|NFD Management protocol]].
6
It provides:
7 1 Junxiao Shi
8 20 Junxiao Shi
* commands to create and destroy faces
9
* commands to enable and disable [[LocalControlHeader]] features on a face
10
* a dataset of description of all active faces and their counters
11 33 Junxiao Shi
* a dataset of description of all active channels
12 20 Junxiao Shi
* a notification stream for face creating and destroying events
13 1 Junxiao Shi
14 45 Junxiao Shi
Face Management commands, datasets, and notifications are available under namespace `ndn:/localhost/nfd/faces`.
15 12 Alex Afanasyev
16
17 20 Junxiao Shi
## FaceUri
18 1 Junxiao Shi
19 27 Junxiao Shi
A FaceUri represents the underlying protocol and address used by a Face.  
20
Every Face has two FaceUris: one for local endpoint, and the other for remote endpoint.
21 1 Junxiao Shi
22 27 Junxiao Shi
### UDP
23 9 Junxiao Shi
24 30 Junxiao Shi
`udp[4|6]://<IP-or-host>[:<port>]`  
25 2 Alex Afanasyev
26 9 Junxiao Shi
Examples:
27 1 Junxiao Shi
28 20 Junxiao Shi
* `udp4://192.0.2.1:6363` (canonical form)
29
* `udp6://[2001:db8::1]:6363` (canonical form)
30 71 Alex Afanasyev
* `udp6://[fe80::1068:dddb:fe26:fe3f%en0]:6363` (canonical form for link-local IPv6 addresses)
31
* `udp6://[fe80::1068:dddb:fe26:fe3f%25en0]:6363` (equivalent, but not canonical, version of the above FaceUri)
32 1 Junxiao Shi
* `udp://192.0.2.1` (remote-port defaults to 6363)
33
* `udp://example.net:6363`
34
* `udp4://example.net:6363` (resolve hostname to IPv4 address only)
35 9 Junxiao Shi
* `udp6://example.net:6363` (resolve hostname to IPv6 address only)
36 27 Junxiao Shi
* `udp4://224.0.23.170:56363` (multicast, canonical form)
37 1 Junxiao Shi
38 61 Davide Pesavento
LocalUri of a NIC-associated UDP face has the form:
39
40
`udp[4|6]+dev://<NIC>:<port>`
41
42 1 Junxiao Shi
This is only used in face dataset.
43 61 Davide Pesavento
44 51 Junxiao Shi
Examples:
45
46 60 Junxiao Shi
* `udp4+dev://eth1:6363`
47
* `udp6+dev://en0:6363`
48 51 Junxiao Shi
49 1 Junxiao Shi
### TCP
50
51 30 Junxiao Shi
`tcp[4|6]://<IP-or-host>[:<port>]`
52 1 Junxiao Shi
53
Examples:
54
55 20 Junxiao Shi
* `tcp4://192.0.2.1:6363` (canonical form)
56
* `tcp6://[2001:db8::1]:6363` (canonical form)
57 71 Alex Afanasyev
* `tcp6://[fe80::1068:dddb:fe26:fe3f%en0]:6363` (canonical form for link-local IPv6 addresses)
58
* `tcp6://[fe80::1068:dddb:fe26:fe3f%25en0]:6363` (equivalent, but not canonical, version of the above FaceUri)
59 1 Junxiao Shi
* `tcp://192.0.2.1` (remote-port defaults to 6363)
60
* `tcp://example.net:6363`
61 9 Junxiao Shi
* `tcp4://example.net:6363` (resolve hostname to IPv4 address only)
62 1 Junxiao Shi
* `tcp6://example.net:6363` (resolve hostname to IPv6 address only)
63
64
### UNIX stream
65
66 9 Junxiao Shi
`unix://<path>`
67 1 Junxiao Shi
68
Examples:
69
70 61 Davide Pesavento
* `unix:///var/run/nfd.sock` (note that there are three forward-slashes after 'unix:')
71 1 Junxiao Shi
72 30 Junxiao Shi
### File Descriptor
73
74
`fd://<file-descriptor>`
75
76
Examples:
77
78
* `fd://6`
79
80 1 Junxiao Shi
### Ethernet
81 27 Junxiao Shi
82 42 Junxiao Shi
`ether://[<MAC>]`
83 1 Junxiao Shi
84
Examples:
85 42 Junxiao Shi
86
* `ether://[08:00:27:01:01:01]`
87 1 Junxiao Shi
* `ether://[33:33:01:01:01:01]` (multicast)
88
89 30 Junxiao Shi
### Network Device
90 1 Junxiao Shi
91 61 Davide Pesavento
`dev://<interface-name>`
92 30 Junxiao Shi
93
Examples:
94
95 1 Junxiao Shi
* `dev://eth0`
96
97
### Underlying protocol and FaceUri scheme
98
99 67 Junxiao Shi
Underlying protocol     | Remote FaceUri scheme            | Local FaceUri scheme
100
----------------------- | -------------------------------- | --------------------------
101
IPv4 UDP unicast        | udp4                             | udp4
102
IPv6 UDP unicast        | udp6                             | udp6
103
IPv4 UDP multicast      | udp4 (multicast IP)              | udp4 (local IP, same port)
104
IPv4 UDP NIC-associated | udp4                             | udp4+dev
105
IPv6 UDP NIC-associated | udp6                             | udp6+dev
106
IPv4 TCP                | tcp4                             | tcp4
107
IPv6 TCP                | tcp6                             | tcp6
108
UNIX stream             | fd (file descriptor on NFD side) | unix (socket path)
109
Ethernet unicast        | ether                            | dev
110
Ethernet multicast      | ether                            | dev
111
WebSocket               | wsclient                         | ws
112 46 Junxiao Shi
113
## Static Face Attributes
114
115
**FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes.
116
117
* non-local(=0)
118
* local(=1)
119
120
**FacePersistency** indicates whether the face is persistent.
121
122
* on-demand(=1), face closes if it remains idle for some time
123
* persistent(=0), face remains open until it's explicitly destroyed or there's a transport failure
124
* permanent(=2), face remains open until it's explicitly destroyed; transport failures will be recovered internally
125
126
**LinkType** indicates the type of communication link.
127
128
* point-to-point(=0), communication with one peer
129
* multi-access(=1), communication with a multicast group
130 75 Davide Pesavento
* ad-hoc(=2), communication over a wireless ad hoc network
131 52 Junxiao Shi
132
**LocalFieldsEnabled** indicates whether the face allows [[NDNLPv2]] NextHopFaceId, CachePolicy, IncomingFaceId fields.
133
134
* yes(=1), allows these fields; this is valid only if FaceScope=local
135
* no(=0), disallows these fields
136
137 74 Eric Newberry
**LpReliabilityEnabled** indicates whether the face has the [[NDNLPv2]] reliability feature enabled.
138 69 Eric Newberry
139
* yes(=1), enables this feature
140
* no(=0), disables this feature
141 1 Junxiao Shi
142 74 Eric Newberry
**CongestionMarkingEnabled** indicates whether the face has congestion marking based upon send queue length enabled.
143
144
* yes(=1), enables this feature
145
* no(=0), disables this feature
146
147
**BaseCongestionMarkingInterval** indicates the base marking interval for congestion marking.
148
149 76 Davide Pesavento
The value of this attribute is the base marking interval in nanoseconds.
150 74 Eric Newberry
151
**DefaultCongestionThreshold** indicates the default congestion threshold if the face does not support retrieving the send queue capacity.
152
153 76 Davide Pesavento
The value of this attribute is the default congestion threshold in bytes.
154 74 Eric Newberry
155 52 Junxiao Shi
### Flags and Mask
156
157
Some attributes are collected as inclusive OR into a **Flags** field in commands and datasets.
158
These attributes are: (bit 0 is the least significant bit)
159
160
* bit 0: LocalFieldsEnabled
161 1 Junxiao Shi
* bit 1: LpReliabilityEnabled
162 74 Eric Newberry
* bit 2: CongestionMarkingEnabled
163 55 Junxiao Shi
164 1 Junxiao Shi
## Control Commands
165
166 20 Junxiao Shi
[[ControlCommand]] **management-module**: `faces`
167 41 Junxiao Shi
168
### Create a face
169 1 Junxiao Shi
170
**command-verb**: `create`
171 46 Junxiao Shi
172
ControlParameters fields:
173 1 Junxiao Shi
174
* **Uri** (required): canonical remote FaceUri of the face to create.
175 72 Davide Pesavento
* **LocalUri** (optional): canonical local FaceUri of the face to create; e.g., FaceUri of the local interface for an Ethernet unicast face.
176 1 Junxiao Shi
* **FacePersistency** (optional): either *persistent* or *permanent*; creating *on-demand* faces is not permitted. The default is *persistent*. See "static face attributes" for more information.
177 74 Eric Newberry
* **BaseCongestionMarkingInterval** (optional): see "static face attributes".
178
* **DefaultCongestionThreshold** (optional): see "static face attributes".
179 72 Davide Pesavento
* **Flags** (optional): see "static face attributes".
180 73 Junxiao Shi
* **Mask** (optional): must be specified if Flags is present, or omitted if Flags is omitted.
181 1 Junxiao Shi
182 65 Davide Pesavento
This command allows the creation of UDP unicast, Ethernet unicast, and TCP faces only.  
183 50 Junxiao Shi
If the command succeeds, the \<body> of the ControlResponse block contains the ControlParameters describing the current properties of the created face:
184 1 Junxiao Shi
185 64 Alex Afanasyev
* **FaceId**
186 68 Junxiao Shi
* **Uri**
187 64 Alex Afanasyev
* **LocalUri**
188 1 Junxiao Shi
* **FacePersistency**
189 74 Eric Newberry
* **BaseCongestionMarkingInterval**
190
* **DefaultCongestionThreshold**
191 68 Junxiao Shi
* **Flags**: contains effective values for *LocalFieldsEnabled* and *LpReliabilityEnabled* bits.
192
193 52 Junxiao Shi
If this creation would conflict with an existing face (e.g., same underlying protocol and remote endpoint, or a NIC-associated permanent face), 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.
194 66 Davide Pesavento
195 52 Junxiao Shi
If the request attempts to create a face other than UDP unicast, Ethernet unicast, or TCP, or if a static property specified in the request is not acceptable, the command fails with StatusCode 406.
196
197 1 Junxiao Shi
If face creation fails due to a socket error (e.g. TCP connection timeout), the command fails with StatusCode 504.
198
199 20 Junxiao Shi
### Update static properties
200 1 Junxiao Shi
201 20 Junxiao Shi
**command-verb**: `update`
202 52 Junxiao Shi
203 1 Junxiao Shi
ControlParameters fields:
204 64 Alex Afanasyev
205
* **FaceId** (optional)
206 1 Junxiao Shi
* **FacePersistency** (optional): *on-demand* or *persistent* or *permanent*  
207
  See "static face attributes" for more information.
208 74 Eric Newberry
* **BaseCongestionMarkingInterval** (optional): see "static face attributes".
209
* **DefaultCongestionThreshold** (optional): see "static face attributes".
210
* **Flags** (optional): allows *LocalFieldsEnabled*, *LpReliabilityEnabled*, and *CongestionMarkingEnabled* only - see "static face attributes".
211 73 Junxiao Shi
* **Mask** (optional): must be specified if Flags is present, or omitted if Flags is omitted.
212 52 Junxiao Shi
213
FaceId is the FaceId returned in [[FaceMgmt|Face Management]].
214
If FaceId is omitted or is set to zero, it is implied as the requesting face (self updating).  
215 1 Junxiao Shi
If face does not exist, this command fails with StatusCode 404.
216
217
Static properties of the face is updated.
218 55 Junxiao Shi
If an optional property field is omitted or a bitfield is zero in Mask, that static property remains unchanged.
219
If no static property is changed, this command does nothing, but is still considered successful.
220
221
If the command succeeds, \<body> in ControlResponse block contains ControlParameters describing the current properties of the face:
222 1 Junxiao Shi
223
* **FaceId**
224
* **FacePersistency**
225 74 Eric Newberry
* **BaseCongestionMarkingInterval**
226
* **DefaultCongestionThreshold**
227 70 Eric Newberry
* **Flags**: contains effective values for *LocalFieldsEnabled* and *LpReliabilityEnabled* bits
228 1 Junxiao Shi
229 52 Junxiao Shi
If any of the requested changes is invalid, none of the changes should be performed, and this command fails with StatusCode 409.
230
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.
231 62 Davide Pesavento
If the request had been sent without those fields (or bitfields in Mask), it would have been successful.
232 20 Junxiao Shi
233 1 Junxiao Shi
### Destroy a face
234 20 Junxiao Shi
235 26 Junxiao Shi
**command-verb:** `destroy`
236 20 Junxiao Shi
237 39 Junxiao Shi
ControlParameters fields:
238 1 Junxiao Shi
239 64 Alex Afanasyev
* **FaceId** (required)
240 39 Junxiao Shi
241 1 Junxiao Shi
If the specified face does not exist, this command does nothing, but is still considered successful.
242
243 40 Junxiao Shi
## Face Dataset
244 1 Junxiao Shi
245
Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`.
246 39 Junxiao Shi
247
Each face is represented by a **FaceStatus** block:
248 1 Junxiao Shi
249 39 Junxiao Shi
    FaceStatus      ::= FACE-STATUS-TYPE TLV-LENGTH
250
                          FaceId
251 37 Junxiao Shi
                          Uri (remote FaceUri)
252 39 Junxiao Shi
                          LocalUri
253 1 Junxiao Shi
                          ExpirationPeriod?
254
                          FaceScope
255
                          FacePersistency
256
                          LinkType
257 74 Eric Newberry
                          BaseCongestionMarkingInterval
258
                          DefaultCongestionThreshold
259 1 Junxiao Shi
                          Flags
260
                          NInInterests
261 67 Junxiao Shi
                          NInData
262 39 Junxiao Shi
                          NInNacks
263 67 Junxiao Shi
                          NOutInterests
264 49 Junxiao Shi
                          NOutData
265
                          NOutNacks
266 46 Junxiao Shi
                          NInBytes
267
                          NOutBytes
268
269
    Uri             ::= URI-TYPE TLV-LENGTH
270 39 Junxiao Shi
                          FaceUri in UTF-8 encoding
271 46 Junxiao Shi
272 1 Junxiao Shi
    LocalUri        ::= LOCAL-URI-TYPE TLV-LENGTH
273 46 Junxiao Shi
                          FaceUri in UTF-8 encoding
274 1 Junxiao Shi
    
275
    ; other TLVs have nonNegativeInteger as value
276
277 40 Junxiao Shi
* **Uri** is a FaceUri representing remote endpoint.
278 39 Junxiao Shi
* **LocalUri** is a FaceUri representing local endpoint.
279 40 Junxiao Shi
* **ExpirationPeriod** is the remaining lifetime of this face.
280 46 Junxiao Shi
  If this field is omitted, the face has infinite lifetime.
281 40 Junxiao Shi
  Currently, this is applicable to on-demand datagram faces only.
282 46 Junxiao Shi
* **FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes.
283 1 Junxiao Shi
  See "static face attributes" for more information.
284 40 Junxiao Shi
* **FacePersistency** indicates whether the face is persistent.
285 1 Junxiao Shi
  See "static face attributes" for more information.
286 52 Junxiao Shi
* **LinkType** indicates the type of communication link
287 1 Junxiao Shi
  See "static face attributes" for more information.
288 76 Davide Pesavento
* **BaseCongestionMarkingInterval** indicates the base interval for congestion marking (in nanoseconds).
289 1 Junxiao Shi
  See "static face attributes" for more information.
290 76 Davide Pesavento
* **DefaultCongestionThreshold** indicates the default threshold for congestion if the face does not support retrieving the send queue capacity (in bytes).
291 74 Eric Newberry
  See "static face attributes" for more information.
292
* **Flags** contains these bitfields: *LocalFieldsEnabled*, *LpReliabilityEnabled*, *CongestionMarkingEnabled*.
293
  See "static face attributes" for more information.
294 46 Junxiao Shi
* **NInInterests**: number of incoming Interest packets since the face is established.
295 67 Junxiao Shi
* **NInData** counts the number of incoming Data packets since the face is established.
296 46 Junxiao Shi
* **NInNacks** counts the number of incoming Nack packets since the face is established.
297 1 Junxiao Shi
* **NOutInterests** counts the number of outgoing Interest packets since the face is established.
298 67 Junxiao Shi
* **NOutData** counts the number of outgoing Data packets since the face is established.
299 37 Junxiao Shi
* **NOutNacks** counts the number of outgoing Nack packets since the face is established.
300
* **NInBytes** counts the number of bytes of link layer packets received via this face.
301
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
302
* **NOutBytes** counts the number of bytes of link layer packets sent via this face.
303
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
304
305
### Query Operation
306 1 Junxiao Shi
307 37 Junxiao Shi
The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter.
308
309
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.
310
311
    FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH
312 40 Junxiao Shi
                          FaceId?
313
                          UriScheme?
314
                          Uri?
315 37 Junxiao Shi
                          LocalUri?
316
                          FaceScope?
317 1 Junxiao Shi
                          FacePersistency?
318 37 Junxiao Shi
                          LinkType?
319
    
320
    UriScheme       ::= URI-SCHEME-TYPE TLV-LENGTH
321
                          string in UTF-8
322
323 40 Junxiao Shi
* **FaceId** permits a face if its FaceId equals the value
324
* **UriScheme** permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value
325
* **Uri** permits a face if its remote FaceUri equals the value
326 1 Junxiao Shi
* **LocalUri** permits a face if its local FaceUri equals the value
327
* **FaceScope** permits a face if its *FaceScope* attribute equals the value
328 39 Junxiao Shi
* **FacePersistency** permits a face if its *FacePersistency* attribute equals the value
329 37 Junxiao Shi
* **LinkType** permits a face if its *LinkType* attribute equals the value
330
331
A face must satisfy ALL conditions to satisfy the filter.
332 1 Junxiao Shi
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>`).
333 37 Junxiao Shi
334 41 Junxiao Shi
Examples of filters:
335 1 Junxiao Shi
336 75 Davide Pesavento
* a specific face: `FaceId=260`
337
* a specific TCP tunnel: `Uri=tcp4://192.0.2.1:6363`  
338
  (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)
339
* all TCP tunnels: `UriScheme=tcp`  
340
  (note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6")
341
* all UDP multi-access faces: `UriScheme=udp` && `LinkType=multi-access`
342
* all Ethernet faces: `UriScheme=ether`  
343
  (note: UriScheme matches against both local and remote FaceUri, "dev" also works)
344 1 Junxiao Shi
* all faces: no condition  
345 75 Davide Pesavento
  (note: this is equivalent to face dataset, and face dataset should be preferred for this purpose)
346 33 Junxiao Shi
347
## Channel Dataset
348
349 20 Junxiao Shi
Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`.
350 1 Junxiao Shi
351
Each channel is represented by a **ChannelStatus** block:
352 20 Junxiao Shi
353
    ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
354 21 Alex Afanasyev
                          LocalUri
355 20 Junxiao Shi
356 1 Junxiao Shi
* **LocalUri** is a FaceUri representing local endpoint.
357 21 Alex Afanasyev
358 37 Junxiao Shi
## Face Status Change Notification
359
360
Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`.
361 1 Junxiao Shi
Notifications of all faces are sent into the same notification stream.
362 37 Junxiao Shi
363
The Content of each notification Data packet is a `FaceEventNotification` block:
364 23 Alex Afanasyev
365 37 Junxiao Shi
    FaceEventNotification ::= FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
366 40 Junxiao Shi
                                FaceEventKind
367
                                FaceId
368
                                Uri
369 25 Junxiao Shi
                                LocalUri
370 23 Alex Afanasyev
                                FaceScope
371
                                FacePersistency
372 58 Eric Newberry
                                LinkType
373 25 Junxiao Shi
                                Flags
374 23 Alex Afanasyev
    
375 9 Junxiao Shi
    FaceEventKind         ::= FACE-EVENT-KIND-TYPE TLV-LENGTH
376
                                nonNegativeInteger
377
378 1 Junxiao Shi
**FaceEventKind** indicates the kind of event. Its possible values are:
379 34 Junxiao Shi
380 33 Junxiao Shi
* **1**: face is created
381 57 Eric Newberry
* **2**: face is destroyed
382
* **3**: face goes UP (from DOWN state)
383 1 Junxiao Shi
* **4**: face goes DOWN (from UP state)
384 32 Junxiao Shi
385 20 Junxiao Shi
## TLV-TYPE assignments
386
387
Type                                        | Assigned value    | Assigned value (hex)
388 39 Junxiao Shi
------------------------------------------- | ----------------- | --------------------
389 40 Junxiao Shi
FaceStatus                                  | 128               | 0x80
390
LocalUri                                    | 129               | 0x81
391
ChannelStatus                               | 130               | 0x82
392 75 Davide Pesavento
UriScheme                                   | 131               | 0x83
393 1 Junxiao Shi
FaceScope                                   | 132               | 0x84
394
FacePersistency                             | 133               | 0x85
395
LinkType                                    | 134               | 0x86
396 74 Eric Newberry
BaseCongestionMarkingInterval               | 135               | 0x87
397 1 Junxiao Shi
DefaultCongestionThreshold                  | 136               | 0x88
398 67 Junxiao Shi
NInInterests                                | 144               | 0x90
399 48 Junxiao Shi
NInData                                     | 145               | 0x91
400 1 Junxiao Shi
NInNacks                                    | 151               | 0x97
401 67 Junxiao Shi
NOutInterests                               | 146               | 0x92
402 1 Junxiao Shi
NOutData                                    | 147               | 0x93
403
NOutNacks                                   | 152               | 0x98
404
NInBytes                                    | 148               | 0x94
405 39 Junxiao Shi
NOutBytes                                   | 149               | 0x95
406 1 Junxiao Shi
FaceQueryFilter                             | 150               | 0x96
407
FaceEventNotification                       | 192               | 0xc0
408
FaceEventKind                               | 193               | 0xc1
409
(reserved, formerly FaceFlags)              | 194               | 0xc2