Project

General

Profile

ControlCommand » History » Version 46

Eric Newberry, 05/23/2018 11:37 AM
Add MTU field

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