ControlCommand » History » Revision 30
Revision 29 (Davide Pesavento, 02/13/2017 11:59 AM) → Revision 30/53 (Alex Afanasyev, 03/27/2017 04:34 PM)
# Control Command
**Control Command** is a mechanism of [[Management|NFD Management protocol]]. This mechanism is useful for altering the state of the forwarder.
This document defines the request and response format of such commands, and how they should be signed and authenticated.
## Request format
Control commands are [[ndn-cxx:CommandInterest|Command Interests]] under a NFD management prefix.
The Name for a request Interest has the following form:
/<prefix>/<management-module>/<command-verb>/<control-parameters>/<command-interest-components>
* *prefix* is a NFD management prefix.
Unless otherwise noted, all commands use `/localhost/nfd` prefix.
Each individual command MAY specify additional prefixes under which that command could be accepted.
* *management-module* is the name of management module to which the command needs to be dispatched.
* *command-verb* is the command to be executed.
* *control-parameters* is a ControlParameters TLV block wrapped in a NameComponent.
* *command-interest-components* are four additional components defined by [[ndn-cxx:CommandInterest|Command Interest]] spec.
### ControlParameters
ControlParameters block contains arguments to the command.
ControlParameters ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH
Name?
FaceId?
Uri?
LocalUri?
Origin?
Cost?
Flags?
Mask?
Strategy?
ExpirationPeriod?
FacePersistency?
; Name is defined in NDN packet format specification
FaceId ::= FACE-ID-TYPE TLV-LENGTH
nonNegativeInteger
Uri ::= URI-TYPE TLV-LENGTH
RFC3986 URI in UTF-8 encoding
LocalUri ::= LOCAL-URI-TYPE TLV-LENGTH
Uri
Origin ::= ORIGIN-TYPE TLV-LENGTH
nonNegativeInteger
Cost ::= COST-TYPE TLV-LENGTH
nonNegativeInteger
Flags ::= FLAGS-TYPE TLV-LENGTH
nonNegativeInteger
Mask ::= MASK-TYPE TLV-LENGTH
nonNegativeInteger
Strategy ::= STRATEGY-TYPE TLV-LENGTH
Name
ExpirationPeriod ::= EXPIRATION-PERIOD-TYPE TLV-LENGTH
nonNegativeInteger
; FacePersistency is defined in FaceMgmt section
This definition exhausts all possible fields used in existing commands.
Each individual command MUST specify:
* a list of required fields: those fields MUST be present
* a list of optional fields: those fields MAY be present
* the semantics of each required and optional field
A field that is neither required nor optional for a command MUST NOT be present in a ControlParameter given to that command.
Each individual command MAY impose additional constraints on certain fields.
## Response format
A response from the command interface is a Data that matches the request Interest.
The payload of this Data is a ControlResponse block.
ControlResponse ::= CONTROL-RESPONSE-TYPE TLV-LENGTH
StatusCode
StatusText
<body>
StatusCode ::= STATUS-CODE-TYPE TLV-LENGTH
nonNegativeInteger
StatusText ::= STATUS-TEXT-TYPE TLV-LENGTH
string in UTF-8
<body> ::= zero or more arbitrary TLV blocks
### StatusCode
StatusCode loosely follows the HTTP semantics described in [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6).
* Codes between 100 and 399 represent a success.
* Codes between 400 and 499 represent a client error.
* Codes between 500 and 599 represent a server error.
Common codes include:
StatusCode | Description
-----------|------------------------
200 | OK
400 | ControlParameters is incorrect
403 | Command Interest is not authorized
404 | Resource (e.g., face, prefix, ...) not found
501 | Module or verb is not supported
503 | Service not available
Each individual command MAY define additional codes.
### \<body>
Additional elements are allowed at the end of ControlResponse.
Each individual command MAY define the type and meaning of \<body>.
Unless otherwise defined by an individual command,
\<body> is the ControlParameters passed into this command for all successful responses,
and \<body> is empty for all failure responses.
## TLV-TYPE assignments
Type | Assigned value | Assigned value (hex)
------------------------------------------- | ----------------- | --------------------
ControlParameters | 104 | 0x68
FaceId | 105 | 0x69
Uri | 114 | 0x72
Origin | 111 | 0x6f
Cost | 106 | 0x6a
Flags | 108 | 0x6c
Mask | 112 | 0x70
Strategy | 107 | 0x6b
ExpirationPeriod | 109 | 0x6d
ControlResponse | 101 | 0x65
StatusCode | 102 | 0x66
StatusText | 103 | 0x67
(reserved, formerly LocalControlFeature) | 110 | 0x6e