[precheck] Section

If you include a precheck section at the top of the config file this will run some tests before continuing to do the ZTP.

For example you may not want to perform the config until certain connectivity is in place or you may not want to run a configuration if you detect it is not necessary.

This section is similar to the [verify] section described later only the checks are for a different purpose, where the [verify] section check run after a config to determine that everything run as expected,

the precheck section determines whether the config should be run at all. Two types of checks are currently possible. One is to ping an IP address and the second is to run a command on the CLI and inspect the response.

There are two possible actions to take on seeing a precheck fail. One is for the ZTP to sleep for a few minutes and try again later. The second action is for ZTP to report to the RuBAN server that this profile does not need to be run on this device so it will not be tried again.

Example 1 Run a CLI command:

CMD~sh ver | incl System image file~exclude~c800-universalk9-mz.SPA.153-3.M2.bin~EXIT_SUCCESS

The delimeter in this line is the ~ character so the following specifies what each segment of the above example means:

CMD :

This simply means that the action to take is to run a CLI command.

sh ver | incl System image file :

This is the command we are going to run, this can be any CLI command that you can run on the console.

exclude:

This indicates that we are going to check to ensure that the response of the above command excludes a particular string. The other option for this segment is "include" if you wished to verify that the output included a particular string.

c800-universalk9-mz.SPA.153-3.M2.bin:

This is the string we are to match against the output of the command that was run. In the example above we are running a check to ensure that it is excluded from the output. Or in more simple terms if you look a the command you will see that what this achieves it to ensure that the current Ios version is not the one specified here.

EXIT_SUCCESS:

This indicates the action to take based on a fail in the precheck. If the precheck passes then the ZTP will continue as normal but if it fails it must take one of two actions. EXIT_SUCCESS will send a message to RuBAN to say that this profile is not necessary for this device and therefore this device will not try to run this ZTP profile again. The other option "EXIT" simply exits out of ZTP but does not report anything up to RuBAN. The result of this is that when the ZTP process next runs it will try the same profile again.

So to recap the example above would be useful where you wish to upgrade the Ios version on your deployment of devices but you don't want it to run if the device is already on that version of Ios. This could also be adapted to for example not run the ZTP until IP connectivity to a certain server has come up and keep retrying until then. 

[config] Section

Each line in the config section represents a line of config to be applied to the device.

They should be inputted in the order they would be run if they were to be run manually on the device.

Parameters that are to be substituted in from the CSV file are contained within < and > brackets.

For example a if there is a variable <ifname> in the config file and within the CSV file for the row matching that device's serial the parameter in the ifname column is "FastEthernet0"

Then the command "interface <ifname>" will be executed as "interface FastEthernet0"

This allows different variables based on different serial numbers.

Config Dialogue command

Some configuration commands trigger a dialogue on the CLI when they are executed.

Examples are commands that need a confirmation before they run. The config file to be uploaded to RuBAN can handle such dialogues but they have a special format as outlined below.

Here is an example dialogue command as it would appear in the config file:

do copy scp: flash:~Address or name of remote host~192.168.180.158~Source username~root~Source filename~c800-universalk9-mz.SPA.153-3.M2.bin~Password:~CISCOTEST

There ~ (tilda) delimiter is used to separate different parts of the command.

The first part (in example above "do copy scp: flash:") is the command you initially run to kick off the dialogue. What follows after is the prompts on the command line followed by the next command we send.

Looking at the example again when we type do copy scp: flash:

1. We get a prompt on the CLI which contains the text  : Address or name of remote host
2. We then send down : 192.168.180.158
3. We then get a prompt containing the text "Source username"
4. We then send down : root
5. We then get a prompt containing the text "Source filename"
6. We then send down : c800-universalk9-mz.SPA.153-3.M2.bin
7. We then get a prompt containing the text "Password:"
8. We then send down : CISCOTEST

So when dealing with an operation that requires a dialogue to complete it must be structured as above for it to work.

[post-reboot] Section

The existence of this flag indicates that a reboot is needed to complete the provisioning. Many ZTP actions require a reboot to complete.

For example upgrading the Ios or copying a new running config into the startup config. This flag allows the ZTP process to pause save its status and it will resume after the device has come back up from where it left off.

[verify] Section

The verify section is where you perform config verification commands. they must be copied into the config file underneath the [verify] tag which comes after the configuration section.

For example after running a configuration it may be prudent to check that the configuration has set properly by running some show commands and parsing through the output.

It may also be necessary to try and contact an IP address to ensure that the connectivity that was expected is there. The verify commands have a roll back action. There are two options, one is "REPORT" which just reports that the verification failed.

The other option is "ROLLBACK" which indicates that a rollback is necessary, this will execute any commands contained within the [rollback] section.

Show command output

After the config has been run you can run any command you wish on the CLI and parse the output to verify that a certain pattern is or is not contained in the output.

The format of this statement is as follows: 

CMD~sh int <ifname>~include~Description: ZTP changed this!~REPORT

Assuming <ifname> is substituted by "FastEthernet0" The above statement will run the command "sh int FastEthernet0"

The output will then be parsed to verify that it includes the text "Description: ZTP changed this!".

If it does then this verification check will pass. You may also verify that the output does not contain text by substituting "include" with "exclude"

E.G: CMD~sh int <ifname>~exclude~Description: ZTP changed this!

IP connectivity

Another common check when applying a change to a config is to ensure the IP connectivity is as is expected.

In other words that you can ping IP addresses that you expected you would be able to and also that you shouldn't be able to ping certain IP's.

An example statement is as follows:

PING~10.1.1.1~up

PING~10.2.2.2~down

PING~<ip_sub>~down

In this case checks will be made to ensure the device can ping IP 10.1.1.1 and that it cannot reach IP 10.2.2.2

IP addresses in the verify section can also be substituted from values in the CSV file

So if the value in the CSV for ip_sub is for example 10.3.3.3 then the verification check will ensure that IP cannot be reached.

[rollback] Section

This section just contains a number of configuration commands to be executed sequentially much like the commands in the [config] section.

E.G 

no boot system flash <new_image>
boot system flash <old_image>

This would undo setting of the boot image.

Example contents

Below is an example of the full contents of a config file. You would save these contents into a .txt file which you would upload  through the RuBAN web user interface while creating a ZTP profile.

[config]
int <ifname>
desc ZTP changed this!!!!
exit
username <username> privilege 15 password <password>
no ev m applet ZTP_BOOTSTRAP

[verify]
CMD~sh int <ifname>~include~Description: ZTP changed this!!!!
CMD~sh run~include~username <username>
CMD~sh ev m p r~exclude~ZTP_BOOTSTRAP