Project

General

Profile

ControlCommand » History » Version 4

Alex Afanasyev, 01/30/2014 12:27 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
7
## Request format
8
9 4 Alex Afanasyev
A request to the command interface is an Interest under ``ndn:/localhost/nfd/<management-module>/...`` prefix.
10 1 Junxiao Shi
11
A request Interest has at least four Name components.
12
The first four components are:
13
14 2 Junxiao Shi
1. "localhost" in UTF-8
15 1 Junxiao Shi
2. "nfd" in UTF-8
16 4 Alex Afanasyev
3. *management-module* in UTF-8, management module to which the command needs to be dispatched
17
4. *...*, the arguments to the command, defined for each management module in separate specifications:
18
   
19
    - [[FibMgmt|FIB Management specification]]
20 1 Junxiao Shi
21
### Signed request and Unsigned request
22
23
Most commands require a signature to be included in the Name.
24
The signature format is defined in [[Signed Interests]] spec.
25
A signed request Interest has seven Name components.
26
27
Certain commands that do not change the forwarder state do not require a signature.
28
An unsigned request Interest has four Name components.
29
30
Each individual command specification defines whether a request Interest using that command verb should be signed or not.
31
32
### Options
33
34
The *option* component contains arguments to the command as a TLV.
35
36
This component is required even if the command verb does not need any arguments.
37
In that case, this component would have zero length.
38
39
Each individual command specification defines the format of the options TLV.
40
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.
41
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
                          ...
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
                          string in UTF-8
58 1 Junxiao Shi
59
**StatusCode** generally follows HTTP convention. Common codes include:
60
61
StatusCode | Description
62
-----------|------------------------
63 2 Junxiao Shi
200        | OK
64 1 Junxiao Shi
400        | Arguments are incorrect
65
401        | Signed request is required for command, but unsigned request is passed
66
403        | Signing key is not authorized for this command
67
404        | Command verb is not supported
68
69 2 Junxiao Shi
Additional elements are allowed at the end of **ControlResponse**.
70 1 Junxiao Shi
Each individual command specification defines whether and what can present.
71
72
73
## TLV-TYPE assignments
74
75
Type                                        | Assigned value    | Assigned value (hex)
76
------------------------------------------- | ----------------- | --------------------
77 3 Junxiao Shi
ControlResponse                             | 130               | 0x82
78 1 Junxiao Shi
StatusCode                                  | 139               | 0x8b
79
StatusText                                  | 140               | 0x8c