Project

General

Profile

ControlCommand » History » Revision 47

Revision 46 (Eric Newberry, 05/23/2018 11:37 AM) → Revision 47/53 (Ju Pan, 06/03/2019 12:57 PM)

# Control Command 

 {{>toc}} 

 **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 element wrapped in a NameComponent. 
 * *command-interest-components* are four additional components defined by [[ndn-cxx:CommandInterest|Command Interest]] spec. 

 ### ControlParameters 

 ControlParameters element contains arguments to the command. 

     ControlParameters                 ::= CONTROL-PARAMETERS-TYPE TLV-LENGTH 
                                           Name? 
                                           FaceId? 
                                           Uri? 
                                           LocalUri? 
                                           Origin? 
                                           Cost? 
                                           Capacity? 
                                           Count? 
                                           BaseCongestionMarkingInterval? 
                                           DefaultCongestionThreshold? 
                                           Mtu? 
                                           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 

     Count                             ::= COUNT-TYPE TLV-LENGTH  
                                           nonNegativeInteger 

     BaseCongestionMarkingInterval     ::= BASE-CONGESTION-MARKING-INTERVAL-TYPE TLV-LENGTH 
                                           nonNegativeInteger 

     DefaultCongestionThreshold        ::= DEFAULT-CONGESTION-THRESHOLD-TYPE TLV-LENGTH 
                                           nonNegativeInteger 

     Mtu                               ::= MTU-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 element. 

     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 elements 

 ### 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 
 Capacity        	       	       	       	     | 131       	       	 | 0x83 
 Count   	       	       	       	             | 132                 | 0x84 
 BaseCongestionMarkingInterval                 | 135                 | 0x87 
 DefaultCongestionThreshold      	             | 136                 | 0x88 
 Mtu                                           | 137                 | 0x89 
 Flags                                         | 108                 | 0x6c 
 Mask                                          | 112                 | 0x70 
 Strategy                                      | 107                 | 0x6b 
 ExpirationPeriod                              | 109                 | 0x6d 
 ControlResponse                               | 101                 | 0x65 
 StatusCode                                    | 102                 | 0x66 
 StatusText                                    | 103                 | 0x67 
 EndpointId                             | 113                 | 0x71 
 (reserved, formerly LocalControlFeature)      | 110                 | 0x6e