Project

General

Profile

FaceMgmt » History » Version 74

Eric Newberry, 01/25/2018 01:16 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 52 Junxiao Shi
131
**LocalFieldsEnabled** indicates whether the face allows [[NDNLPv2]] NextHopFaceId, CachePolicy, IncomingFaceId fields.
132
133
* yes(=1), allows these fields; this is valid only if FaceScope=local
134
* no(=0), disallows these fields
135
136 74 Eric Newberry
**LpReliabilityEnabled** indicates whether the face has the [[NDNLPv2]] reliability feature enabled.
137 69 Eric Newberry
138
* yes(=1), enables this feature
139
* no(=0), disables this feature
140 1 Junxiao Shi
141 74 Eric Newberry
**CongestionMarkingEnabled** indicates whether the face has congestion marking based upon send queue length enabled.
142
143
* yes(=1), enables this feature
144
* no(=0), disables this feature
145
146
**BaseCongestionMarkingInterval** indicates the base marking interval for congestion marking.
147
148
The value of this attribute is the base marking interval in nanoseconds (unsigned).
149
150
**DefaultCongestionThreshold** indicates the default congestion threshold if the face does not support retrieving the send queue capacity.
151
152
The value of this attribute is the default congestion threshold in bytes (unsigned).
153
154 52 Junxiao Shi
### Flags and Mask
155
156
Some attributes are collected as inclusive OR into a **Flags** field in commands and datasets.
157
These attributes are: (bit 0 is the least significant bit)
158
159
* bit 0: LocalFieldsEnabled
160 1 Junxiao Shi
* bit 1: LpReliabilityEnabled
161 74 Eric Newberry
* bit 2: CongestionMarkingEnabled
162 55 Junxiao Shi
163 1 Junxiao Shi
## Control Commands
164
165 20 Junxiao Shi
[[ControlCommand]] **management-module**: `faces`
166 41 Junxiao Shi
167
### Create a face
168 1 Junxiao Shi
169
**command-verb**: `create`
170 46 Junxiao Shi
171
ControlParameters fields:
172 1 Junxiao Shi
173
* **Uri** (required): canonical remote FaceUri of the face to create.
174 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.
175 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.
176 74 Eric Newberry
* **BaseCongestionMarkingInterval** (optional): see "static face attributes".
177
* **DefaultCongestionThreshold** (optional): see "static face attributes".
178 72 Davide Pesavento
* **Flags** (optional): see "static face attributes".
179 73 Junxiao Shi
* **Mask** (optional): must be specified if Flags is present, or omitted if Flags is omitted.
180 1 Junxiao Shi
181 65 Davide Pesavento
This command allows the creation of UDP unicast, Ethernet unicast, and TCP faces only.  
182 50 Junxiao Shi
If the command succeeds, the \<body> of the ControlResponse block contains the ControlParameters describing the current properties of the created face:
183 1 Junxiao Shi
184 64 Alex Afanasyev
* **FaceId**
185 68 Junxiao Shi
* **Uri**
186 64 Alex Afanasyev
* **LocalUri**
187 1 Junxiao Shi
* **FacePersistency**
188 74 Eric Newberry
* **BaseCongestionMarkingInterval**
189
* **DefaultCongestionThreshold**
190 68 Junxiao Shi
* **Flags**: contains effective values for *LocalFieldsEnabled* and *LpReliabilityEnabled* bits.
191
192 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.
193 66 Davide Pesavento
194 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.
195
196 1 Junxiao Shi
If face creation fails due to a socket error (e.g. TCP connection timeout), the command fails with StatusCode 504.
197
198 20 Junxiao Shi
### Update static properties
199 1 Junxiao Shi
200 20 Junxiao Shi
**command-verb**: `update`
201 52 Junxiao Shi
202 1 Junxiao Shi
ControlParameters fields:
203 64 Alex Afanasyev
204
* **FaceId** (optional)
205 1 Junxiao Shi
* **FacePersistency** (optional): *on-demand* or *persistent* or *permanent*  
206
  See "static face attributes" for more information.
207 74 Eric Newberry
* **BaseCongestionMarkingInterval** (optional): see "static face attributes".
208
* **DefaultCongestionThreshold** (optional): see "static face attributes".
209
* **Flags** (optional): allows *LocalFieldsEnabled*, *LpReliabilityEnabled*, and *CongestionMarkingEnabled* only - see "static face attributes".
210 73 Junxiao Shi
* **Mask** (optional): must be specified if Flags is present, or omitted if Flags is omitted.
211 52 Junxiao Shi
212
FaceId is the FaceId returned in [[FaceMgmt|Face Management]].
213
If FaceId is omitted or is set to zero, it is implied as the requesting face (self updating).  
214 1 Junxiao Shi
If face does not exist, this command fails with StatusCode 404.
215
216
Static properties of the face is updated.
217 55 Junxiao Shi
If an optional property field is omitted or a bitfield is zero in Mask, that static property remains unchanged.
218
If no static property is changed, this command does nothing, but is still considered successful.
219
220
If the command succeeds, \<body> in ControlResponse block contains ControlParameters describing the current properties of the face:
221 1 Junxiao Shi
222
* **FaceId**
223
* **FacePersistency**
224 74 Eric Newberry
* **BaseCongestionMarkingInterval**
225
* **DefaultCongestionThreshold**
226 70 Eric Newberry
* **Flags**: contains effective values for *LocalFieldsEnabled* and *LpReliabilityEnabled* bits
227 1 Junxiao Shi
228 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.
229
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.
230 62 Davide Pesavento
If the request had been sent without those fields (or bitfields in Mask), it would have been successful.
231 20 Junxiao Shi
232 1 Junxiao Shi
### Destroy a face
233 20 Junxiao Shi
234 26 Junxiao Shi
**command-verb:** `destroy`
235 20 Junxiao Shi
236 39 Junxiao Shi
ControlParameters fields:
237 1 Junxiao Shi
238 64 Alex Afanasyev
* **FaceId** (required)
239 39 Junxiao Shi
240 1 Junxiao Shi
If the specified face does not exist, this command does nothing, but is still considered successful.
241
242 40 Junxiao Shi
## Face Dataset
243 1 Junxiao Shi
244
Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`.
245 39 Junxiao Shi
246
Each face is represented by a **FaceStatus** block:
247 1 Junxiao Shi
248 39 Junxiao Shi
    FaceStatus      ::= FACE-STATUS-TYPE TLV-LENGTH
249
                          FaceId
250 37 Junxiao Shi
                          Uri (remote FaceUri)
251 39 Junxiao Shi
                          LocalUri
252 1 Junxiao Shi
                          ExpirationPeriod?
253
                          FaceScope
254
                          FacePersistency
255
                          LinkType
256 74 Eric Newberry
                          BaseCongestionMarkingInterval
257
                          DefaultCongestionThreshold
258 1 Junxiao Shi
                          Flags
259
                          NInInterests
260 67 Junxiao Shi
                          NInData
261 39 Junxiao Shi
                          NInNacks
262 67 Junxiao Shi
                          NOutInterests
263 49 Junxiao Shi
                          NOutData
264
                          NOutNacks
265 46 Junxiao Shi
                          NInBytes
266
                          NOutBytes
267
268
    Uri             ::= URI-TYPE TLV-LENGTH
269 39 Junxiao Shi
                          FaceUri in UTF-8 encoding
270 46 Junxiao Shi
271 1 Junxiao Shi
    LocalUri        ::= LOCAL-URI-TYPE TLV-LENGTH
272 46 Junxiao Shi
                          FaceUri in UTF-8 encoding
273 1 Junxiao Shi
    
274
    ; other TLVs have nonNegativeInteger as value
275
276 40 Junxiao Shi
* **Uri** is a FaceUri representing remote endpoint.
277 39 Junxiao Shi
* **LocalUri** is a FaceUri representing local endpoint.
278 40 Junxiao Shi
* **ExpirationPeriod** is the remaining lifetime of this face.
279 46 Junxiao Shi
  If this field is omitted, the face has infinite lifetime.
280 40 Junxiao Shi
  Currently, this is applicable to on-demand datagram faces only.
281 46 Junxiao Shi
* **FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes.
282 1 Junxiao Shi
  See "static face attributes" for more information.
283 40 Junxiao Shi
* **FacePersistency** indicates whether the face is persistent.
284 1 Junxiao Shi
  See "static face attributes" for more information.
285 52 Junxiao Shi
* **LinkType** indicates the type of communication link
286 1 Junxiao Shi
  See "static face attributes" for more information.
287 74 Eric Newberry
* **BaseCongestionMarkingInterval** indicates the base interval for congestion marking (in unsigned nanoseconds).
288 1 Junxiao Shi
  See "static face attributes" for more information.
289 74 Eric Newberry
* **DefaultCongestionThreshold** indicates the default threshold for congestion if the face does not support retrieving the send queue capacity (in unsigned bytes).
290
  See "static face attributes" for more information.
291
* **Flags** contains these bitfields: *LocalFieldsEnabled*, *LpReliabilityEnabled*, *CongestionMarkingEnabled*.
292
  See "static face attributes" for more information.
293 46 Junxiao Shi
* **NInInterests**: number of incoming Interest packets since the face is established.
294 67 Junxiao Shi
* **NInData** counts the number of incoming Data packets since the face is established.
295 46 Junxiao Shi
* **NInNacks** counts the number of incoming Nack packets since the face is established.
296 1 Junxiao Shi
* **NOutInterests** counts the number of outgoing Interest packets since the face is established.
297 67 Junxiao Shi
* **NOutData** counts the number of outgoing Data packets since the face is established.
298 37 Junxiao Shi
* **NOutNacks** counts the number of outgoing Nack packets since the face is established.
299
* **NInBytes** counts the number of bytes of link layer packets received via this face.
300
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
301
* **NOutBytes** counts the number of bytes of link layer packets sent via this face.
302
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
303
304
### Query Operation
305 1 Junxiao Shi
306 37 Junxiao Shi
The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter.
307
308
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.
309
310
    FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH
311 40 Junxiao Shi
                          FaceId?
312
                          UriScheme?
313
                          Uri?
314 37 Junxiao Shi
                          LocalUri?
315
                          FaceScope?
316 1 Junxiao Shi
                          FacePersistency?
317 37 Junxiao Shi
                          LinkType?
318
    
319
    UriScheme       ::= URI-SCHEME-TYPE TLV-LENGTH
320
                          string in UTF-8
321
322 40 Junxiao Shi
* **FaceId** permits a face if its FaceId equals the value
323
* **UriScheme** permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value
324
* **Uri** permits a face if its remote FaceUri equals the value
325 1 Junxiao Shi
* **LocalUri** permits a face if its local FaceUri equals the value
326
* **FaceScope** permits a face if its *FaceScope* attribute equals the value
327 39 Junxiao Shi
* **FacePersistency** permits a face if its *FacePersistency* attribute equals the value
328 37 Junxiao Shi
* **LinkType** permits a face if its *LinkType* attribute equals the value
329
330
A face must satisfy ALL conditions to satisfy the filter.
331 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>`).
332 37 Junxiao Shi
333 41 Junxiao Shi
Examples of filters:
334 37 Junxiao Shi
335 33 Junxiao Shi
* a specific face: FaceId=260
336 40 Junxiao Shi
* a specific TCP tunnel: Uri=tcp4://192.0.2.1:6363  
337 33 Junxiao Shi
  note: FaceUri must precisely match the canonical form: use either "tcp4" or "tcp6" instead of "tcp", use IP address instead of DNS name, include port number
338
* all TCP tunnels: UriScheme=tcp  
339
  note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6"
340
* all UDP multicast faces: UriScheme=udp & LinkType=multi-access
341
* all Ethernet faces: UriScheme=ether
342 1 Junxiao Shi
  note: UriScheme matches on both local and remote FaceUri, "dev" also works
343
* all faces: no condition  
344
  note: this is equivalent to face dataset, and face dataset should be preferred for this purpose
345 33 Junxiao Shi
346
## Channel Dataset
347
348 20 Junxiao Shi
Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`.
349 1 Junxiao Shi
350
Each channel is represented by a **ChannelStatus** block:
351 20 Junxiao Shi
352
    ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
353 21 Alex Afanasyev
                          LocalUri
354 20 Junxiao Shi
355 1 Junxiao Shi
* **LocalUri** is a FaceUri representing local endpoint.
356 21 Alex Afanasyev
357 37 Junxiao Shi
## Face Status Change Notification
358
359
Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`.
360 1 Junxiao Shi
Notifications of all faces are sent into the same notification stream.
361 37 Junxiao Shi
362
The Content of each notification Data packet is a `FaceEventNotification` block:
363 23 Alex Afanasyev
364 37 Junxiao Shi
    FaceEventNotification ::= FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
365 40 Junxiao Shi
                                FaceEventKind
366
                                FaceId
367
                                Uri
368 25 Junxiao Shi
                                LocalUri
369 23 Alex Afanasyev
                                FaceScope
370
                                FacePersistency
371 58 Eric Newberry
                                LinkType
372 25 Junxiao Shi
                                Flags
373 23 Alex Afanasyev
    
374 9 Junxiao Shi
    FaceEventKind         ::= FACE-EVENT-KIND-TYPE TLV-LENGTH
375
                                nonNegativeInteger
376
377 1 Junxiao Shi
**FaceEventKind** indicates the kind of event. Its possible values are:
378 34 Junxiao Shi
379 33 Junxiao Shi
* **1**: face is created
380 57 Eric Newberry
* **2**: face is destroyed
381
* **3**: face goes UP (from DOWN state)
382 32 Junxiao Shi
* **4**: face goes DOWN (from UP state)
383 20 Junxiao Shi
384
## TLV-TYPE assignments
385
386 39 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
387 40 Junxiao Shi
------------------------------------------- | ----------------- | --------------------
388
FaceStatus                                  | 128               | 0x80
389
LocalUri                                    | 129               | 0x81
390 24 Alex Afanasyev
ChannelStatus                               | 130               | 0x82
391 1 Junxiao Shi
FaceScope                                   | 132               | 0x84
392
FacePersistency                             | 133               | 0x85
393
LinkType                                    | 134               | 0x86
394 74 Eric Newberry
BaseCongestionMarkingInterval               | 135               | 0x87
395
DefaultCongestionThreshold                  | 136               | 0x88
396 1 Junxiao Shi
NInInterests                                | 144               | 0x90
397 67 Junxiao Shi
NInData                                     | 145               | 0x91
398 48 Junxiao Shi
NInNacks                                    | 151               | 0x97
399 1 Junxiao Shi
NOutInterests                               | 146               | 0x92
400 67 Junxiao Shi
NOutData                                    | 147               | 0x93
401 1 Junxiao Shi
NOutNacks                                   | 152               | 0x98
402
NInBytes                                    | 148               | 0x94
403
NOutBytes                                   | 149               | 0x95
404 39 Junxiao Shi
FaceQueryFilter                             | 150               | 0x96
405 1 Junxiao Shi
UriScheme                                   | 131               | 0x83
406
FaceEventNotification                       | 192               | 0xc0
407
FaceEventKind                               | 193               | 0xc1
408
(reserved, formerly FaceFlags)              | 194               | 0xc2