FaceMgmt » History » Version 24
Alex Afanasyev, 03/20/2014 05:22 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 | * 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 | ## Face Status Change Notification |
||
| 170 | |||
| 171 | Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`. |
||
| 172 | 1 | Junxiao Shi | Events of all faces are sent into the same notification stream. |
| 173 | 20 | Junxiao Shi | |
| 174 | 21 | Alex Afanasyev | The Content of each notification Data packet is a `FaceEventNotification` block: |
| 175 | 20 | Junxiao Shi | |
| 176 | 21 | Alex Afanasyev | FaceEventNotification := FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH |
| 177 | FaceEventKind |
||
| 178 | FaceId |
||
| 179 | Uri |
||
| 180 | 23 | Alex Afanasyev | FaceFlags |
| 181 | 20 | Junxiao Shi | |
| 182 | FaceEventKind := FACE-EVENT-KIND-TYPE TLV-LENGTH |
||
| 183 | nonNegativeInteger |
||
| 184 | |||
| 185 | 23 | Alex Afanasyev | FaceFlags := FACE-FLAGS-TYPE TLV-LENGTH |
| 186 | nonNegativeInteger |
||
| 187 | |||
| 188 | 20 | Junxiao Shi | **FaceEventKind** indicates the kind of event. Its possible values are: |
| 189 | |||
| 190 | * **1**: face is created or accepted |
||
| 191 | * **2**: face is destroyed or closed |
||
| 192 | 23 | Alex Afanasyev | |
| 193 | **FaceFlags** is a bitset, providing additional information about the face. The following bits are currently defined: |
||
| 194 | |||
| 195 | * **1**: face is local |
||
| 196 | * **2**: face is created on demand (e.g., as a response to an incoming connection) |
||
| 197 | |||
| 198 | 9 | Junxiao Shi | ## TLV-TYPE assignments |
| 199 | |||
| 200 | Type | Assigned value | Assigned value (hex) |
||
| 201 | 2 | Alex Afanasyev | ------------------------------------------- | ----------------- | -------------------- |
| 202 | 20 | Junxiao Shi | FaceStatus | 128 | 0x80 |
| 203 | NInInterests | 144 | 0x90 |
||
| 204 | NInDatas | 145 | 0x91 |
||
| 205 | NOutInterests | 146 | 0x92 |
||
| 206 | NOutDatas | 147 | 0x93 |
||
| 207 | 22 | Alex Afanasyev | FaceEventNotification | 192 | 0xc0 |
| 208 | 1 | Junxiao Shi | FaceEventKind | 193 | 0xc1 |
| 209 | 24 | Alex Afanasyev | FaceFlags | 194 | 0xc2 |