ControlCommand » History » Revision 33
Revision 28 (Davide Pesavento, 02/13/2017 11:57 AM) → Revision 33/53 (Alex Afanasyev, 03/27/2017 04:42 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 RFC3986 URI in UTF-8 encoding 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 LocalUri | 129 | 0x81 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