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