Project

General

Profile

ControlCommand » History » Version 23

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