Zero Touch Provisioning of Cohda Wireless devices

Owned by Colin Ryan
Last updated: Mar 20, 2015
3 min read

RuBAN supports provisioning of Cohda devices through a package called WaveMgr. The WaveMgr package installs a small agent called the ZTP_executor.sh which periodically calls home to the RuBAN server for any provisioning job to perform. If a provisioning job has been configured for a device the ZTP_executor will download and execute the job, the job comes in the form of a bash script which the user writes when creating the job. On completing the job the ZTP_executor uploads a report indicating success or failure. When RuBAN receives a successful job report it will add the device to the system and it can be viewed in reports and generally managed by RuBAN.

Installing the ZTP Agent

To install the ZTP agent copy the WaveMgr-x.y.z.tar.gz to the Cohda device

  • extract the file: tar zxf WaveMgr-x.y.z.tar.gz -C /opt
  • execute the install script: sh /opt/wavemgr/install.sh

Configuring the ZTP_executor

The ZTP_executor is configured with two parameters: ruban_ip and ruban_port. These can be configured on the Cohda devices command line as follows:

  • fw_setenv ruban_ip "insert.ruban.ip.here"
  • fw_setenv ruban_port "58000"

The ZTP_executor lifecycle

The ZTP_executor follows a simple lifecycle: 

  1. It downloads a job
  2. Invokes the job script with "init" as first argument
    1. returning 1 from the script will stop the ZTP process and report a failure to RuBAN
  3. Invokes the job script with "precheck" as first argument
    1. returning 1 from the script will stop the ZTP process and report a failure to RuBAN
  4. Invokes the job script with "config" as first argument
    1. If the script returns 2 then it signals to the executor that a reboot is required.
      1. On reboot the ztp executor will invoke the job with "post_reboot_config" and move on to step 5
    2. returning 1 from the script will stop the ZTP process and report a failure to RuBAN
  5. Invokes the job script with "verify" as first argument
    1. If the job  script returns 1 then verification has failed but no rollback will be performed by the ztp_executor
    2. If the job script returns 2 then verification has failed and a rollback will be started
      1. the job script is called with "rollback" as the first argument
        1. if the script returns 1 then rollback has failed
        2. if the script returns 2 then the ZTP_executor will issue a reboot of the system after completing the job

In all cases if the script returns 0 for any call it is regarded as a successful call and the ZTP executor will proceed to the next step in the process.

Writing the ZTP job

A ztp job is a bash script which is called by the ZTP_executor. The easiest way to get started with writing one of these scripts is to use the ZTP_config_skel.sh. The skeleton script is a template script, it reads the first argument passed to the script and invokes one of init(), precheck(), configure(), post_reboot_config(),verify(),rollback() depending on the first argument value. So to create your own script just copy this script and fill in the commands you want to execute in the appropriate functions and the template will take care of the sequencing and lifecycle.

Special meaning is attributed to any token that looks like: <my_variable> this is a substitution placeholder. When you create the ztp job you create a csv file, one row for each device you wish to provision. If there is a value in the script that you would like to set differently for each device when the script is run then this mechanism facilitates that. When writing your script define a bash variable:

MY_VAR=<MY_VAR>

Later when defining your ZTP job add a column in your csv file with heading "MY_VAR" and set the value for your devices in each row.

Creating the ZTP job

To define a ZTP job go to Admin->ZTP and click "Create Profile"

  • enter a name for the policy
  • enter a provisioning message (this is a message the ZTP_executor includes in a request to RuBAN to identify the job it's going to run)
  • Upload the gateway list - this is a csv file. Details of the csv file follow below, this file must include the unique serial numbers of the Cohda devices you wish to run this policy on as well as any parameter you wish to pass on to the ztp job script
  • Upload Configuration - upload your ztp job script. You will be presented with a file browser, you must reset the file filter to look for "all files" by default it's set to filter only tcl files. Navigate your file system to locate your script and click open
  • Click "Create Profile"

 ZTP C.S.V file

The ztp file is a simple csv file, the only constraint is that the first column of each row must identify the unique serial number of the cohda device, all subsequent values are regarded as values to be substituted into the ztp bash script as described earlier.