Project

General

Profile

ControlCommand » History » Version 53

Junxiao Shi, 01/06/2024 04:10 AM
reorder ControlParameters fields according to ndn-cxx:commit:16203ea2b66b14b5035b7b01235a3daed6b70f6f

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