Project

General

Profile

FaceMgmt » History » Version 13

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