Project

General

Profile

FaceMgmt » History » Version 45

Junxiao Shi, 07/29/2015 08:34 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
### TCP
37
38 30 Junxiao Shi
`tcp[4|6]://<IP-or-host>[:<port>]`
39 1 Junxiao Shi
40
Examples:
41
42 20 Junxiao Shi
* `tcp4://192.0.2.1:6363` (canonical form)
43
* `tcp6://[2001:db8::1]:6363` (canonical form)
44 1 Junxiao Shi
* `tcp://192.0.2.1` (remote-port defaults to 6363)
45
* `tcp://example.net:6363`
46 9 Junxiao Shi
* `tcp4://example.net:6363` (resolve hostname to IPv4 address only)
47 1 Junxiao Shi
* `tcp6://example.net:6363` (resolve hostname to IPv6 address only)
48
49
### UNIX stream
50 9 Junxiao Shi
51 1 Junxiao Shi
`unix://<path>`
52 9 Junxiao Shi
53 1 Junxiao Shi
Examples:
54
55
* `unix:///var/run/nfd.sock` (note there are three forward-slashes after 'unix')
56
57 30 Junxiao Shi
### File Descriptor
58
59
`fd://<file-descriptor>`
60
61
Examples:
62
63
* `fd://6`
64
65 1 Junxiao Shi
### Ethernet
66 27 Junxiao Shi
67 42 Junxiao Shi
`ether://[<MAC>]`
68 1 Junxiao Shi
69
Examples:
70
71 42 Junxiao Shi
* `ether://[08:00:27:01:01:01]`
72
* `ether://[33:33:01:01:01:01]` (multicast)
73 1 Junxiao Shi
74 30 Junxiao Shi
### Network Device
75 1 Junxiao Shi
76 30 Junxiao Shi
`dev://<ifname>`
77
78
Examples:
79
80
* `dev://eth0`
81
82
### Underlying protocol and FaceUri scheme
83
84
Underlying protocol | remote FaceUri scheme            | local FaceUri scheme
85
------------------- | -------------------------------- | --------------------------
86
IPv4 UDP unicast    | udp4                             | udp4
87
IPv6 UDP unicast    | udp6                             | udp6
88
IPv4 UDP multicast  | udp4 (multicast IP)              | udp4 (local IP, same port)
89
IPv4 TCP            | tcp4                             | tcp4
90
IPv6 TCP            | tcp6                             | tcp6
91
UNIX stream         | fd (file descriptor on NFD side) | unix (socket path)
92
Ethernet multicast  | ether                            | dev
93
94 20 Junxiao Shi
## Control Commands
95
96 1 Junxiao Shi
[[ControlCommand]] **management-module**: `faces`
97
98
### Create a face
99 20 Junxiao Shi
100 1 Junxiao Shi
**command-verb**: `create`
101
102 20 Junxiao Shi
ControlParameters fields:
103 1 Junxiao Shi
104 41 Junxiao Shi
* Uri (required): a UDP unicast or TCP FaceUri  
105
  note: It's recommended to use a FaceUri in canonical form; passing a hostname is allowed but deprecated.
106 1 Junxiao Shi
107 20 Junxiao Shi
This command allows creation of UDP unicast and TCP faces only.  
108 30 Junxiao Shi
If another face with same underlying protocol and remote address exists, the command is considered successful, and FaceId of that face is returned.
109 1 Junxiao Shi
110 20 Junxiao Shi
If the command succeeds, \<Body> in ControlResponse block contains updated ControlParameters:
111 1 Junxiao Shi
112 20 Junxiao Shi
* FaceId
113
* Uri: FaceUri in canonical form - hostname is substituted with IP address, scheme name indicates either IPv4 or IPv6
114 1 Junxiao Shi
115
### Destroy a face
116
117
**command-verb:** `destroy`
118
119 20 Junxiao Shi
ControlParameters fields:
120 1 Junxiao Shi
121 20 Junxiao Shi
* FaceId (required)
122 1 Junxiao Shi
123
If the specified face does not exist, this command does nothing, but is still considered successful.
124 20 Junxiao Shi
125
### Enable a LocalControlHeader feature
126
127
**command-verb**: `enable-local-control`
128
129
ControlParameters fields:
130
131 43 Junxiao Shi
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId, 3=CachingPolicy
132 26 Junxiao Shi
133 20 Junxiao Shi
This command can only operate on the requesting face.
134
135
### Disable a LocalControlHeader feature
136
137 1 Junxiao Shi
**command-verb**: `disable-local-control`
138 20 Junxiao Shi
139
ControlParameters fields:
140
141 43 Junxiao Shi
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId, 3=CachingPolicy
142 26 Junxiao Shi
143 20 Junxiao Shi
This command can only operate on the requesting face.
144
145 1 Junxiao Shi
## Face Dataset
146
147 20 Junxiao Shi
Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`.
148 1 Junxiao Shi
149 32 Junxiao Shi
Each face is represented by a **FaceStatus** block:
150 1 Junxiao Shi
151 39 Junxiao Shi
    FaceStatus      ::= FACE-STATUS-TYPE TLV-LENGTH
152
                          FaceId
153
                          Uri (remote FaceUri)
154
                          LocalUri
155
                          ExpirationPeriod?
156 40 Junxiao Shi
                          FaceScope
157
                          FacePersistency
158
                          LinkType
159 39 Junxiao Shi
                          NInInterests
160
                          NInDatas
161
                          NOutInterests
162
                          NOutDatas
163
                          NInBytes
164
                          NOutBytes
165 1 Junxiao Shi
    
166 39 Junxiao Shi
    LocalUri        ::= LOCAL-URI-TYPE TLV-LENGTH
167
                          RFC3986 URI in UTF-8 encoding
168 1 Junxiao Shi
    
169 40 Junxiao Shi
    FaceScope       ::= FACE-SCOPE-TYPE TLV-LENGTH
170 39 Junxiao Shi
                          nonNegativeInteger
171 1 Junxiao Shi
    
172 40 Junxiao Shi
    FacePersistency ::= FACE-PERSISTENCY-TYPE TLV-LENGTH
173 39 Junxiao Shi
                          nonNegativeInteger
174 1 Junxiao Shi
    
175 40 Junxiao Shi
    LinkType        ::= LINK-TYPE-TYPE TLV-LENGTH
176 39 Junxiao Shi
                          nonNegativeInteger
177 20 Junxiao Shi
    
178 39 Junxiao Shi
    NInInterests    ::= N-IN-INTERESTS-TYPE TLV-LENGTH
179
                          nonNegativeInteger
180 1 Junxiao Shi
    
181 39 Junxiao Shi
    NInDatas        ::= N-IN-DATAS-TYPE TLV-LENGTH
182
                          nonNegativeInteger
183 1 Junxiao Shi
    
184 39 Junxiao Shi
    NOutInterests   ::= N-OUT-INTERESTS-TYPE TLV-LENGTH
185
                          nonNegativeInteger
186 37 Junxiao Shi
    
187 39 Junxiao Shi
    NOutDatas       ::= N-OUT-DATAS-TYPE TLV-LENGTH
188
                          nonNegativeInteger
189
    
190
    NInBytes        ::= N-IN-BYTES-TYPE TLV-LENGTH
191
                          nonNegativeInteger
192
    
193
    NOutBytes       ::= N-OUT-BYTES-TYPE TLV-LENGTH
194
                          nonNegativeInteger
195 1 Junxiao Shi
196
* **Uri** is a FaceUri representing remote endpoint.
197
* **LocalUri** is a FaceUri representing local endpoint.
198
* **ExpirationPeriod** is the remaining lifetime of this face.
199
  If this field is omitted, the face has infinite lifetime.
200
  Currently, this is applicable to on-demand datagram faces only.
201 40 Junxiao Shi
* **FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes.
202 39 Junxiao Shi
    * non-local(=0)
203
    * local(=1)
204 40 Junxiao Shi
* **FacePersistency** indicates whether the face is persistent.
205
    * persistent(=0), face remains open until it's explicitly destroyed or there's a transport failure
206
    * on-demand(=1), face closes if it remains idle for some time
207
    * permanent(=2), face remains open until it's explicitly destroyed; transport failures will be recovered internally (this level of persistency is not supported currently)
208
* **LinkType** indicates the type of communication link
209
    * point-to-point(=0), communication with one peer
210
    * multi-access(=1), communication with a multicast group
211 1 Junxiao Shi
* **NInInterests** is the total number of incoming Interests since the face is established.
212 37 Junxiao Shi
* **NInDatas** is the total number of incoming Datas since the face is established.
213
* **NOutInterests** is the total number of outgoing Interests since the face is established.
214
* **NOutDatas** is the total number of outgoing Datas since the face is established.
215
* **NInBytes** counts the number of bytes of link layer packets received via this face.
216 1 Junxiao Shi
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
217
* **NOutBytes** counts the number of bytes of link layer packets sent via this face.
218 37 Junxiao Shi
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
219
220
### Query Operation
221
222
The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter.
223
224
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.
225 1 Junxiao Shi
226 37 Junxiao Shi
    FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH
227
                          FaceId?
228
                          UriScheme?
229
                          Uri?
230
                          LocalUri?
231 40 Junxiao Shi
                          FaceScope?
232
                          FacePersistency?
233
                          LinkType?
234 37 Junxiao Shi
    
235
    UriScheme       ::= URI-SCHEME-TYPE TLV-LENGTH
236 1 Junxiao Shi
                          string in UTF-8
237 37 Junxiao Shi
238
* **FaceId** permits a face if its FaceId equals the value
239
* **UriScheme** permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value
240
* **Uri** permits a face if its remote FaceUri equals the value
241
* **LocalUri** permits a face if its local FaceUri equals the value
242 40 Junxiao Shi
* **FaceScope** permits a face if its *FaceScope* attribute equals the value
243
* **FacePersistency** permits a face if its *FacePersistency* attribute equals the value
244
* **LinkType** permits a face if its *LinkType* attribute equals the value
245 1 Junxiao Shi
246
A face must satisfy ALL conditions to satisfy the filter.
247 39 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>`).
248 37 Junxiao Shi
249
Examples of filters:
250
251 1 Junxiao Shi
* a specific face: FaceId=260
252 37 Junxiao Shi
* a specific TCP tunnel: Uri=tcp4://192.0.2.1:6363  
253 41 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
254 37 Junxiao Shi
* all TCP tunnels: UriScheme=tcp  
255 33 Junxiao Shi
  note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6"
256 40 Junxiao Shi
* all UDP multicast faces: UriScheme=udp & LinkType=multi-access
257 33 Junxiao Shi
* all Ethernet faces: UriScheme=ether
258
  note: UriScheme matches on both local and remote FaceUri, "dev" also works
259
* all faces: no condition  
260
  note: this is equivalent to face dataset, and face dataset should be preferred for this purpose
261
262 1 Junxiao Shi
## Channel Dataset
263
264
Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`.
265 33 Junxiao Shi
266
Each channel is represented by a **ChannelStatus** block:
267
268 20 Junxiao Shi
    ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
269 1 Junxiao Shi
                          LocalUri
270
271 20 Junxiao Shi
* **LocalUri** is a FaceUri representing local endpoint.
272
273 21 Alex Afanasyev
## Face Status Change Notification
274 20 Junxiao Shi
275 1 Junxiao Shi
Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`.
276 21 Alex Afanasyev
Notifications of all faces are sent into the same notification stream.
277 37 Junxiao Shi
278
The Content of each notification Data packet is a `FaceEventNotification` block:
279
280 1 Junxiao Shi
    FaceEventNotification ::= FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
281 37 Junxiao Shi
                                FaceEventKind
282
                                FaceId
283 23 Alex Afanasyev
                                Uri
284 37 Junxiao Shi
                                LocalUri
285 40 Junxiao Shi
                                FaceScope
286
                                FacePersistency
287
                                LinkType
288 25 Junxiao Shi
    
289 23 Alex Afanasyev
    FaceEventKind         ::= FACE-EVENT-KIND-TYPE TLV-LENGTH
290
                                nonNegativeInteger
291 25 Junxiao Shi
292 23 Alex Afanasyev
**FaceEventKind** indicates the kind of event. Its possible values are:
293 9 Junxiao Shi
294
* **1**: face is created
295
* **2**: face is destroyed
296 1 Junxiao Shi
297 34 Junxiao Shi
## TLV-TYPE assignments
298 33 Junxiao Shi
299 32 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
300 20 Junxiao Shi
------------------------------------------- | ----------------- | --------------------
301
FaceStatus                                  | 128               | 0x80
302
LocalUri                                    | 129               | 0x81
303 39 Junxiao Shi
ChannelStatus                               | 130               | 0x82
304 40 Junxiao Shi
FaceScope                                   | 132               | 0x84
305
FacePersistency                             | 133               | 0x85
306
LinkType                                    | 134               | 0x86
307 24 Alex Afanasyev
NInInterests                                | 144               | 0x90
308 1 Junxiao Shi
NInDatas                                    | 145               | 0x91
309
NOutInterests                               | 146               | 0x92
310
NOutDatas                                   | 147               | 0x93
311
NInBytes                                    | 148               | 0x94
312
NOutBytes                                   | 149               | 0x95
313 44 Junxiao Shi
FaceQueryFilter                             | 150               | 0x96
314 1 Junxiao Shi
UriScheme                                   | 131               | 0x83
315
FaceEventNotification                       | 192               | 0xc0
316
FaceEventKind                               | 193               | 0xc1
317 39 Junxiao Shi
(reserved, formerly FaceFlags)              | 194               | 0xc2