Project

General

Profile

FaceMgmt » History » Version 70

Eric Newberry, 07/11/2017 07:25 PM
Change ReliabilityEnabled flag to LpReliabilityEnabled

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