Project

General

Profile

FaceMgmt » History » Version 16

Alex Afanasyev, 02/15/2014 09:13 PM

1 1 Junxiao Shi
# NFD Face Management protocol
2
3 9 Junxiao Shi
The **Face Management protocol** allows an entity to request NFD daemon create and destroy faces.
4 2 Alex Afanasyev
5 16 Alex Afanasyev
The Face Management protocol uses [[|Command Interests|Signed Command Interests]] to authenticate each issued command.
6 2 Alex Afanasyev
7
## Command format
8
9
### Request
10
11 1 Junxiao Shi
Request is a [[Command Interests|Command Interest]] with the following name:
12
13 15 Alex Afanasyev
    /localhost/nfd/faces/<command-verb>/<command-options>/.....................
14 2 Alex Afanasyev
15 15 Alex Afanasyev
    \                  / \                              / \                   /
16
     --------  --------   -------------  ---------------   --------  ---------
17
             \/                        \/                          \/
18
    NFD Control Command       FaceManager command           Command Interest
19
    to FaceManager            and command options          related information
20 2 Alex Afanasyev
21
22 9 Junxiao Shi
Command options is defined as a TLV-encoded `FaceManagementOptions` block.
23
Each individual command defines a subset of required and optional elements in the `FaceManagementOptions` block.
24 2 Alex Afanasyev
25 1 Junxiao Shi
    FaceManagementOptions ::= FACE-MANAGEMENT-OPTIONS-TYPE TLV-LENGTH
26
                               FaceId?
27 9 Junxiao Shi
                               Uri?
28 1 Junxiao Shi
    
29 14 Junxiao Shi
    FaceId                ::= FACEID-TYPE TLV-LENGTH
30
                                nonNegativeInteger
31 9 Junxiao Shi
    
32 14 Junxiao Shi
    Uri                   ::= URI-TYPE TLV-LENGTH
33
                                RFC3986 URI in UTF-8 encoding
34 1 Junxiao Shi
35
### Response
36
37 12 Alex Afanasyev
Command response is a Data packet that contains TLV-encoded ``ControlResponse`` block, defined in [[ControlCommand|NFD Control Command specification]].
38 1 Junxiao Shi
39 12 Alex Afanasyev
Content of ``ControlResponse`` on success:
40 1 Junxiao Shi
41 12 Alex Afanasyev
Field in ``ControlResponse`` block | Value
42
---------------------------------- | -----
43
``StatusCode``                     | 200
44
``StatusText``                     | "Success"
45
``<StatusBody>``                   | ``FaceManagementOptions`` block, either echoed or with updated ``Uri``---hostname replaced with IP address---and ``FaceId`` fields
46 1 Junxiao Shi
47 12 Alex Afanasyev
Content of ``ControlResponse`` on error:
48
49
Field in ``ControlResponse`` block | Value
50
---------------------------------- | -----
51
``StatusCode``                     | 4xx, 500x, or other error codes based on RFC2616
52
``StatusText``                     | Human-readable description of the error
53
``<StatusBody>``                   | Not present
54
55 9 Junxiao Shi
## URI
56 1 Junxiao Shi
57 9 Junxiao Shi
The underlying protocol and underlying address of a Face is expressed as a URI.
58 2 Alex Afanasyev
59 9 Junxiao Shi
### UDP unicast
60 2 Alex Afanasyev
61 9 Junxiao Shi
`udp[4|6]://<remote-IP-or-host>[:<remote-port>]`
62 1 Junxiao Shi
63 9 Junxiao Shi
Examples:
64 1 Junxiao Shi
65 9 Junxiao Shi
* `udp://192.0.2.1:6363` (canonical form)
66
* `udp://192.0.2.1` (remote-port defaults to 6363)
67
* `udp://[2001:db8::1]:6363` (canonical form)
68
* `udp://example.net:6363`
69
* `udp4://example.net:6363` (resolve hostname to IPv4 address only)
70
* `udp6://example.net:6363` (resolve hostname to IPv6 address only)
71 1 Junxiao Shi
72 9 Junxiao Shi
### UDP multicast
73 1 Junxiao Shi
74 9 Junxiao Shi
`udp-mcast://<multicast-IP>:<multicast-port>`
75 1 Junxiao Shi
76 9 Junxiao Shi
Examples:
77 1 Junxiao Shi
78 9 Junxiao Shi
* `udp://224.0.23.170:56363`
79 1 Junxiao Shi
80 9 Junxiao Shi
### TCP
81 1 Junxiao Shi
82 9 Junxiao Shi
`tcp[4|6]://<remote-IP-or-host>[:<remote-port>]`
83
84
Examples:
85
86
* `tcp://192.0.2.1:6363` (canonical form)
87
* `tcp://192.0.2.1` (remote-port defaults to 6363)
88
* `tcp://[2001:db8::1]:6363` (canonical form)
89
* `tcp://example.net:6363`
90
* `tcp4://example.net:6363` (resolve hostname to IPv4 address only)
91
* `tcp6://example.net:6363` (resolve hostname to IPv6 address only)
92
93
### UNIX stream
94
95
`unix://<path>`
96
97
Examples:
98
99
* `unix:///var/run/nfd.sock` (note there are three forward-slashes after 'unix')
100
101
URI is available for the channel only.
102
Accepted UNIX stream faces do not have URI.
103
104
### Ethernet unicast
105
106
`ether://<remote-MAC>`
107
108
Examples:
109
110
* `ether://08:00:27:01:01:01`
111
112
### Ethernet multicast
113
114
`ether-mcast://<multicast-MAC>`
115
116
Examples:
117
118
* `ether-mcast://33:33:01:01:01:01`
119
120
## Operations
121
122
**Face management protocol** protocol supports two operations:
123
124
* create a face (command-verb: `create`)
125
* destroy a face (command-verb: `destroy`)
126
127
### Create a face
128
129
**command-verb:** `create`
130
131
Required fields in `FaceManagementOptions` block:
132
133
* `Uri`
134
135
This command allows creation of UDP unicast and TCP faces only.
136
137
If the command succeeds, the `ControlResponse` block in the response contains a `FaceManagementOptions` block, which contains:
138
139
* `FaceId`
140 10 Junxiao Shi
* `Uri`, the canonical URI
141 9 Junxiao Shi
142 10 Junxiao Shi
If another face exists for the same underlying protocol and address, the command is considered successful, and that face is returned.
143
144 9 Junxiao Shi
### Destroy a face
145
146
**command-verb:** `destroy`
147
148
Required fields in `FaceManagementOptions` block:
149
150
* `FaceId`
151
152
If the specified face does not exist, this command does nothing, but is still considered successful.
153 2 Alex Afanasyev
154
## TLV-TYPE assignments
155 1 Junxiao Shi
156 2 Alex Afanasyev
Type                                        | Assigned value    | Assigned value (hex)
157
------------------------------------------- | ----------------- | --------------------
158
FaceManagementOptions                       | 108               | 0x6c
159 9 Junxiao Shi
FaceId                                      | 105               | 0x69
160 13 Alex Afanasyev
Uri                                         | 114               | 0x72