Project

General

Profile

ControlCommand » History » Version 24

Junxiao Shi, 08/20/2015 01:40 PM

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