Project

General

Profile

FaceMgmt » History » Version 71

Alex Afanasyev, 09/28/2017 01:12 AM

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