Project

General

Profile

ControlCommand » History » Version 26

Junxiao Shi, 08/11/2016 10:35 AM

1 13 Junxiao Shi
# Control Command
2 1 Junxiao Shi
3 13 Junxiao Shi
**Control Command** is a mechanism of [[Management|NFD Management protocol]].
4
This document defines the request and response format of commands that can alter forwarder state, and how these commands should be signed and authenticated.
5
This mechanism is useful for altering forwarder state.
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 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 13 Junxiao Shi
    
47 19 Junxiao Shi
    Origin              ::= ORIGIN-TYPE TLV-LENGTH
48 17 Junxiao Shi
                              nonNegativeInteger
49 1 Junxiao Shi
    
50
    Cost                ::= COST-TYPE TLV-LENGTH
51
                              nonNegativeInteger
52 17 Junxiao Shi
    
53 1 Junxiao Shi
    Flags               ::= FLAGS-TYPE TLV-LENGTH 
54
                              nonNegativeInteger
55
    
56 26 Junxiao Shi
    Mask                ::= MASK-TYPE TLV-LENGTH 
57
                              nonNegativeInteger
58
    
59 17 Junxiao Shi
    Strategy            ::= STRATEGY-TYPE TLV-LENGTH
60
                              Name
61
    
62
    ExpirationPeriod    ::= EXPIRATION-PERIOD-TYPE TLV-LENGTH
63 1 Junxiao Shi
                              nonNegativeInteger  
64 24 Junxiao Shi
65 26 Junxiao Shi
    ; FacePersistency is defined in FaceMgmt section
66 24 Junxiao Shi
67 1 Junxiao Shi
This definition exhausts all possible fields used in existing commands.
68 13 Junxiao Shi
69 1 Junxiao Shi
Each individual command MUST specify:
70 13 Junxiao Shi
71
* a list of required fields: those fields MUST be present
72
* a list of optional fields: those fields MAY be present
73 1 Junxiao Shi
* the semantics of each required and optional fields
74 13 Junxiao Shi
75 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.
76
77 17 Junxiao Shi
Each individual command MAY impose additional constraints on certain fields.
78 1 Junxiao Shi
79
## Response format
80
81
A response from the command interface is a Data that matches the request Interest.
82 13 Junxiao Shi
The payload of this Data is a ControlResponse block.
83 1 Junxiao Shi
84
    ControlResponse ::= CONTROL-RESPONSE-TYPE TLV-LENGTH
85
                          StatusCode
86
                          StatusText
87 26 Junxiao Shi
                          <body>
88 1 Junxiao Shi
    
89
    StatusCode      ::= STATUS-CODE-TYPE TLV-LENGTH
90
                          nonNegativeInteger
91
    
92 13 Junxiao Shi
    StatusText      ::= STATUS-TEXT-TYPE TLV-LENGTH
93 2 Junxiao Shi
                          string in UTF-8
94 1 Junxiao Shi
    
95 20 Junxiao Shi
    <body>          ::= zero or more arbitrary TLV blocks
96 1 Junxiao Shi
97 13 Junxiao Shi
### StatusCode
98 2 Junxiao Shi
99 16 Junxiao Shi
StatusCode generally follows HTTP convention \[[RFC2616](http://tools.ietf.org/html/rfc2616#section-10)\].
100
101
* Codes between 100 and 399 represents a success.
102
* Codes between 400 and 499 represents a client error.
103
* Codes between 500 and 599 represents a server error.
104
105 13 Junxiao Shi
Common codes include:
106 1 Junxiao Shi
107
StatusCode | Description
108
-----------|------------------------
109 13 Junxiao Shi
200        | OK
110 2 Junxiao Shi
400        | ControlParameters is incorrect
111 16 Junxiao Shi
403        | Command Interest is not authorized
112
404        | Resource (e.g. face, prefix, ...) not found
113 19 Junxiao Shi
501        | Module or verb is not supported
114
503        | Service not available
115 1 Junxiao Shi
116
Each individual command MAY define additional codes.
117 13 Junxiao Shi
118 1 Junxiao Shi
### \<body>
119 13 Junxiao Shi
120 2 Junxiao Shi
Additional elements are allowed at the end of ControlResponse.
121 13 Junxiao Shi
122 1 Junxiao Shi
Each individual command MAY define the type and meaning of \<body>.
123 14 Junxiao Shi
124 1 Junxiao Shi
Unless otherwise defined by an individual command,
125 14 Junxiao Shi
\<body> is the ControlParameters passed into this command for all successful responses,
126
and \<body> is empty for all failure responses.
127 1 Junxiao Shi
128
## TLV-TYPE assignments
129 13 Junxiao Shi
130 1 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
131 13 Junxiao Shi
------------------------------------------- | ----------------- | --------------------
132 1 Junxiao Shi
ControlParameters                           | 104               | 0x68
133 13 Junxiao Shi
FaceId                                      | 105               | 0x69
134 1 Junxiao Shi
Uri                                         | 114               | 0x72
135 13 Junxiao Shi
Origin                                      | 111               | 0x6f
136 19 Junxiao Shi
Cost                                        | 106               | 0x6a
137 1 Junxiao Shi
Flags                                       | 108               | 0x6c
138 26 Junxiao Shi
Mask                                        | 112               | 0x70
139 5 Alex Afanasyev
Strategy                                    | 107               | 0x6b
140 1 Junxiao Shi
ExpirationPeriod                            | 109               | 0x6d
141 24 Junxiao Shi
ControlResponse                             | 101               | 0x65
142 5 Alex Afanasyev
StatusCode                                  | 102               | 0x66
143 13 Junxiao Shi
StatusText                                  | 103               | 0x67
144 26 Junxiao Shi
(reserved, formerly LocalControlFeature)    | 110               | 0x6e