ControlCommand » History » Revision 13
Revision 12 (Alex Afanasyev, 02/15/2014 09:09 PM) → Revision 13/53 (Junxiao Shi, 03/18/2014 12:03 AM)
# NFD Control Command specification **Control Command** is NFD management module exposes a mechanism of [[Management|NFD Management protocol]]. command interface as Interest-Data exchange. This document defines Commands provided over this interface are useful for querying or changing the request and response format state of commands that can alter forwarder state, and how these commands should be signed and authenticated. NFD forwarder. When specified, control command takes form of a [[Command Interests|Signed Command Interest]]. This mechanism is useful for altering forwarder state. ## Request format Control commands are signed [[Command Interests]] A request to the command interface is an Interest under `ndn:/localhost/nfd` ``ndn:/localhost/nfd/<management-module>/<command-verb>/...`` prefix. /localhost/nfd/<management-module>/<command-verb>/................./............................... \ / \ / ------ ------ -------------- -------------- \/ \/ ControlParameters Control Command options Command Interest security (optional) info (optional) A request Interest has 9 at least five Name components. These The first five 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 [[Command Interests]] 7. random-value of [[Command Interests]] 8. SignatureInfo of [[Command Interests]] 9. SignatureValue of [[Command Interests]] the arguments to the command, defined for each management module in separate specifications: - [[FibMgmt|FIB Management specification]] - [[FaceMgmt|Face Management specification]] ### ControlParameters Signed request and Unsigned request ControlParameters block contains arguments Most commands require a signature to be included in the command. ControlParameters ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH Name? FaceId? Uri? ControlModule? Cost? Strategy? // Name Name. The signature format is defined in NDN-TLV spec FaceId ::= FACEID-TYPE TLV-LENGTH nonNegativeInteger Uri ::= URI-TYPE TLV-LENGTH RFC3986 URI in UTF-8 encoding ControlModule ::= CONTROL-MODULE-TYPE TLV-LENGTH nonNegativeInteger Cost ::= COST-TYPE TLV-LENGTH nonNegativeInteger Strategy ::= STRATEGY-TYPE TLV-LENGTH [[Signed Interests]] spec. A signed request Interest has eight Name components. This definition exhausts all possible fields used in existing commands. Certain commands that do not change the forwarder state do not require a signature. An unsigned request Interest has five Name components. Each individual command MUST specify: * specification defines whether a list of required fields: those fields MUST request Interest using that command verb should be present * signed or not. ### Options The *option* component contains arguments to the command as a list of optional fields: those fields MAY be present * the semantics of each required and optional fields TLV. A field that This component is neither required nor optional for a even if the command MUST NOT be present in a ControlParameter given to verb does not need any arguments. In that command. case, this component would have zero length. Each individual command MAY impose additional constraints specification defines the format of the options TLV. The TLV-TYPE numbers used in this TLV should be allocated from application range, and are not required to certain fields. be unique across different command verbs. ## Response format A response from the command interface is a Data that matches the request Interest. The payload of in this Data is should be a ControlResponse block. ControlCommandResponse element. ControlResponse ::= CONTROL-RESPONSE-TYPE TLV-LENGTH StatusCode StatusText <body>? <StatusBody>? StatusCode ::= STATUS-CODE-TYPE TLV-LENGTH nonNegativeInteger StatusText ::= STATUS-TEXT-TYPE STATUS-TEXT TLV-LENGTH string in UTF-8 <body> <StatusBody> ::= zero or more arbitary TLV <TLV block defined by the specific control protocol> ### StatusCode StatusCode **StatusCode** generally follows HTTP convention. Codes between 100 and 399 are considered successful; all other codes are considered failure. Common codes include: StatusCode | Description -----------|------------------------ 200 | OK 400 | Arguments are incorrect 401 | Signed request is required for command, but unsigned request is passed 403 | Signing key is not authorized for this command 404 | Resource (e.g. face, prefix, ...) not found 501 | Command verb is not supported Each individual command MAY define additional codes. ### \<body> Additional elements are allowed at the end of ControlResponse. Unless defined by an individual command, \<body> is the ControlParameters passed into this command. **ControlResponse**. Each individual command MAY define the type specification defines whether and meaning of \<body>. what can present. ## TLV-TYPE assignments (Types are assigned from the range reserved for forwarding daemon.) Type | Assigned value | Assigned value (hex) ------------------------------------------- | ----------------- | -------------------- ControlParameters | 104 | 0x68 FaceId | 105 | 0x69 Uri | 114 | 0x72 ControlModule | 110 | 0x6e Cost | 106 | 0x6a Strategy | 107 | 0x6b ControlResponse | 101 | 0x65 StatusCode | 102 | 0x66 StatusText | 103 | 0x67 These types are assigned from the range reserved for forwarding daemon.