Project

General

Profile

ControlCommand » History » Version 42

Eric Newberry, 03/06/2018 02:35 PM

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