== The OpenClovis Managment Command Line Interface ==

=== Overview ===
OpenClovis provides a powerful graphical Command Line Interface (CLI) and Text Command Line interface application that allows users to easily access information presented by network elements via the NETCONF protocol but in this first version, we only provide the latter.

To get started with the supported commands, you must be familiar with Netconf specification (https://tools.ietf.org/html/rfc6241) and Netconf notification (https://tools.ietf.org/html/rfc5277). These specifications define concepts as well as message structure in xml you must know in order to communicate with netconf server via commands such as get-config, edit-config, create-subscription...

First, you need to run ./safplus_cli

To get the command list, type help.

The first step you must to do is to connect to the mgt server by connect command below: 
{{{#!highlight bash
connect <name> <username> <password> <host>
}}}
name : connection name (any name you like)

username: username that needs to authenticate with the machine on which the mgt server is running. Note that, to be able to run some netconf commands that changing the data e.g. edit-config, lock, ... the username must be the one defined in netconfd.conf located in mgt server

password: password that needs to authenticate with the machine on which the mgt server is running.

host: the ipaddress on which the mgt server is running


To run an rpc command, type: <command> [<name=value> <name=value> ...]

<command>: rpc command supported by OpenYuma such as get-config, edit-config... and your own commands defined in your app.

<name=value>: arguments for the command in pair separated by '=' and each pair is separated by space if the command has several arguments. Each name in each pair will be translated as an xml tag and value will be the text value for the tag. For example, get-config source=running will be translated as <get-config><source>running</source></get-config> . But according to the Netconf specification, the get-config xml message must be: <get-config><source><running/></source></get-config>. To achieve this, you must type: get-config source=<running/>

If the tag doesn't include any attribute, like <source><running/></source>, you can type get-config source=<running/>. But if a tag contains attribute like

{{{#!highlight xml
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <myService>
             <config>
               <homeLocation/>
             </config>
           </myService>
         </filter>
       </get-config>
}}}

you must type: get-config source=<running/> 'filter type="subtree"'=<myService><config><homeLocation/></config></myService>

If <filter> doesn't contain any attribute (for example), type: get-config source=<running/> filter=<myService><config><homeLocation/></config></myService>. Xml generated:
{{{#!highlight xml
        <get-config>
          <source>
            <running/>
          </source>
          <filter>
            <myService>
              <config>
                <homeLocation/>
              </config>
            </myService>
          </filter>
        </get-config>
}}}


In general, if an argument contains space, it must be covered with single quotes. For example:


{{{#!highlight bash
edit-config target=<running/> 'tag attr1="blah" attr2="blah blah"'='<othertag attr="blah blah blah" attr2="blah blah"/>'
}}}

The xml generated:

{{{#!highlight xml
        <edit-config>
          <target>
            <running/>
          </target>
          <tag attr1="blah" attr2="blah blah">
            <othertag attr="blah blah blah" attr2="blah blah"/>           
          </tag>
        </edit-config>
}}}

Beside netconf standard protocol operations fully supported in safplus_cli, there are some openclovis command such as ls, cd, setdatabase, set, getconfig... They are to simplify some netconf standard protocol operations

1.cd : set the new current xpath (similar to linux "cd" command) located in the running database

syntax: cd <xpath>

For example, /test> cd myService/config

The result of the above statement is: /test/myService/config>

2. ls: display the xpath structure of the running database for the passed argument xpath, if xpath is omitted, the command display the structure of current xpath

Systax: ls [<xpath>]

For example, /test/myService/config>ls port

The result of the above statement is: port:8000

             /test/myService/config>ls

The result of the above statement is: 

homeLocation:/srv/web

port:8000


3. setdatabase: set the operational database that will be applied for set and getconfig commands

Syntax: setdatabase <databasename>

For example, setdatabase running

             setdatabase candidate

4. getdatabase: get the database that was set by setdatabase commands. Note: the default database is candidate

Syntax: getdatabase


5. set: assign a new value for a leaf located in the running database

syntax: set leaf value

For example, /test/myService/config>set port 3000
             
             /test/>set myService/config/port 3000
              

6. getconfig: get the configuration values for an xpath located in the database set by previous setdatabase command, if xpath is omitted, the command get the configuration values for the current xpath

syntax: getconfig [<xpath>]

For example, /test>getconfig myService/config


The result of the above statement is: 

config:
        
homeLocation:/srv/web

port:8000

7. create: operate like operation "create" of edit-config: create a new xpath or a leaf with value, usually element of a list with key value and other fields of the list (other fields of the list can be also created by set command). The applicable database is the one set by setdatabase command. Note that if you want to create a new leaf (not a list element), use set command

syntax: create xpath_with_key

For example: create a new element of list with key name "host1":

  create test/myService/lists/server[name=host1]

Create a new container "config" under "myService" with its default leaf's values:

  create test/myService/config

create a leaf with value:

  create a/myService/config/port1=111

Create an element of list with a key and other fields:
 
  create a/myService/lists/server[name=host3][port=222][ip=1.1.1.1]


8. delete: operate like operation "delete" of edit-config: delete an xpath  , usually a new element of a list with key value. The applicable database is the one set by setdatabase command

syntax: delete xpath[wih_key]

For example: delete test/myService/lists/server[name=host1]

This will delete an element of list with key name "host1"

delete test/myService/config/port

This will delete "port" as a leaf contained in config container

9. Merge: operate like operation "merge" of edit-config

syntax: merge xpath_with_values

Example: set new value of port for list with the key "host3":

  merge a/myService/lists/server[name=host3][port=222]

10. Replace: operate like operation "replace" of edit-config

syntax: replace xpath_with_values

Example: replace new value of ip for list with the key "host3" and delete all remaining values of other fields of the list:

  replace a/myService/lists/server[name=host3][ip=1.1.1.1]