Project

General

Profile

ControlCommand » History » Revision 22

Revision 21 (Alex Afanasyev, 07/23/2014 04:15 PM) → Revision 22/53 (Junxiao Shi, 10/12/2014 01:03 PM)

# Control Command 

 **Control Command** is a mechanism of [[Management|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 [[ndn-cxx:SignedInterest|Signed Interests]] under a NFD management namespace. `ndn:/localhost/nfd` prefix. 

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

 The Name for a A request Interest has the following form: 

     /<namespace>/<management-module>/<command-verb>/<control-parameters>/<signed-interest-components> 9 Name components. 
 These components are: 

 * *namespace* is a NFD management namespace. 
   Unless otherwise noted, all commands use `/localhost/nfd` namespace. 
   Each individual command MAY specify additional namespaces under which that command could be accepted. 1. "localhost" in UTF-8 
 * 2. "nfd" in UTF-8 
 3. *management-module* is the name of in UTF-8, management module to which the command needs to be dispatched. dispatched 
 * 4. *command-verb* is the in UTF-8, command to be executed. executed 
 * *control-parameters* is 5. *...*, a ControlParameters TLV block wrapped in a NameComponent. 
 * *signed-interest-components* are four additional components defined by [ndn-cxx:SignedInterest|Signed Interest] spec 6. timestamp of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest) 
 7. nonce of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest) 
 8. SignatureInfo of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest) 
 9. SignatureValue of [Signed Interest](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest) 

 ### 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](http://tools.ietf.org/html/rfc2616#section-10)\]. 

 * 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.