FaceMgmt » History » Version 26
Junxiao Shi, 03/24/2014 07:42 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 | 20 | Junxiao Shi | ## Control Commands |
| 81 | 1 | Junxiao Shi | |
| 82 | 20 | Junxiao Shi | [[ControlCommand]] **management-module**: `faces` |
| 83 | |||
| 84 | 1 | Junxiao Shi | ### Create a face |
| 85 | |||
| 86 | 20 | Junxiao Shi | **command-verb**: `create` |
| 87 | 1 | Junxiao Shi | |
| 88 | 20 | Junxiao Shi | ControlParameters fields: |
| 89 | 1 | Junxiao Shi | |
| 90 | 20 | Junxiao Shi | * Uri (required): a FaceUri that represents a UDP unicast tunnel or a TCP tunnel |
| 91 | 1 | Junxiao Shi | |
| 92 | 20 | Junxiao Shi | This command allows creation of UDP unicast and TCP faces only. |
| 93 | If another face exists for the same underlying protocol and address, the command is considered successful, and FaceId of that face is returned. |
||
| 94 | 1 | Junxiao Shi | |
| 95 | 20 | Junxiao Shi | If the command succeeds, \<Body> in ControlResponse block contains updated ControlParameters: |
| 96 | 1 | Junxiao Shi | |
| 97 | 20 | Junxiao Shi | * FaceId |
| 98 | * Uri: FaceUri in canonical form - hostname is substituted with IP address, scheme name indicates either IPv4 or IPv6 |
||
| 99 | 1 | Junxiao Shi | |
| 100 | ### Destroy a face |
||
| 101 | |||
| 102 | **command-verb:** `destroy` |
||
| 103 | |||
| 104 | 20 | Junxiao Shi | ControlParameters fields: |
| 105 | 1 | Junxiao Shi | |
| 106 | 20 | Junxiao Shi | * FaceId (required) |
| 107 | 1 | Junxiao Shi | |
| 108 | If the specified face does not exist, this command does nothing, but is still considered successful. |
||
| 109 | |||
| 110 | 20 | Junxiao Shi | ### Enable a LocalControlHeader feature |
| 111 | |||
| 112 | **command-verb**: `enable-local-control` |
||
| 113 | |||
| 114 | ControlParameters fields: |
||
| 115 | |||
| 116 | * LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId |
||
| 117 | |||
| 118 | 26 | Junxiao Shi | This command can only operate on the requesting face. |
| 119 | 20 | Junxiao Shi | |
| 120 | ### Disable a LocalControlHeader feature |
||
| 121 | |||
| 122 | **command-verb**: `disable-local-control` |
||
| 123 | 1 | Junxiao Shi | |
| 124 | 20 | Junxiao Shi | ControlParameters fields: |
| 125 | |||
| 126 | * LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId |
||
| 127 | |||
| 128 | 26 | Junxiao Shi | This command can only operate on the requesting face. |
| 129 | 20 | Junxiao Shi | |
| 130 | |||
| 131 | ## Face Dataset |
||
| 132 | |||
| 133 | Description and counters of all active faces are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/faces/list`. |
||
| 134 | |||
| 135 | Each face is represented by a **FaceStatus** blocks: |
||
| 136 | |||
| 137 | FaceStatus := FACE-STATUS-TYPE TLV-LENGTH |
||
| 138 | FaceId |
||
| 139 | Uri |
||
| 140 | NInInterests |
||
| 141 | NInDatas |
||
| 142 | NOutInterests |
||
| 143 | NOutDatas |
||
| 144 | |||
| 145 | NInInterests := N-IN-INTERESTS-TYPE TLV-LENGTH |
||
| 146 | nonNegativeInteger |
||
| 147 | |||
| 148 | NInDatas := N-IN-DATAS-TYPE TLV-LENGTH |
||
| 149 | nonNegativeInteger |
||
| 150 | |||
| 151 | NOutInterests := N-OUT-INTERESTS-TYPE TLV-LENGTH |
||
| 152 | nonNegativeInteger |
||
| 153 | |||
| 154 | NOutDatas := N-OUT-DATAS-TYPE TLV-LENGTH |
||
| 155 | nonNegativeInteger |
||
| 156 | |||
| 157 | * NInInterests is the total number of incoming Interests since the face is established. |
||
| 158 | * NInDatas is the total number of incoming Datas since the face is established. |
||
| 159 | * NOutInterests is the total number of outgoing Interests since the face is established. |
||
| 160 | * NOutDatas is the total number of outgoing Datas since the face is established. |
||
| 161 | |||
| 162 | ## Face Status Change Notification |
||
| 163 | |||
| 164 | Face status change events are published as a [[Notification|Notification Stream]] at `ndn:/localhost/nfd/faces/events`. |
||
| 165 | 1 | Junxiao Shi | Events of all faces are sent into the same notification stream. |
| 166 | 20 | Junxiao Shi | |
| 167 | 21 | Alex Afanasyev | The Content of each notification Data packet is a `FaceEventNotification` block: |
| 168 | 20 | Junxiao Shi | |
| 169 | 21 | Alex Afanasyev | FaceEventNotification := FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH |
| 170 | FaceEventKind |
||
| 171 | FaceId |
||
| 172 | Uri |
||
| 173 | 23 | Alex Afanasyev | FaceFlags |
| 174 | 20 | Junxiao Shi | |
| 175 | 25 | Junxiao Shi | FaceEventKind := FACE-EVENT-KIND-TYPE TLV-LENGTH |
| 176 | nonNegativeInteger |
||
| 177 | 20 | Junxiao Shi | |
| 178 | 25 | Junxiao Shi | FaceFlags := FACE-FLAGS-TYPE TLV-LENGTH |
| 179 | nonNegativeInteger |
||
| 180 | 23 | Alex Afanasyev | |
| 181 | 20 | Junxiao Shi | **FaceEventKind** indicates the kind of event. Its possible values are: |
| 182 | |||
| 183 | 25 | Junxiao Shi | * **1**: face is created |
| 184 | * **2**: face is destroyed |
||
| 185 | 23 | Alex Afanasyev | |
| 186 | 25 | Junxiao Shi | **FaceFlags** is a bitset, providing additional information about the face. The following bits are currently defined: |
| 187 | 23 | Alex Afanasyev | |
| 188 | * **1**: face is local |
||
| 189 | 25 | Junxiao Shi | * **2**: face is on demand - accepted incoming connection, instead of initiated outgoing connection |
| 190 | 23 | Alex Afanasyev | |
| 191 | 9 | Junxiao Shi | ## TLV-TYPE assignments |
| 192 | |||
| 193 | Type | Assigned value | Assigned value (hex) |
||
| 194 | 2 | Alex Afanasyev | ------------------------------------------- | ----------------- | -------------------- |
| 195 | 20 | Junxiao Shi | FaceStatus | 128 | 0x80 |
| 196 | NInInterests | 144 | 0x90 |
||
| 197 | NInDatas | 145 | 0x91 |
||
| 198 | NOutInterests | 146 | 0x92 |
||
| 199 | NOutDatas | 147 | 0x93 |
||
| 200 | 22 | Alex Afanasyev | FaceEventNotification | 192 | 0xc0 |
| 201 | 1 | Junxiao Shi | FaceEventKind | 193 | 0xc1 |
| 202 | 24 | Alex Afanasyev | FaceFlags | 194 | 0xc2 |