Project

General

Profile

FaceMgmt » History » Version 60

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