FaceMgmt » History » Version 36
Junxiao Shi, 07/16/2014 05:43 PM
| 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 | 35 | Junxiao Shi | ExpirationPeriod? |
| 153 | 32 | Junxiao Shi | FaceFlags |
| 154 | 20 | Junxiao Shi | NInInterests |
| 155 | NInDatas |
||
| 156 | NOutInterests |
||
| 157 | NOutDatas |
||
| 158 | 36 | Junxiao Shi | NInBytes |
| 159 | NOutBytes |
||
| 160 | 1 | Junxiao Shi | |
| 161 | 32 | Junxiao Shi | LocalUri := LOCAL-URI-TYPE TLV-LENGTH |
| 162 | 1 | Junxiao Shi | RFC3986 URI in UTF-8 encoding |
| 163 | 32 | Junxiao Shi | |
| 164 | FaceFlags := FACE-FLAGS-TYPE TLV-LENGTH |
||
| 165 | nonNegativeInteger |
||
| 166 | 30 | Junxiao Shi | |
| 167 | 20 | Junxiao Shi | NInInterests := N-IN-INTERESTS-TYPE TLV-LENGTH |
| 168 | nonNegativeInteger |
||
| 169 | |||
| 170 | NInDatas := N-IN-DATAS-TYPE TLV-LENGTH |
||
| 171 | 1 | Junxiao Shi | nonNegativeInteger |
| 172 | |||
| 173 | NOutInterests := N-OUT-INTERESTS-TYPE TLV-LENGTH |
||
| 174 | nonNegativeInteger |
||
| 175 | |||
| 176 | NOutDatas := N-OUT-DATAS-TYPE TLV-LENGTH |
||
| 177 | nonNegativeInteger |
||
| 178 | 36 | Junxiao Shi | |
| 179 | NInBytes := N-IN-BYTES-TYPE TLV-LENGTH |
||
| 180 | nonNegativeInteger |
||
| 181 | |||
| 182 | NOutBytes := N-OUT-BYTES-TYPE TLV-LENGTH |
||
| 183 | nonNegativeInteger |
||
| 184 | 1 | Junxiao Shi | |
| 185 | 32 | Junxiao Shi | * **Uri** is a FaceUri representing remote endpoint. |
| 186 | 1 | Junxiao Shi | * **LocalUri** is a FaceUri representing local endpoint. |
| 187 | 35 | Junxiao Shi | * **ExpirationPeriod** is the remaining lifetime of this face. |
| 188 | 34 | Junxiao Shi | If this field is omitted, the face has infinite lifetime. |
| 189 | Currently, this is applicable to on-demand datagram faces only. |
||
| 190 | * **FaceFlags** is a bitset providing additional information about the face. |
||
| 191 | The following bits are currently defined: |
||
| 192 | 32 | Junxiao Shi | * **1**: face is local |
| 193 | * **2**: face is on demand - accepted incoming connection, instead of initiated outgoing connection |
||
| 194 | * **NInInterests** is the total number of incoming Interests since the face is established. |
||
| 195 | * **NInDatas** is the total number of incoming Datas since the face is established. |
||
| 196 | * **NOutInterests** is the total number of outgoing Interests since the face is established. |
||
| 197 | * **NOutDatas** is the total number of outgoing Datas since the face is established. |
||
| 198 | 36 | Junxiao Shi | * **NInBytes** counts the number of bytes of link layer packets received via this face. |
| 199 | This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range. |
||
| 200 | * **NOutBytes** counts the number of bytes of link layer packets sent via this face. |
||
| 201 | This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range. |
||
| 202 | 20 | Junxiao Shi | |
| 203 | 33 | Junxiao Shi | ## Channel Dataset |
| 204 | |||
| 205 | Description of all active channels is published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/channels`. |
||
| 206 | |||
| 207 | Each channel is represented by a **ChannelStatus** block: |
||
| 208 | |||
| 209 | ChannelStatus := CHANNEL-STATUS-TYPE TLV-LENGTH |
||
| 210 | LocalUri |
||
| 211 | |||
| 212 | * **LocalUri** is a FaceUri representing local endpoint. |
||
| 213 | |||
| 214 | 20 | Junxiao Shi | ## Face Status Change Notification |
| 215 | |||
| 216 | Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`. |
||
| 217 | 21 | Alex Afanasyev | Notifications of all faces are sent into the same notification stream. |
| 218 | 20 | Junxiao Shi | |
| 219 | 21 | Alex Afanasyev | The Content of each notification Data packet is a `FaceEventNotification` block: |
| 220 | |||
| 221 | 25 | Junxiao Shi | FaceEventNotification := FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH |
| 222 | 20 | Junxiao Shi | FaceEventKind |
| 223 | 25 | Junxiao Shi | FaceId |
| 224 | Uri |
||
| 225 | 1 | Junxiao Shi | LocalUri |
| 226 | 23 | Alex Afanasyev | FaceFlags |
| 227 | 20 | Junxiao Shi | |
| 228 | FaceEventKind := FACE-EVENT-KIND-TYPE TLV-LENGTH |
||
| 229 | 25 | Junxiao Shi | nonNegativeInteger |
| 230 | |||
| 231 | 23 | Alex Afanasyev | **FaceEventKind** indicates the kind of event. Its possible values are: |
| 232 | 25 | Junxiao Shi | |
| 233 | 23 | Alex Afanasyev | * **1**: face is created |
| 234 | * **2**: face is destroyed |
||
| 235 | 25 | Junxiao Shi | |
| 236 | 23 | Alex Afanasyev | ## TLV-TYPE assignments |
| 237 | 9 | Junxiao Shi | |
| 238 | Type | Assigned value | Assigned value (hex) |
||
| 239 | ------------------------------------------- | ----------------- | -------------------- |
||
| 240 | 1 | Junxiao Shi | FaceStatus | 128 | 0x80 |
| 241 | 34 | Junxiao Shi | LocalUri | 129 | 0x81 |
| 242 | 33 | Junxiao Shi | ChannelStatus | 130 | 0x82 |
| 243 | 32 | Junxiao Shi | FaceFlags | 194 | 0xc2 |
| 244 | 20 | Junxiao Shi | NInInterests | 144 | 0x90 |
| 245 | NInDatas | 145 | 0x91 |
||
| 246 | NOutInterests | 146 | 0x92 |
||
| 247 | 22 | Alex Afanasyev | NOutDatas | 147 | 0x93 |
| 248 | 36 | Junxiao Shi | NInBytes | 148 | 0x94 |
| 249 | NOutBytes | 149 | 0x95 |
||
| 250 | 1 | Junxiao Shi | FaceEventNotification | 192 | 0xc0 |
| 251 | 24 | Alex Afanasyev | FaceEventKind | 193 | 0xc1 |