Project

General

Profile

Actions
History

Management »

ControlCommand » History » Revision 21

« Previous | Revision 21/53 (diff) | Next »
Alex Afanasyev, 07/23/2014 04:15 PM

Control Command

Control Command is a mechanism of NFD Management protocol.
This document defines the request and response format of commands that can alter forwarder state, and how these commands should be signed and authenticated.
This mechanism is useful for altering forwarder state.

Request format

Control commands are Signed Interests under ndn:/localhost/nfd prefix.

/localhost/nfd/<management-module>/<command-verb>/................./.........................................
                                                  \______  _______/ \__________________  ___________________/
                                                         \/                            \/
                                                  ControlParameters   Signed Interest additional components

A request Interest has 9 Name components.
These components are:

  1. "localhost" in UTF-8
  2. "nfd" in UTF-8
  3. management-module in UTF-8, management module to which the command needs to be dispatched
  4. command-verb in UTF-8, command to be executed
  5. ..., a ControlParameters TLV block
  6. timestamp of Signed Interest
  7. nonce of Signed Interest
  8. SignatureInfo of Signed Interest
  9. SignatureValue of Signed Interest

ControlParameters

ControlParameters block contains arguments to the command.

ControlParameters   ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH
                          Name?
                          FaceId?
                          Uri?
                          LocalControlFeature?
                          Origin?
                          Cost?
                          Flags?
                          Strategy?
                          ExpirationPeriod?

// Name is defined in NDN-TLV spec

FaceId              ::= FACE-ID-TYPE TLV-LENGTH
                          nonNegativeInteger

Uri                 ::= URI-TYPE TLV-LENGTH
                          RFC3986 URI in UTF-8 encoding

LocalControlFeature ::= LOCAL-CONTROL-FEATURE-TYPE TLV-LENGTH
                          nonNegativeInteger

Origin              ::= ORIGIN-TYPE TLV-LENGTH
                          nonNegativeInteger

Cost                ::= COST-TYPE TLV-LENGTH
                          nonNegativeInteger

Flags               ::= FLAGS-TYPE TLV-LENGTH 
                          nonNegativeInteger

Strategy            ::= STRATEGY-TYPE TLV-LENGTH
                          Name

ExpirationPeriod    ::= EXPIRATION-PERIOD-TYPE TLV-LENGTH
                          nonNegativeInteger

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 fields

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 generally follows HTTP convention RFC2616.

  • Codes between 100 and 399 represents a success.
  • Codes between 400 and 499 represents a client error.
  • Codes between 500 and 599 represents 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
LocalControlFeature 110 0x6e
Origin 111 0x6f
Cost 106 0x6a
Flags 108 0x6c
Strategy 107 0x6b
ExpirationPeriod 109 0x6d
ControlResponse 101 0x65
StatusCode 102 0x66
StatusText 103 0x67

These types are assigned from the range reserved for forwarding daemon.

Updated by Alex Afanasyev over 10 years ago · 52 revisions