Project

General

Profile

ControlCommand » History » Version 35

Junxiao Shi, 01/21/2018 04:45 PM

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