Project

General

Profile

ControlCommand » History » Version 38

Davide Pesavento, 02/09/2018 02:28 PM

1 38 Davide Pesavento
{{>toc}}
2 34 Junxiao Shi
3 13 Junxiao Shi
# Control Command
4 1 Junxiao Shi
5 29 Davide Pesavento
**Control Command** is a mechanism of [[Management|NFD Management protocol]]. This mechanism is useful for altering the state of the forwarder.
6 28 Davide Pesavento
This document defines the request and response format of such commands, and how they should be signed and authenticated.
7 1 Junxiao Shi
8
## Request format
9 9 Anonymous
10 26 Junxiao Shi
Control commands are [[ndn-cxx:CommandInterest|Command Interests]] under a NFD management prefix.
11 1 Junxiao Shi
12 22 Junxiao Shi
The Name for a request Interest has the following form:
13 1 Junxiao Shi
14 26 Junxiao Shi
    /<prefix>/<management-module>/<command-verb>/<control-parameters>/<command-interest-components>
15 1 Junxiao Shi
16 23 Junxiao Shi
* *prefix* is a NFD management prefix.
17
  Unless otherwise noted, all commands use `/localhost/nfd` prefix.
18
  Each individual command MAY specify additional prefixes under which that command could be accepted.
19 22 Junxiao Shi
* *management-module* is the name of management module to which the command needs to be dispatched.
20
* *command-verb* is the command to be executed.
21 37 Junxiao Shi
* *control-parameters* is a ControlParameters TLV element wrapped in a NameComponent.
22 26 Junxiao Shi
* *command-interest-components* are four additional components defined by [[ndn-cxx:CommandInterest|Command Interest]] spec.
23 1 Junxiao Shi
24 13 Junxiao Shi
### ControlParameters
25 1 Junxiao Shi
26 37 Junxiao Shi
ControlParameters element contains arguments to the command.
27 1 Junxiao Shi
28 14 Junxiao Shi
    ControlParameters   ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH
29
                              Name?
30
                              FaceId?
31 1 Junxiao Shi
                              Uri?
32 30 Alex Afanasyev
                              LocalUri?
33 14 Junxiao Shi
                              Origin?
34 1 Junxiao Shi
                              Cost?
35 19 Junxiao Shi
                              Capacity?
36 37 Junxiao Shi
                              NCsEntries?
37 1 Junxiao Shi
                              Flags?
38 26 Junxiao Shi
                              Mask?
39 17 Junxiao Shi
                              Strategy?
40
                              ExpirationPeriod?
41 24 Junxiao Shi
                              FacePersistency?
42 1 Junxiao Shi
    
43 24 Junxiao Shi
    ; Name is defined in NDN packet format specification
44 13 Junxiao Shi
    
45 14 Junxiao Shi
    FaceId              ::= FACE-ID-TYPE TLV-LENGTH
46
                              nonNegativeInteger
47 13 Junxiao Shi
    
48 14 Junxiao Shi
    Uri                 ::= URI-TYPE TLV-LENGTH
49
                              RFC3986 URI in UTF-8 encoding
50 30 Alex Afanasyev
    
51
    LocalUri            ::= LOCAL-URI-TYPE TLV-LENGTH
52 31 Alex Afanasyev
                              RFC3986 URI in UTF-8 encoding
53 13 Junxiao Shi
    
54 19 Junxiao Shi
    Origin              ::= ORIGIN-TYPE TLV-LENGTH
55 17 Junxiao Shi
                              nonNegativeInteger
56 1 Junxiao Shi
    
57
    Cost                ::= COST-TYPE TLV-LENGTH
58
                              nonNegativeInteger
59
60
    Capacity            ::= CAPACITY-TYPE TLV-LENGTH 
61
                              nonNegativeInteger
62 37 Junxiao Shi
63
    NCsEntries          ::= N-CS-ENTRIES-TYPE TLV-LENGTH 
64
                              nonNegativeInteger
65
66 1 Junxiao Shi
    Flags               ::= FLAGS-TYPE TLV-LENGTH 
67
                              nonNegativeInteger
68 37 Junxiao Shi
69 26 Junxiao Shi
    Mask                ::= MASK-TYPE TLV-LENGTH 
70
                              nonNegativeInteger
71 37 Junxiao Shi
72 17 Junxiao Shi
    Strategy            ::= STRATEGY-TYPE TLV-LENGTH
73
                              Name
74 37 Junxiao Shi
75 17 Junxiao Shi
    ExpirationPeriod    ::= EXPIRATION-PERIOD-TYPE TLV-LENGTH
76 1 Junxiao Shi
                              nonNegativeInteger  
77 24 Junxiao Shi
78 26 Junxiao Shi
    ; FacePersistency is defined in FaceMgmt section
79 24 Junxiao Shi
80 1 Junxiao Shi
This definition exhausts all possible fields used in existing commands.
81 13 Junxiao Shi
82 1 Junxiao Shi
Each individual command MUST specify:
83 13 Junxiao Shi
84
* a list of required fields: those fields MUST be present
85
* a list of optional fields: those fields MAY be present
86 28 Davide Pesavento
* the semantics of each required and optional field
87 13 Junxiao Shi
88 1 Junxiao Shi
A field that is neither required nor optional for a command MUST NOT be present in a ControlParameter given to that command.
89
90 17 Junxiao Shi
Each individual command MAY impose additional constraints on certain fields.
91 1 Junxiao Shi
92 35 Junxiao Shi
### Flags and Mask
93
94 36 Davide Pesavento
Various commands collect multiple boolean attributes into the **Flags** field as an inclusive OR.
95
Each individual command that uses the Flags field MUST define the meaning of each bit. In the definition, "bit 0" refers to the least significant bit.
96 35 Junxiao Shi
97
The **Mask** field, if accepted by a command, indicates which attributes are being updated.
98 36 Davide Pesavento
In such cases, Flags field and Mask field must be both present or both omitted in the request.
99
Bits in the Mask field are arranged in the same order as the Flags field.
100 1 Junxiao Shi
For example, if a command defines two flags at bit 0 and bit 1 and also accepts a Mask field, a request containing "Flags=0x02 Mask=0x02" specifies bit 1 as "true" and specifies bit 0 as "don't care, leave at default, or keep unchanged"; this request is equivalent to a request containing "Flags=0x03 Mask=0x02".
101 35 Junxiao Shi
102 36 Davide Pesavento
If a command does not accept the **Mask** field, it SHOULD interpret every bit in Flags, and there is no "don't care" bits.
103 35 Junxiao Shi
104 1 Junxiao Shi
## Response format
105
106
A response from the command interface is a Data that matches the request Interest.
107 37 Junxiao Shi
The payload of this Data is a ControlResponse element.
108 1 Junxiao Shi
109
    ControlResponse ::= CONTROL-RESPONSE-TYPE TLV-LENGTH
110
                          StatusCode
111 26 Junxiao Shi
                          StatusText
112 1 Junxiao Shi
                          <body>
113
    
114
    StatusCode      ::= STATUS-CODE-TYPE TLV-LENGTH
115
                          nonNegativeInteger
116
    
117 13 Junxiao Shi
    StatusText      ::= STATUS-TEXT-TYPE TLV-LENGTH
118 2 Junxiao Shi
                          string in UTF-8
119 1 Junxiao Shi
    
120 37 Junxiao Shi
    <body>          ::= zero or more arbitrary TLV elements
121 1 Junxiao Shi
122 13 Junxiao Shi
### StatusCode
123 2 Junxiao Shi
124 28 Davide Pesavento
StatusCode loosely follows the HTTP semantics described in [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6).
125 16 Junxiao Shi
126 28 Davide Pesavento
* Codes between 100 and 399 represent a success.
127
* Codes between 400 and 499 represent a client error.
128
* Codes between 500 and 599 represent a server error.
129 16 Junxiao Shi
130 13 Junxiao Shi
Common codes include:
131 1 Junxiao Shi
132
StatusCode | Description
133
-----------|------------------------
134 13 Junxiao Shi
200        | OK
135 2 Junxiao Shi
400        | ControlParameters is incorrect
136 16 Junxiao Shi
403        | Command Interest is not authorized
137 28 Davide Pesavento
404        | Resource (e.g., face, prefix, ...) not found
138 19 Junxiao Shi
501        | Module or verb is not supported
139
503        | Service not available
140 1 Junxiao Shi
141
Each individual command MAY define additional codes.
142 13 Junxiao Shi
143 1 Junxiao Shi
### \<body>
144 13 Junxiao Shi
145 2 Junxiao Shi
Additional elements are allowed at the end of ControlResponse.
146 13 Junxiao Shi
147 1 Junxiao Shi
Each individual command MAY define the type and meaning of \<body>.
148 14 Junxiao Shi
149 1 Junxiao Shi
Unless otherwise defined by an individual command,
150 14 Junxiao Shi
\<body> is the ControlParameters passed into this command for all successful responses,
151
and \<body> is empty for all failure responses.
152 1 Junxiao Shi
153
## TLV-TYPE assignments
154 13 Junxiao Shi
155 1 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
156
------------------------------------------- | ----------------- | --------------------
157 13 Junxiao Shi
ControlParameters                           | 104               | 0x68
158 1 Junxiao Shi
FaceId                                      | 105               | 0x69
159 13 Junxiao Shi
Uri                                         | 114               | 0x72
160 1 Junxiao Shi
LocalUri                                    | 129               | 0x81
161 33 Alex Afanasyev
Origin                                      | 111               | 0x6f
162 13 Junxiao Shi
Cost                                        | 106               | 0x6a
163 19 Junxiao Shi
Capacity                                    | 131               | 0x83
164 37 Junxiao Shi
NCsEntries                                  | 135               | 0x87
165 1 Junxiao Shi
Flags                                       | 108               | 0x6c
166 26 Junxiao Shi
Mask                                        | 112               | 0x70
167 5 Alex Afanasyev
Strategy                                    | 107               | 0x6b
168 1 Junxiao Shi
ExpirationPeriod                            | 109               | 0x6d
169 24 Junxiao Shi
ControlResponse                             | 101               | 0x65
170 5 Alex Afanasyev
StatusCode                                  | 102               | 0x66
171 13 Junxiao Shi
StatusText                                  | 103               | 0x67
172 26 Junxiao Shi
(reserved, formerly LocalControlFeature)    | 110               | 0x6e