Project

General

Profile

ControlCommand » History » Version 10

Anonymous, 02/04/2014 08:20 PM

1 1 Junxiao Shi
# NFD Control Command specification
2
3
NFD management module exposes a command interface as Interest-Data exchange.
4
Commands provided over this interface are useful for querying or changing the state of NFD forwarder.
5
6
## Request format
7
8 9 Anonymous
A request to the command interface is an Interest under ``ndn:/localhost/nfd/<management-module>/<command-verb>/...`` prefix.
9 1 Junxiao Shi
10 8 Anonymous
A request Interest has at least five Name components.
11
The first five components are:
12 1 Junxiao Shi
13
1. "localhost" in UTF-8
14 2 Junxiao Shi
2. "nfd" in UTF-8
15 1 Junxiao Shi
3. *management-module* in UTF-8, management module to which the command needs to be dispatched
16 8 Anonymous
4. *command-verb* in UTF-8, command to be executed
17
5. *...*, the arguments to the command, defined for each management module in separate specifications:
18 4 Alex Afanasyev
   
19
    - [[FibMgmt|FIB Management specification]]
20 7 Alex Afanasyev
    - [[FaceMgmt|Face Management specification]]
21 1 Junxiao Shi
22
### Signed request and Unsigned request
23
24
Most commands require a signature to be included in the Name.
25
The signature format is defined in [[Signed Interests]] spec.
26 8 Anonymous
A signed request Interest has eight Name components.
27 1 Junxiao Shi
28
Certain commands that do not change the forwarder state do not require a signature.
29 8 Anonymous
An unsigned request Interest has five Name components.
30 1 Junxiao Shi
31
Each individual command specification defines whether a request Interest using that command verb should be signed or not.
32
33
### Options
34
35
The *option* component contains arguments to the command as a TLV.
36
37
This component is required even if the command verb does not need any arguments.
38
In that case, this component would have zero length.
39
40
Each individual command specification defines the format of the options TLV.
41
The TLV-TYPE numbers used in this TLV should be allocated from application range, and are not required to be unique across different command verbs.
42
43
## Response format
44
45
A response from the command interface is a Data that matches the request Interest.
46 2 Junxiao Shi
The payload in this Data should be a ControlCommandResponse element.
47 1 Junxiao Shi
48 2 Junxiao Shi
    ControlResponse ::= CONTROL-RESPONSE-TYPE TLV-LENGTH
49
                          StatusCode
50
                          StatusText
51 6 Alex Afanasyev
                          <StatusBody>?
52 1 Junxiao Shi
    
53 2 Junxiao Shi
    StatusCode      ::= STATUS-CODE-TYPE TLV-LENGTH
54
                          nonNegativeInteger
55 1 Junxiao Shi
    
56 2 Junxiao Shi
    StatusText      ::= STATUS-TEXT TLV-LENGTH
57 1 Junxiao Shi
                          string in UTF-8
58 6 Alex Afanasyev
    
59
    <StatusBody>    ::= <TLV block defined by the specific control protocol>
60 1 Junxiao Shi
61
**StatusCode** generally follows HTTP convention. Common codes include:
62
63
StatusCode | Description
64
-----------|------------------------
65 2 Junxiao Shi
200        | OK
66 1 Junxiao Shi
400        | Arguments are incorrect
67
401        | Signed request is required for command, but unsigned request is passed
68
403        | Signing key is not authorized for this command
69 10 Anonymous
404        | Resource (e.g. face, prefix, ...) not found
70
501        | Command verb is not supported
71 1 Junxiao Shi
72 2 Junxiao Shi
Additional elements are allowed at the end of **ControlResponse**.
73 1 Junxiao Shi
Each individual command specification defines whether and what can present.
74
75
76
## TLV-TYPE assignments
77
78 5 Alex Afanasyev
(Types are assigned from the range reserved for forwarding daemon.)
79
80 1 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
81
------------------------------------------- | ----------------- | --------------------
82 5 Alex Afanasyev
ControlResponse                             | 101               | 0x65
83
StatusCode                                  | 102               | 0x66
84
StatusText                                  | 103               | 0x67