Control Command¶

Control Command is a mechanism of 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 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 Command Interest spec.

ControlParameters¶

ControlParameters block contains arguments to the command.

ControlParameters   ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH
                          Name?
                          FaceId?
                          Uri?
                          LocalUri?
                          Origin?
                          Cost?
                          Capacity?
                          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
                          RFC3986 URI in UTF-8 encoding

Origin              ::= ORIGIN-TYPE TLV-LENGTH
                          nonNegativeInteger

Cost                ::= COST-TYPE TLV-LENGTH
                          nonNegativeInteger

Capacity            ::= CAPACITY-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.

Flags and Mask¶

Various commands collect multiple boolean attributes into the Flags field as an inclusive OR.
Each individual command that uses the Flags field MUST define the meaning of each bit. In the definition, "bit 0" refers to the least significant bit.

The Mask field, if accepted by a command, indicates which attributes are being updated.
In such cases, Flags field and Mask field must be both present or both omitted in the request.
Bits in the Mask field are arranged in the same order as the Flags field.
For example, if a command defines two flags at bit 0 and bit 1 and also accepts a Mask field, a request containing "Flags=0x02 Mask=0x02" specifies bit 1 as "true" and specifies bit 0 as "don't care, leave at default, or keep unchanged"; this request is equivalent to a request containing "Flags=0x03 Mask=0x02".

If a command does not accept the Mask field, it SHOULD interpret every bit in Flags, and there is no "don't care" bits.

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.

• 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
LocalUri	129	0x81
Origin	111	0x6f
Cost	106	0x6a
Capacity	131	0x83
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