Project

General

Profile

ControlCommand » History » Version 16

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