Project

General

Profile

ControlCommand » History » Version 34

Junxiao Shi, 01/09/2018 08:22 AM

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
## Response format
88
89
A response from the command interface is a Data that matches the request Interest.
90 13 Junxiao Shi
The payload of this Data is a ControlResponse block.
91 1 Junxiao Shi
92
    ControlResponse ::= CONTROL-RESPONSE-TYPE TLV-LENGTH
93
                          StatusCode
94
                          StatusText
95 26 Junxiao Shi
                          <body>
96 1 Junxiao Shi
    
97
    StatusCode      ::= STATUS-CODE-TYPE TLV-LENGTH
98
                          nonNegativeInteger
99
    
100 13 Junxiao Shi
    StatusText      ::= STATUS-TEXT-TYPE TLV-LENGTH
101 2 Junxiao Shi
                          string in UTF-8
102 1 Junxiao Shi
    
103 20 Junxiao Shi
    <body>          ::= zero or more arbitrary TLV blocks
104 1 Junxiao Shi
105 13 Junxiao Shi
### StatusCode
106 2 Junxiao Shi
107 28 Davide Pesavento
StatusCode loosely follows the HTTP semantics described in [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6).
108 16 Junxiao Shi
109 28 Davide Pesavento
* Codes between 100 and 399 represent a success.
110
* Codes between 400 and 499 represent a client error.
111
* Codes between 500 and 599 represent a server error.
112 16 Junxiao Shi
113 13 Junxiao Shi
Common codes include:
114 1 Junxiao Shi
115
StatusCode | Description
116
-----------|------------------------
117 13 Junxiao Shi
200        | OK
118 2 Junxiao Shi
400        | ControlParameters is incorrect
119 16 Junxiao Shi
403        | Command Interest is not authorized
120 28 Davide Pesavento
404        | Resource (e.g., face, prefix, ...) not found
121 19 Junxiao Shi
501        | Module or verb is not supported
122
503        | Service not available
123 1 Junxiao Shi
124
Each individual command MAY define additional codes.
125 13 Junxiao Shi
126 1 Junxiao Shi
### \<body>
127 13 Junxiao Shi
128 2 Junxiao Shi
Additional elements are allowed at the end of ControlResponse.
129 13 Junxiao Shi
130 1 Junxiao Shi
Each individual command MAY define the type and meaning of \<body>.
131 14 Junxiao Shi
132 1 Junxiao Shi
Unless otherwise defined by an individual command,
133 14 Junxiao Shi
\<body> is the ControlParameters passed into this command for all successful responses,
134
and \<body> is empty for all failure responses.
135 1 Junxiao Shi
136
## TLV-TYPE assignments
137 13 Junxiao Shi
138 1 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
139 13 Junxiao Shi
------------------------------------------- | ----------------- | --------------------
140 1 Junxiao Shi
ControlParameters                           | 104               | 0x68
141 13 Junxiao Shi
FaceId                                      | 105               | 0x69
142 1 Junxiao Shi
Uri                                         | 114               | 0x72
143 33 Alex Afanasyev
LocalUri                                    | 129               | 0x81
144 13 Junxiao Shi
Origin                                      | 111               | 0x6f
145 19 Junxiao Shi
Cost                                        | 106               | 0x6a
146 34 Junxiao Shi
Capacity                                    | 131               | 0x83
147 1 Junxiao Shi
Flags                                       | 108               | 0x6c
148 26 Junxiao Shi
Mask                                        | 112               | 0x70
149 5 Alex Afanasyev
Strategy                                    | 107               | 0x6b
150 1 Junxiao Shi
ExpirationPeriod                            | 109               | 0x6d
151 24 Junxiao Shi
ControlResponse                             | 101               | 0x65
152 5 Alex Afanasyev
StatusCode                                  | 102               | 0x66
153 13 Junxiao Shi
StatusText                                  | 103               | 0x67
154 26 Junxiao Shi
(reserved, formerly LocalControlFeature)    | 110               | 0x6e