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