Project

General

Profile

FaceMgmt » History » Version 34

Junxiao Shi, 06/27/2014 04:29 AM

1 20 Junxiao Shi
# Face Management
2 1 Junxiao Shi
3 20 Junxiao Shi
**Face Management** is a module of [[Management|NFD Management protocol]].
4
It provides:
5 1 Junxiao Shi
6 20 Junxiao Shi
* commands to create and destroy faces
7
* commands to enable and disable [[LocalControlHeader]] features on a face
8
* a dataset of description of all active faces and their counters
9 33 Junxiao Shi
* a dataset of description of all active channels
10 20 Junxiao Shi
* a notification stream for face creating and destroying events
11 1 Junxiao Shi
12 20 Junxiao Shi
Face Management commands, datasets, and notifications are published in namespace `ndn:/localhost/nfd/faces`.
13 12 Alex Afanasyev
14
15 20 Junxiao Shi
## FaceUri
16 1 Junxiao Shi
17 27 Junxiao Shi
A FaceUri represents the underlying protocol and address used by a Face.  
18
Every Face has two FaceUris: one for local endpoint, and the other for remote endpoint.
19 1 Junxiao Shi
20 27 Junxiao Shi
### UDP
21 9 Junxiao Shi
22 30 Junxiao Shi
`udp[4|6]://<IP-or-host>[:<port>]`  
23 2 Alex Afanasyev
24 9 Junxiao Shi
Examples:
25 1 Junxiao Shi
26 20 Junxiao Shi
* `udp4://192.0.2.1:6363` (canonical form)
27
* `udp6://[2001:db8::1]:6363` (canonical form)
28 1 Junxiao Shi
* `udp://192.0.2.1` (remote-port defaults to 6363)
29
* `udp://example.net:6363`
30
* `udp4://example.net:6363` (resolve hostname to IPv4 address only)
31 9 Junxiao Shi
* `udp6://example.net:6363` (resolve hostname to IPv6 address only)
32 27 Junxiao Shi
* `udp4://224.0.23.170:56363` (multicast, canonical form)
33 1 Junxiao Shi
34
### TCP
35
36 30 Junxiao Shi
`tcp[4|6]://<IP-or-host>[:<port>]`
37 1 Junxiao Shi
38
Examples:
39
40 20 Junxiao Shi
* `tcp4://192.0.2.1:6363` (canonical form)
41
* `tcp6://[2001:db8::1]:6363` (canonical form)
42 1 Junxiao Shi
* `tcp://192.0.2.1` (remote-port defaults to 6363)
43
* `tcp://example.net:6363`
44 9 Junxiao Shi
* `tcp4://example.net:6363` (resolve hostname to IPv4 address only)
45 1 Junxiao Shi
* `tcp6://example.net:6363` (resolve hostname to IPv6 address only)
46
47
### UNIX stream
48 9 Junxiao Shi
49 1 Junxiao Shi
`unix://<path>`
50 9 Junxiao Shi
51 1 Junxiao Shi
Examples:
52
53
* `unix:///var/run/nfd.sock` (note there are three forward-slashes after 'unix')
54
55 30 Junxiao Shi
### File Descriptor
56
57
`fd://<file-descriptor>`
58
59
Examples:
60
61
* `fd://6`
62
63 1 Junxiao Shi
### Ethernet
64 27 Junxiao Shi
65 30 Junxiao Shi
`ether://<MAC>`  
66 1 Junxiao Shi
67
Examples:
68
69
* `ether://08:00:27:01:01:01`
70
* `ether://33:33:01:01:01:01` (multicast)
71
72 30 Junxiao Shi
### Network Device
73 1 Junxiao Shi
74 30 Junxiao Shi
`dev://<ifname>`
75
76
Examples:
77
78
* `dev://eth0`
79
80
### Underlying protocol and FaceUri scheme
81
82
Underlying protocol | remote FaceUri scheme            | local FaceUri scheme
83
------------------- | -------------------------------- | --------------------------
84
IPv4 UDP unicast    | udp4                             | udp4
85
IPv6 UDP unicast    | udp6                             | udp6
86
IPv4 UDP multicast  | udp4 (multicast IP)              | udp4 (local IP, same port)
87
IPv4 TCP            | tcp4                             | tcp4
88
IPv6 TCP            | tcp6                             | tcp6
89
UNIX stream         | fd (file descriptor on NFD side) | unix (socket path)
90
Ethernet multicast  | ether                            | dev
91
92 20 Junxiao Shi
## Control Commands
93
94 1 Junxiao Shi
[[ControlCommand]] **management-module**: `faces`
95
96
### Create a face
97 20 Junxiao Shi
98 1 Junxiao Shi
**command-verb**: `create`
99
100 20 Junxiao Shi
ControlParameters fields:
101 1 Junxiao Shi
102 30 Junxiao Shi
* Uri (required): a UDP unicast or TCP FaceUri
103 1 Junxiao Shi
104 20 Junxiao Shi
This command allows creation of UDP unicast and TCP faces only.  
105 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.
106 1 Junxiao Shi
107 20 Junxiao Shi
If the command succeeds, \<Body> in ControlResponse block contains updated ControlParameters:
108 1 Junxiao Shi
109 20 Junxiao Shi
* FaceId
110
* Uri: FaceUri in canonical form - hostname is substituted with IP address, scheme name indicates either IPv4 or IPv6
111 1 Junxiao Shi
112
### Destroy a face
113
114
**command-verb:** `destroy`
115
116 20 Junxiao Shi
ControlParameters fields:
117 1 Junxiao Shi
118 20 Junxiao Shi
* FaceId (required)
119 1 Junxiao Shi
120
If the specified face does not exist, this command does nothing, but is still considered successful.
121 20 Junxiao Shi
122
### Enable a LocalControlHeader feature
123
124
**command-verb**: `enable-local-control`
125
126
ControlParameters fields:
127
128
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId
129 26 Junxiao Shi
130 20 Junxiao Shi
This command can only operate on the requesting face.
131
132
### Disable a LocalControlHeader feature
133
134 1 Junxiao Shi
**command-verb**: `disable-local-control`
135 20 Junxiao Shi
136
ControlParameters fields:
137
138
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId
139 26 Junxiao Shi
140 20 Junxiao Shi
This command can only operate on the requesting face.
141
142 1 Junxiao Shi
## Face Dataset
143
144 20 Junxiao Shi
Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`.
145 1 Junxiao Shi
146 32 Junxiao Shi
Each face is represented by a **FaceStatus** block:
147 20 Junxiao Shi
148
    FaceStatus    := FACE-STATUS-TYPE TLV-LENGTH
149 1 Junxiao Shi
                       FaceId
150
                       Uri (remote FaceUri)
151 30 Junxiao Shi
                       LocalUri
152 34 Junxiao Shi
                       Lifetime?
153 32 Junxiao Shi
                       FaceFlags
154 20 Junxiao Shi
                       NInInterests
155
                       NInDatas
156
                       NOutInterests
157
                       NOutDatas
158 1 Junxiao Shi
    
159 32 Junxiao Shi
    LocalUri      := LOCAL-URI-TYPE TLV-LENGTH
160 1 Junxiao Shi
                       RFC3986 URI in UTF-8 encoding
161 34 Junxiao Shi
    
162
    Lifetime      := LIFETIME-TYPE TLV-LENGTH
163
                       nonNegativeInteger
164 32 Junxiao Shi
165
    FaceFlags     := FACE-FLAGS-TYPE TLV-LENGTH
166
                       nonNegativeInteger
167 30 Junxiao Shi
    
168 20 Junxiao Shi
    NInInterests  := N-IN-INTERESTS-TYPE TLV-LENGTH
169
                       nonNegativeInteger
170
    
171
    NInDatas      := N-IN-DATAS-TYPE TLV-LENGTH
172 1 Junxiao Shi
                       nonNegativeInteger
173
    
174
    NOutInterests := N-OUT-INTERESTS-TYPE TLV-LENGTH
175
                       nonNegativeInteger
176
    
177
    NOutDatas     := N-OUT-DATAS-TYPE TLV-LENGTH
178
                       nonNegativeInteger
179 32 Junxiao Shi
180
* **Uri** is a FaceUri representing remote endpoint.
181 1 Junxiao Shi
* **LocalUri** is a FaceUri representing local endpoint.
182 34 Junxiao Shi
* **Lifetime** is the remaining lifetime of this face.
183
  If this field is omitted, the face has infinite lifetime.
184
  Currently, this is applicable to on-demand datagram faces only.
185
* **FaceFlags** is a bitset providing additional information about the face.
186
  The following bits are currently defined:
187 32 Junxiao Shi
    * **1**: face is local
188
    * **2**: face is on demand - accepted incoming connection, instead of initiated outgoing connection
189
* **NInInterests** is the total number of incoming Interests since the face is established.
190
* **NInDatas** is the total number of incoming Datas since the face is established.
191
* **NOutInterests** is the total number of outgoing Interests since the face is established.
192
* **NOutDatas** is the total number of outgoing Datas since the face is established.
193 20 Junxiao Shi
194 33 Junxiao Shi
## Channel Dataset
195
196
Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`.
197
198
Each channel is represented by a **ChannelStatus** block:
199
200
    ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
201
                          LocalUri
202
203
* **LocalUri** is a FaceUri representing local endpoint.
204
205 20 Junxiao Shi
## Face Status Change Notification
206
207
Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`.
208 21 Alex Afanasyev
Notifications of all faces are sent into the same notification stream.
209 20 Junxiao Shi
210 21 Alex Afanasyev
The Content of each notification Data packet is a `FaceEventNotification` block:
211
212 25 Junxiao Shi
    FaceEventNotification := FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
213 20 Junxiao Shi
                               FaceEventKind
214 25 Junxiao Shi
                               FaceId
215
                               Uri
216 1 Junxiao Shi
                               LocalUri
217 23 Alex Afanasyev
                               FaceFlags
218 20 Junxiao Shi
    
219
    FaceEventKind         := FACE-EVENT-KIND-TYPE TLV-LENGTH
220 25 Junxiao Shi
                               nonNegativeInteger
221
222 23 Alex Afanasyev
**FaceEventKind** indicates the kind of event. Its possible values are:
223 25 Junxiao Shi
224 23 Alex Afanasyev
* **1**: face is created
225
* **2**: face is destroyed
226 25 Junxiao Shi
227 23 Alex Afanasyev
## TLV-TYPE assignments
228 9 Junxiao Shi
229
Type                                        | Assigned value    | Assigned value (hex)
230
------------------------------------------- | ----------------- | --------------------
231 2 Alex Afanasyev
FaceStatus                                  | 128               | 0x80
232 1 Junxiao Shi
LocalUri                                    | 129               | 0x81
233 34 Junxiao Shi
Lifetime                                    | 131               | 0x83
234 33 Junxiao Shi
ChannelStatus                               | 130               | 0x82
235 32 Junxiao Shi
FaceFlags                                   | 194               | 0xc2
236 20 Junxiao Shi
NInInterests                                | 144               | 0x90
237
NInDatas                                    | 145               | 0x91
238
NOutInterests                               | 146               | 0x92
239 22 Alex Afanasyev
NOutDatas                                   | 147               | 0x93
240 1 Junxiao Shi
FaceEventNotification                       | 192               | 0xc0
241 24 Alex Afanasyev
FaceEventKind                               | 193               | 0xc1