Project

General

Profile

ControlCommand » History » Revision 30

Revision 29 (Davide Pesavento, 02/13/2017 11:59 AM) → Revision 30/53 (Alex Afanasyev, 03/27/2017 04:34 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 
                               Uri 
    
     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 
 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