Project

General

Profile

FaceMgmt » History » Version 20

Junxiao Shi, 03/18/2014 11:28 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
* a notification stream for face creating and destroying events
10 1 Junxiao Shi
11 20 Junxiao Shi
Face Management commands, datasets, and notifications are published in namespace `ndn:/localhost/nfd/faces`.
12 12 Alex Afanasyev
13
14
15 20 Junxiao Shi
## FaceUri
16 12 Alex Afanasyev
17 20 Junxiao Shi
A FaceUri indicates the underlying protocol and underlying address of a Face.
18 1 Junxiao Shi
19 9 Junxiao Shi
### UDP unicast
20 2 Alex Afanasyev
21 9 Junxiao Shi
`udp[4|6]://<remote-IP-or-host>[:<remote-port>]`
22 2 Alex Afanasyev
23 9 Junxiao Shi
Examples:
24 1 Junxiao Shi
25 20 Junxiao Shi
* `udp4://192.0.2.1:6363` (canonical form)
26
* `udp6://[2001:db8::1]:6363` (canonical form)
27 9 Junxiao Shi
* `udp://192.0.2.1` (remote-port defaults to 6363)
28
* `udp://example.net:6363`
29
* `udp4://example.net:6363` (resolve hostname to IPv4 address only)
30 1 Junxiao Shi
* `udp6://example.net:6363` (resolve hostname to IPv6 address only)
31 9 Junxiao Shi
32 1 Junxiao Shi
### UDP multicast
33
34 9 Junxiao Shi
`udp-mcast://<multicast-IP>:<multicast-port>`
35 1 Junxiao Shi
36
Examples:
37 9 Junxiao Shi
38 1 Junxiao Shi
* `udp://224.0.23.170:56363`
39
40
### TCP
41
42 9 Junxiao Shi
`tcp[4|6]://<remote-IP-or-host>[:<remote-port>]`
43 1 Junxiao Shi
44
Examples:
45
46 20 Junxiao Shi
* `tcp4://192.0.2.1:6363` (canonical form)
47
* `tcp6://[2001:db8::1]:6363` (canonical form)
48 1 Junxiao Shi
* `tcp://192.0.2.1` (remote-port defaults to 6363)
49 9 Junxiao Shi
* `tcp://example.net:6363`
50 1 Junxiao Shi
* `tcp4://example.net:6363` (resolve hostname to IPv4 address only)
51 9 Junxiao Shi
* `tcp6://example.net:6363` (resolve hostname to IPv6 address only)
52 1 Junxiao Shi
53
### UNIX stream
54
55 9 Junxiao Shi
`unix://<path>`
56
57
Examples:
58 1 Junxiao Shi
59
* `unix:///var/run/nfd.sock` (note there are three forward-slashes after 'unix')
60
61
URI is available for the channel only.
62
Accepted UNIX stream faces do not have URI.
63
64
### Ethernet unicast
65
66
`ether://<remote-MAC>`
67
68
Examples:
69
70
* `ether://08:00:27:01:01:01`
71
72
### Ethernet multicast
73
74
`ether-mcast://<multicast-MAC>`
75
76
Examples:
77
78
* `ether-mcast://33:33:01:01:01:01`
79
80
81
82 20 Junxiao Shi
## Control Commands
83 1 Junxiao Shi
84 20 Junxiao Shi
[[ControlCommand]] **management-module**: `faces`
85
86 1 Junxiao Shi
### Create a face
87
88 20 Junxiao Shi
**command-verb**: `create`
89 1 Junxiao Shi
90 20 Junxiao Shi
ControlParameters fields:
91 1 Junxiao Shi
92 20 Junxiao Shi
* Uri (required): a FaceUri that represents a UDP unicast tunnel or a TCP tunnel
93 1 Junxiao Shi
94 20 Junxiao Shi
This command allows creation of UDP unicast and TCP faces only.  
95
If another face exists for the same underlying protocol and address, the command is considered successful, and FaceId of that face is returned.
96 1 Junxiao Shi
97 20 Junxiao Shi
If the command succeeds, \<Body> in ControlResponse block contains updated ControlParameters:
98 1 Junxiao Shi
99 20 Junxiao Shi
* FaceId
100
* Uri: FaceUri in canonical form - hostname is substituted with IP address, scheme name indicates either IPv4 or IPv6
101 1 Junxiao Shi
102
### Destroy a face
103
104
**command-verb:** `destroy`
105
106 20 Junxiao Shi
ControlParameters fields:
107 1 Junxiao Shi
108 20 Junxiao Shi
* FaceId (required)
109 1 Junxiao Shi
110
If the specified face does not exist, this command does nothing, but is still considered successful.
111
112 20 Junxiao Shi
### Enable a LocalControlHeader feature
113
114
**command-verb**: `enable-local-control`
115
116
ControlParameters fields:
117
118
* FaceId (required)
119
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId
120
121
If the face doesn't exist, the command fails with code 404.  
122
If the face is not local, the command fails with code 412.
123
124
### Disable a LocalControlHeader feature
125
126
**command-verb**: `disable-local-control`
127
128
ControlParameters fields:
129
130
* FaceId (required)
131
* LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId
132
133
If the face doesn't exist, the command fails with code 404.  
134
If the face is not local, the command fails with code 412.
135
136
137
138
## Face Dataset
139
140
Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`.
141
142
Each face is represented by a **FaceStatus** blocks:
143
144
    FaceStatus    := FACE-STATUS-TYPE TLV-LENGTH
145
                       FaceId
146
                       Uri
147
                       NInInterests
148
                       NInDatas
149
                       NOutInterests
150
                       NOutDatas
151
    
152
    NInInterests  := N-IN-INTERESTS-TYPE TLV-LENGTH
153
                       nonNegativeInteger
154
    
155
    NInDatas      := N-IN-DATAS-TYPE TLV-LENGTH
156
                       nonNegativeInteger
157
    
158
    NOutInterests := N-OUT-INTERESTS-TYPE TLV-LENGTH
159
                       nonNegativeInteger
160
    
161
    NOutDatas     := N-OUT-DATAS-TYPE TLV-LENGTH
162
                       nonNegativeInteger
163
164
* NInInterests is the total number of incoming Interests since the face is established.
165
* NInDatas is the total number of incoming Datas since the face is established.
166
* NOutInterests is the total number of outgoing Interests since the face is established.
167
* NOutDatas is the total number of outgoing Datas since the face is established.
168
169
170
171
## Face Status Change Notification
172
173
Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`.
174
Events of all faces are sent into the same notification stream.
175
176
The Content of each notification Data packet is a `FaceEvent` block:
177
178
    FaceEvent     := FACE-EVENT-TYPE TLV-LENGTH
179
                       FaceId
180
                       Uri
181
                       FaceEventKind
182
    
183
    FaceEventKind := FACE-EVENT-KIND-TYPE TLV-LENGTH
184
                       nonNegativeInteger
185
186
**FaceEventKind** indicates the kind of event. Its possible values are:
187
188
* **1**: face is created or accepted
189
* **2**: face is destroyed or closed
190
191
192
193 9 Junxiao Shi
## TLV-TYPE assignments
194
195
Type                                        | Assigned value    | Assigned value (hex)
196 2 Alex Afanasyev
------------------------------------------- | ----------------- | --------------------
197 20 Junxiao Shi
FaceStatus                                  | 128               | 0x80
198
NInInterests                                | 144               | 0x90
199
NInDatas                                    | 145               | 0x91
200
NOutInterests                               | 146               | 0x92
201
NOutDatas                                   | 147               | 0x93
202
FaceEvent                                   | 192               | 0xc0
203
FaceEventKind                               | 193               | 0xc1