Project

General

Profile

FaceMgmt » History » Version 61

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