Project

General

Profile

ControlCommand » History » Version 21

Alex Afanasyev, 07/23/2014 04:15 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 21 Alex Afanasyev
Control commands are [[ndn-cxx:SignedInterest|Signed Interests]] under `ndn:/localhost/nfd` prefix.
10 11 Alex Afanasyev
11 20 Junxiao Shi
    /localhost/nfd/<management-module>/<command-verb>/................./.........................................
12
                                                      \______  _______/ \__________________  ___________________/
13
                                                             \/                            \/
14
                                                      ControlParameters   Signed Interest additional components
15 1 Junxiao Shi
16 13 Junxiao Shi
A request Interest has 9 Name components.
17
These components are:
18 1 Junxiao Shi
19
1. "localhost" in UTF-8
20
2. "nfd" in UTF-8
21
3. *management-module* in UTF-8, management module to which the command needs to be dispatched
22
4. *command-verb* in UTF-8, command to be executed
23 13 Junxiao Shi
5. *...*, a ControlParameters TLV block
24 20 Junxiao Shi
6. timestamp of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest)
25
7. nonce of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest)
26
8. SignatureInfo of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest)
27
9. SignatureValue of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest)
28 1 Junxiao Shi
29 13 Junxiao Shi
### ControlParameters
30 1 Junxiao Shi
31 13 Junxiao Shi
ControlParameters block contains arguments to the command.
32 1 Junxiao Shi
33 14 Junxiao Shi
    ControlParameters   ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH
34
                              Name?
35
                              FaceId?
36
                              Uri?
37
                              LocalControlFeature?
38 19 Junxiao Shi
                              Origin?
39 1 Junxiao Shi
                              Cost?
40 19 Junxiao Shi
                              Flags?
41 17 Junxiao Shi
                              Strategy?
42
                              ExpirationPeriod?
43 13 Junxiao Shi
    
44
    // Name is defined in NDN-TLV spec
45
    
46 14 Junxiao Shi
    FaceId              ::= FACE-ID-TYPE TLV-LENGTH
47
                              nonNegativeInteger
48 13 Junxiao Shi
    
49 14 Junxiao Shi
    Uri                 ::= URI-TYPE TLV-LENGTH
50
                              RFC3986 URI in UTF-8 encoding
51 13 Junxiao Shi
    
52 14 Junxiao Shi
    LocalControlFeature ::= LOCAL-CONTROL-FEATURE-TYPE TLV-LENGTH
53
                              nonNegativeInteger
54 13 Junxiao Shi
    
55 19 Junxiao Shi
    Origin              ::= ORIGIN-TYPE TLV-LENGTH
56 17 Junxiao Shi
                              nonNegativeInteger
57
    
58 1 Junxiao Shi
    Cost                ::= COST-TYPE TLV-LENGTH
59
                              nonNegativeInteger
60
    
61 19 Junxiao Shi
    Flags               ::= FLAGS-TYPE TLV-LENGTH 
62
                              nonNegativeInteger
63
    
64 17 Junxiao Shi
    Strategy            ::= STRATEGY-TYPE TLV-LENGTH
65
                              Name
66
    
67
    ExpirationPeriod    ::= EXPIRATION-PERIOD-TYPE TLV-LENGTH
68
                              nonNegativeInteger  
69 13 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 1 Junxiao Shi
* the semantics of each required and optional fields
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 13 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 16 Junxiao Shi
StatusCode generally follows HTTP convention \[[RFC2616](http://tools.ietf.org/html/rfc2616#section-10)\].
103
104
* Codes between 100 and 399 represents a success.
105
* Codes between 400 and 499 represents a client error.
106
* Codes between 500 and 599 represents a server error.
107
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
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 17 Junxiao Shi
and \<body> is empty for all failure responses.
130 14 Junxiao Shi
131 1 Junxiao Shi
## TLV-TYPE assignments
132 13 Junxiao Shi
133 1 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
134
------------------------------------------- | ----------------- | --------------------
135 13 Junxiao Shi
ControlParameters                           | 104               | 0x68
136
FaceId                                      | 105               | 0x69
137 1 Junxiao Shi
Uri                                         | 114               | 0x72
138 13 Junxiao Shi
LocalControlFeature                         | 110               | 0x6e
139 19 Junxiao Shi
Origin                                      | 111               | 0x6f
140 1 Junxiao Shi
Cost                                        | 106               | 0x6a
141 19 Junxiao Shi
Flags                                       | 108               | 0x6c
142 17 Junxiao Shi
Strategy                                    | 107               | 0x6b
143
ExpirationPeriod                            | 109               | 0x6d
144 5 Alex Afanasyev
ControlResponse                             | 101               | 0x65
145
StatusCode                                  | 102               | 0x66
146
StatusText                                  | 103               | 0x67
147 13 Junxiao Shi
148
These types are assigned from the range reserved for forwarding daemon.