Project

General

Profile

ControlCommand » History » Version 6

Alex Afanasyev, 01/30/2014 04: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 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
404        | Command verb is not supported
70
71 2 Junxiao Shi
Additional elements are allowed at the end of **ControlResponse**.
72 1 Junxiao Shi
Each individual command specification defines whether and what can present.
73
74
75
## TLV-TYPE assignments
76
77 5 Alex Afanasyev
(Types are assigned from the range reserved for forwarding daemon.)
78
79 1 Junxiao Shi
Type                                        | Assigned value    | Assigned value (hex)
80
------------------------------------------- | ----------------- | --------------------
81 5 Alex Afanasyev
ControlResponse                             | 101               | 0x65
82
StatusCode                                  | 102               | 0x66
83
StatusText                                  | 103               | 0x67