Project

General

Profile

ControlCommand » History » Version 30

Alex Afanasyev, 03/27/2017 04:34 PM

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