Project

General

Profile

FaceMgmt » History » Version 47

Yukai Tu, 08/23/2015 10: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 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 46 Junxiao Shi
## Static Face Attributes
95
96
**FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes.
97
98
* non-local(=0)
99
* local(=1)
100
101
**FacePersistency** indicates whether the face is persistent.
102
103
* on-demand(=1), face closes if it remains idle for some time
104
* persistent(=0), face remains open until it's explicitly destroyed or there's a transport failure
105
* permanent(=2), face remains open until it's explicitly destroyed; transport failures will be recovered internally
106
107
**LinkType** indicates the type of communication link.
108
109
* point-to-point(=0), communication with one peer
110
* multi-access(=1), communication with a multicast group
111
112 1 Junxiao Shi
## Control Commands
113 20 Junxiao Shi
114 1 Junxiao Shi
[[ControlCommand]] **management-module**: `faces`
115
116 20 Junxiao Shi
### Create a face
117 1 Junxiao Shi
118 41 Junxiao Shi
**command-verb**: `create`
119
120 1 Junxiao Shi
ControlParameters fields:
121
122 46 Junxiao Shi
* Uri (required): a canonical UDP unicast or TCP FaceUri
123
* FacePersistency (optional): either *persistent* or *permanent*; creating on-demand faces is disallowed.  
124 47 Yukai Tu
  The default is *persistent*.  
125 46 Junxiao Shi
  See "static face attributes" for more information.
126 1 Junxiao Shi
127 20 Junxiao Shi
This command allows creation of UDP unicast and TCP faces only.  
128 46 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;
129
If the existing face has a different FacePersistency property, the transition on the direction of *on-demand* -> *persistent* -> *permanent* is allowed.
130 1 Junxiao Shi
131 20 Junxiao Shi
If the command succeeds, \<Body> in ControlResponse block contains updated ControlParameters:
132 1 Junxiao Shi
133 20 Junxiao Shi
* FaceId
134 46 Junxiao Shi
* FacePersistency
135 1 Junxiao Shi
136
### Destroy a face
137
138
**command-verb:** `destroy`
139
140 20 Junxiao Shi
ControlParameters fields:
141 1 Junxiao Shi
142 20 Junxiao Shi
* FaceId (required)
143 1 Junxiao Shi
144
If the specified face does not exist, this command does nothing, but is still considered successful.
145 20 Junxiao Shi
146
### Enable a LocalControlHeader feature
147
148
**command-verb**: `enable-local-control`
149
150
ControlParameters fields:
151
152 43 Junxiao Shi
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId, 3=CachingPolicy
153 26 Junxiao Shi
154 20 Junxiao Shi
This command can only operate on the requesting face.
155
156
### Disable a LocalControlHeader feature
157
158 1 Junxiao Shi
**command-verb**: `disable-local-control`
159 20 Junxiao Shi
160 26 Junxiao Shi
ControlParameters fields:
161 20 Junxiao Shi
162 39 Junxiao Shi
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId, 3=CachingPolicy
163 1 Junxiao Shi
164 40 Junxiao Shi
This command can only operate on the requesting face.
165 39 Junxiao Shi
166 1 Junxiao Shi
## Face Dataset
167
168 40 Junxiao Shi
Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`.
169 1 Junxiao Shi
170
Each face is represented by a **FaceStatus** block:
171 39 Junxiao Shi
172
    FaceStatus      ::= FACE-STATUS-TYPE TLV-LENGTH
173 1 Junxiao Shi
                          FaceId
174 39 Junxiao Shi
                          Uri (remote FaceUri)
175
                          LocalUri
176 37 Junxiao Shi
                          ExpirationPeriod?
177 39 Junxiao Shi
                          FaceScope
178 1 Junxiao Shi
                          FacePersistency
179
                          LinkType
180
                          NInInterests
181
                          NInDatas
182 46 Junxiao Shi
                          NInNacks
183 1 Junxiao Shi
                          NOutInterests
184 39 Junxiao Shi
                          NOutDatas
185 46 Junxiao Shi
                          NOutNacks
186
187
    Uri             ::= URI-TYPE TLV-LENGTH
188
                          FaceUri in UTF-8 encoding
189
190 39 Junxiao Shi
    LocalUri        ::= LOCAL-URI-TYPE TLV-LENGTH
191 46 Junxiao Shi
                          FaceUri in UTF-8 encoding
192 1 Junxiao Shi
    
193 46 Junxiao Shi
    ; other TLVs have nonNegativeInteger as value
194 1 Junxiao Shi
195
* **Uri** is a FaceUri representing remote endpoint.
196
* **LocalUri** is a FaceUri representing local endpoint.
197 40 Junxiao Shi
* **ExpirationPeriod** is the remaining lifetime of this face.
198 39 Junxiao Shi
  If this field is omitted, the face has infinite lifetime.
199
  Currently, this is applicable to on-demand datagram faces only.
200 40 Junxiao Shi
* **FaceScope** indicates whether the face is local for [[ScopeControl|scope control]] purposes.
201 46 Junxiao Shi
  See "static face attributes" for more information.
202 40 Junxiao Shi
* **FacePersistency** indicates whether the face is persistent.
203 46 Junxiao Shi
  See "static face attributes" for more information.
204 40 Junxiao Shi
* **LinkType** indicates the type of communication link
205 46 Junxiao Shi
  See "static face attributes" for more information.
206
* **NInInterests**: number of incoming Interest packets since the face is established.
207
* **NInDatas** counts the number of incoming Data packets since the face is established.
208
* **NInNacks** counts the number of incoming Nack packets since the face is established.
209
* **NOutInterests** counts the number of outgoing Interest packets since the face is established.
210
* **NOutDatas** counts the number of outgoing Data packets since the face is established.
211
* **NOutNacks** counts the number of outgoing Nack packets since the face is established.
212 1 Junxiao Shi
* **NInBytes** counts the number of bytes of link layer packets received via this face.
213
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
214 37 Junxiao Shi
* **NOutBytes** counts the number of bytes of link layer packets sent via this face.
215
  This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
216
217
### Query Operation
218
219
The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter.
220
221 1 Junxiao Shi
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.
222 37 Junxiao Shi
223
    FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH
224
                          FaceId?
225
                          UriScheme?
226
                          Uri?
227 40 Junxiao Shi
                          LocalUri?
228
                          FaceScope?
229
                          FacePersistency?
230 37 Junxiao Shi
                          LinkType?
231
    
232 1 Junxiao Shi
    UriScheme       ::= URI-SCHEME-TYPE TLV-LENGTH
233 37 Junxiao Shi
                          string in UTF-8
234
235
* **FaceId** permits a face if its FaceId equals the value
236
* **UriScheme** permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value
237
* **Uri** permits a face if its remote FaceUri equals the value
238 40 Junxiao Shi
* **LocalUri** permits a face if its local FaceUri equals the value
239
* **FaceScope** permits a face if its *FaceScope* attribute equals the value
240
* **FacePersistency** permits a face if its *FacePersistency* attribute equals the value
241 1 Junxiao Shi
* **LinkType** permits a face if its *LinkType* attribute equals the value
242
243 39 Junxiao Shi
A face must satisfy ALL conditions to satisfy the filter.
244 37 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>`).
245
246
Examples of filters:
247 1 Junxiao Shi
248 37 Junxiao Shi
* a specific face: FaceId=260
249 41 Junxiao Shi
* a specific TCP tunnel: Uri=tcp4://192.0.2.1:6363  
250 37 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
251 33 Junxiao Shi
* all TCP tunnels: UriScheme=tcp  
252 40 Junxiao Shi
  note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6"
253 33 Junxiao Shi
* all UDP multicast faces: UriScheme=udp & LinkType=multi-access
254
* all Ethernet faces: UriScheme=ether
255
  note: UriScheme matches on both local and remote FaceUri, "dev" also works
256
* all faces: no condition  
257
  note: this is equivalent to face dataset, and face dataset should be preferred for this purpose
258 1 Junxiao Shi
259
## Channel Dataset
260
261 33 Junxiao Shi
Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`.
262
263
Each channel is represented by a **ChannelStatus** block:
264 20 Junxiao Shi
265 1 Junxiao Shi
    ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
266
                          LocalUri
267 20 Junxiao Shi
268
* **LocalUri** is a FaceUri representing local endpoint.
269 21 Alex Afanasyev
270 20 Junxiao Shi
## Face Status Change Notification
271 1 Junxiao Shi
272 21 Alex Afanasyev
Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`.
273 37 Junxiao Shi
Notifications of all faces are sent into the same notification stream.
274
275
The Content of each notification Data packet is a `FaceEventNotification` block:
276 1 Junxiao Shi
277 37 Junxiao Shi
    FaceEventNotification ::= FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
278
                                FaceEventKind
279 23 Alex Afanasyev
                                FaceId
280 37 Junxiao Shi
                                Uri
281 40 Junxiao Shi
                                LocalUri
282
                                FaceScope
283
                                FacePersistency
284 25 Junxiao Shi
                                LinkType
285 23 Alex Afanasyev
    
286
    FaceEventKind         ::= FACE-EVENT-KIND-TYPE TLV-LENGTH
287 25 Junxiao Shi
                                nonNegativeInteger
288 23 Alex Afanasyev
289 9 Junxiao Shi
**FaceEventKind** indicates the kind of event. Its possible values are:
290
291
* **1**: face is created
292 1 Junxiao Shi
* **2**: face is destroyed
293 34 Junxiao Shi
294 33 Junxiao Shi
## TLV-TYPE assignments
295 32 Junxiao Shi
296 20 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
297
------------------------------------------- | ----------------- | --------------------
298
FaceStatus                                  | 128               | 0x80
299 39 Junxiao Shi
LocalUri                                    | 129               | 0x81
300 40 Junxiao Shi
ChannelStatus                               | 130               | 0x82
301
FaceScope                                   | 132               | 0x84
302
FacePersistency                             | 133               | 0x85
303 24 Alex Afanasyev
LinkType                                    | 134               | 0x86
304 1 Junxiao Shi
NInInterests                                | 144               | 0x90
305
NInDatas                                    | 145               | 0x91
306
NOutInterests                               | 146               | 0x92
307
NOutDatas                                   | 147               | 0x93
308
NInBytes                                    | 148               | 0x94
309 44 Junxiao Shi
NOutBytes                                   | 149               | 0x95
310 1 Junxiao Shi
FaceQueryFilter                             | 150               | 0x96
311
UriScheme                                   | 131               | 0x83
312
FaceEventNotification                       | 192               | 0xc0
313 39 Junxiao Shi
FaceEventKind                               | 193               | 0xc1
314 1 Junxiao Shi
(reserved, formerly FaceFlags)              | 194               | 0xc2