CLI Tutorial

Introduction

With the exscript command line tool, you can quickly automate a conversation with a device over Telnet or SSH.

This is a step by step introduction to using the Exscript command line tool.

We’ll assume that Exscript is already installed. You can confirm that your installation works by typing exscript --version into a terminal; if this prints the version number, your installation is complete.

Getting started

As a first simple test, let’s try to connect to a Linux/Unix machine via SSH2, and execute the uname -a command on it.

Create a file named test.exscript with the following content:

uname -a

To run this Exscript template, just start Exscript using the following command:

exscript test.exscript ssh://localhost

Awesome fact: Just replace ssh:// by telnet:// and it should still work with Telnet devices.

Hint

The example assumes that localhost is a Unix server where SSH is running. You may of course change this to either an ip address (such as ssh://192.168.0.1), or any other hostname.

Exscript will prompt you for a username and a password, and connect to localhost using the entered login details. Once logged in, it executes uname -a, waits for a prompt, and closes the connection.

Running a script on multiple hosts

In practice, you may want to run this script on multiple hosts, and optimally at the same time, in parallel. Using the -c option, you tell Exscript to open multiple connections at the same time:

exscript -c 2 test.exscript ssh://localhost ssh://otherhost

-c 2 tells Exscript to open two connections in parallel. So if you run this script, Exscript will again ask for the login details, and run uname -a for both hosts in parallel.

Note that the login details are only asked once and used on both hosts - this may or may not be what you want. The following section explains some of the details of using different login accounts.

Reading login information

Depending on how you would like to provide the login information, there are a few options. The first is by including it in the hostname:

exscript -c 2 test.exscript ssh://localhost
ssh://user:password@otherhost

In this case, Exscript still prompts the user for his login details, but the entered information is only used on hosts that do not have a user/password combination included in the hostname.

If you do not want for Exscript to prompt for login details, the -i switch tells Exscript to not ask for a user and password. You need to make sure that all hosts have a user and password in the hostname if you use it.

Reading host names from a text file

If you do not wish to hard code the host names or login details into the command, you may also list the hosts in an external file and load it using the --hosts option as follows:

exscript -c 2 —hosts myhosts.txt test.exscript

Note that hosts.txt is a file containing a list of hostnames, e.g.:

host1
host2
...
host20

Reading host names from a CSV file

Similar to the --hosts, you may also use --csv-hosts option to pass a list of hosts to Exscript while at the same time providing a number of variables to the script. The CSV file has the following format:

address my_variable another_variable
telnet://myhost value another_value
ssh://yourhost hello world

Note that fields are separated using the tab character, and the first line must start with the string “address” and is followed by a list of column names.

In the Exscript template, you may then access the variables using those column names:

ls -l $my_variable
touch $another_variable

Using Account Pooling

You can also pass in a pre-loaded list of accounts from a separate file. The accounts from the file are used for hosts that do not have a user/password combination specified in their URL.

exscript -c 2 —hosts myhosts.txt —account-pool accounts.cfg test.exscript

Note that accounts.cfg is a config file with a defined syntax as seen in the API documentation for Exscript.util.file.get_accounts_from_file().

It is assumed that you are aware of the security implications of saving login passwords in a text file.

Logging

Exscript has built-in support for logging - just pass the --logdir or -l option with a path to the directory in which logs are stored:

exscript -l /tmp/logs -c 2 —hosts myhosts.txt —account-pool accounts.cfg test.exscript

Exscript creates one logfile per device. In the case that an error happened on the remote device, it creates an additional file that contains the error (including Python’s traceback).

Interacting with a device

So far we only fired and forgot a command on a device, there was no true interaction. But Exscript does a lot to make interaction with a device easier. The first notable tool is the extract keyword. Let’s look at an example:

uname -a{extract /^(\S+)\s+(\S+)/ as os, hostname}

The Exscript Template Language

The Exscript template language is in some ways comparable to Expect, but has unique features that make it a lot easier to use and understand for non-developers.

A first example:

{fail "not a Cisco router" if connection.guess_os() is not "ios"}

show ip interface brief {extract /^(\S+)\s/ as interfaces}
configure terminal
{loop interfaces as interface}
    interface $interface
    description This is an automatically configured interface description!
    cdp enable
    no shut
    exit
{end}
copy running-config startup-config

Exscript templates support many more commands. Here is another example, to automate a session with a Cisco router:

show version {extract /^(cisco)/ as vendor}
{if vendor is "cisco"}
  show ip interface brief {extract /^(\S+)\s/ as interfaces}
  {loop interfaces as interface}
    show running interface $interface
    configure terminal
    interface $interface
    no shut
    end
  {end}
  copy running-config startup-config
{end}

Advanced Templates

Exscript templates support many more commands. For a full overview over the template language, please check Exscript Templates.