Exscript Release v2.

0 User Documentation
A scripting language and framework for terminal based protocols

Samuel Abels March 4, 2010 Contents

Contents 1 Introduction 1.1 Why Exscript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Legal Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Contact Information & Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Overview 2.1 Quick Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Talking To Multiple Devices At The Same Time . . . . . . . . . . . . . . . . . . . . . 2.3 Advanced Command Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Command Line Syntax 3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Using Account Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Using a CSV le as input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Language Syntax 4.1 Sending Commands To The Remote Host 4.2 Comments . . . . . . . . . . . . . . . . . . 4.3 Using Variables . . . . . . . . . . . . . . . 4.4 Adding Variables To A List . . . . . . . . 4.5 Using Built-in Variables . . . . . . . . . . 4.6 Using Expressions . . . . . . . . . . . . . 4.6.1 Priority 1 Operators . . . . . . . . 4.6.2 Priority 2 Operators . . . . . . . . 4.6.3 Priority 3 Operators . . . . . . . . 4.6.4 Priority 4 Operators . . . . . . . . 1 2 2 2 2 3 3 3 3 4 4 4 5 5 5 5 6 6 7 7 7 7 7 8

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

CONTENTS 4.6.5 4.6.6 Using Using Priority 5 Operators . . . . . . Priority 6 Operators . . . . . . Hexadecimal Or Octal Numbers Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CONTENTS . . . . . . . . . . . . . . . . . . . . 8 8 8 9 9 9 9 10 10 10 10 10 11 11 12 12 13 13 13 13 14 14 14 15 16 16 16 16 17 18 19 20 20 23 23 24 24 26 26 29 29 30 30

4.7 4.8

5 Exscript Commands 5.1 Extracting Data From A Response 5.1.1 extract ... into ... . . . . . . 5.1.2 extract ... into ... from ... . 5.1.3 extract ... as ... . . . . . . . 5.2 Using If-Conditions . . . . . . . . . 5.2.1 if ... end . . . . . . . . . . . 5.2.2 if ... else ... end . . . . . . . 5.2.3 if ... else if ... . . . . . . . . 5.3 Loops . . . . . . . . . . . . . . . . 5.4 Loops And Lists . . . . . . . . . . 5.5 Using Functions . . . . . . . . . . . 5.6 Exiting A Script . . . . . . . . . . 5.6.1 fail message . . . . . . . . 5.6.2 fail message if ... . . . . . 5.7 Error Handling . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

6 Trouble Shooting 6.1 Common Pitfalls . . . . . . . . . . . 6.2 Deadlocks . . . . . . . . . . . . . . . 6.3 A Command Is Sent Too Soon . . . 6.4 The Connection Is Closed Too Soon 7 The Python API 7.1 Overview . . . . . . . . . . . . . . . 7.2 Exscript .protocols . . . . . . . . . . 7.2.1 Emulating A Remote Device 7.3 Exscript .Queue . . . . . . . . . . . . A The Standard Library A.1 Module stdlib.connection A.1.1 Functions . . . . . A.2 Module stdlib.crypt . . . A.2.1 Functions . . . . . A.3 Module stdlib.le . . . . . A.3.1 Functions . . . . . A.4 Module stdlib.ipv4 . . . . A.4.1 Functions . . . . . A.5 Module stdlib.list . . . . . A.5.1 Functions . . . . . A.6 Module stdlib.string . . . A.6.1 Functions . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

Page 2

CONTENTS

CONTENTS 31 31

A.7 Module stdlib.sys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.7.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Page 3

INTRODUCTION

1 Introduction
1.1 Why Exscript?
Exscript is a script and template language for automating network connections over protocols such as Telnet or SSH. Exscript is targeted at non-developers and developers alike. Exscript is often used to automate sessions with routers from Cisco, Juniper, Huawei, and others. It may be used by an administrator who often congures machines running Linux/Unix, IOS, IOS-XR, JunOS, VRP, or any other operating system that can be used with a terminal. Exscript is in some ways comparable to Expect, but has some unique features that make it a lot easier to use and understand for non-developers.

1.2 Legal Information

Exscript and this handbook are distributed under the terms and conditions of the GNU GPL (General Public License) Version 2. You should have received a copy of the GPL along with Exscript . If you did not, you may read it here: http://www.gnu.org/licenses/gpl-2.0.txt If this license does not meet your requirements you may contact us under the points of contact listed in the following section. Please let us know why you need a dierent license - perhaps we may work out a solution that works for either of us.

1.3 Contact Information & Feedback

If you spot any errors, or have ideas for improving Exscript or this documentation, your suggestions are gladly accepted. We oer the following contact options: Google Groups: Phone: Jabber: http://groups.google.com/group/exscript/ +49 176 830 40288 knipknap@jabber.org

Page 4

OVERVIEW

2 Overview
2.1 Quick Introduction
With Exscript you can quickly automate a conversation with a device over Telnet or SSH. For example, to execute the ls command on three dierent hosts, create a le with the following content: ls and then run it using exscript my template host1 host2 host3

2.2 Talking To Multiple Devices At The Same Time

With Exscript you can automatically parallelize your connections, such that multiple sessions are opened at the same time. This can speed up the time in which a specic command is propagated within your network. For example, imagine you want to execute the clear ip bgp * soft command on twenty dierent Cisco routers. Start by creating a text le with the following content: clear ip bgp soft Save this le as commands.exscript. Also, create a text le that contains the list of hostnames to which the command should be sent: host1 host2 ... host20 Save this le as hosts.txt. To send this change to all routers at the same time, type the following command: exscript hosts hosts. txt c15 commands. exscript Note that the -c15 option causes Exscript to open a maximum of fteen connections at the same time. Once the rst host out of these 15 is completed, Exscript opens the connection to the next host, until the clear ip bgp * soft command has been sent to all hosts.

2.3 Advanced Command Templates

Exscript templates support many more commands. For example, to automate a session with a Cisco router, the following template may be used:

Page 5

COMMAND LINE SYNTAX 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 startupconfig {end}

Exscript provides additional methods for interacting with the remote host and for receiving information from it. The following chapters include a more complete overview of the template language.

3 Command Line Syntax

3.1 Overview
You can pass parameters (or lists of parameters) into the templates and use them to drive what happens on the remote host. Exscript easily supports logging, authentication mechanisms such as TACACS and takes care of synchronizing the login procedure between multiple running connections. These features are enabled using simple command line options. The following options are currently provided:

3.2 Using Account Pooling

It is possible to provide an account pool from which Exscript takes a user account whenever it needs to log into a remote host. Depending on the authentication mechanism used in your network, you may signicantly increase the speed of parallel connections by using more than one account in parallel. The following steps need to be taken to use the feature: 1. Create a le with the following format: [account pool] user= password other user=another password somebody =yet another password Note that the password needs to be base64 encrypted, just putting plain passwords there will NOT work.

Page 6

LANGUAGE SYNTAX

3.3

USING A CSV FILE AS INPUT

2. Save the le. It is assumed that you are aware of the security implications of saving your login passwords in a text le. 3. Start Exscript with the account-pool FILE option. For example: exscript account pool /home/user/my accounts my. exscript host4

3.3 Using a CSV le as input

By providing the csv-hosts option you may pass a list of hosts to Exscript while at the same time providing a number of variables to the script. The CSV le should have the following format: hostname my variable another variable myhost value another value yourhost hello world Note that elds are separated using the tab character, and the rst line must start with the string hostname and is followed by a list of column names. In the Exscript, you may then access the variables using those column names: ls l $my variable touch $another variable

4 Language Syntax
4.1 Sending Commands To The Remote Host
The simplest possible template is one that contains only the commands that are sent to the remote host. For example, the following Exscript can be used to retrieve the response of the ls -l and df commands from a unix host: ls l df Save this le as my.exscript and execute it using the following command: exscript my. exscript localhost where localhost is the name of the host on which the ls -l and df commands are executed.

4.2 Comments
Lines starting with a hash (#) are interpreted as comments and ignored. For example:

Page 7

LANGUAGE SYNTAX 1. # This line is ignored . . . 2. {if hostname is test} 3. # . . .and so is this one. 4. {end}

4.3

USING VARIABLES

4.3 Using Variables

The following template uses a variable to execute the ls command with a lename as an argument: ls l $filename Execute: exscript d filename=.profile my. exscript localhost Note that the -d switch allows passing variables into the Exscript . The example executes the command ls -l .prole. You can also assign a value to a variable within an Exscript : {filename = . profile} ls l $filename You may also use variables in strings by prexing them with the $ character: 1. {test = my test} 2. {if my test one is $test one} 3. # This matches! 4. {end} In the above template line 3 is reached. If you dont want the $ character to be interpreted as a variable, you may prex it with a backslash: 1. {test = my test} 2. {if my test one is \$test one} 3. # This does not match 4. {end}

4.4 Adding Variables To A List

In Exscript every variable is a list. You can also merge two lists by using the append keyword: 1. { 2. test1 = one 3. test2 = two 4. append test2 to test1 5. } This results in the test1 variable containing two items, one and two.

Page 8

LANGUAGE SYNTAX

4.5

USING BUILT-IN VARIABLES

4.5 Using Built-in Variables

The following variables are available in any Exscript template, even if they were not explicitly passed in: 1. 2. hostname contains the hostname that was used to open the current connection.

response contains the response of the remote host that was received after the execution of the last command.

Built-in variables are used just like any other variable. You can also assign a new value to a built-in variable in the same way.

4.6 Using Expressions

An expression is a combination of values, variables, operators, and functions that are interpreted (evaluated) according to particular rules and that produce a return value. For example, the following code is an expression: name is samuel and 4 3 is not 11 In this expression, name is a variable, is, is not, and * are operators, and samuel, 4, 3, and 11 are values. The return value of this particular expression is true. In Exscript , expressions are used in many places, such as if-conditions or variable assignments. The following operators may be used in an expression. 4.6.1 Priority 1 Operators 1. * multiplies the operators (numerically). 2. / divides the operators (numerically). 4.6.2 Priority 2 Operators 1. + adds the operators (numerically). 2. - subtracts the operators (numerically). 4.6.3 Priority 3 Operators 1. . concatenates two strings.

Page 9

LANGUAGE SYNTAX

4.7

USING HEXADECIMAL OR OCTAL NUMBERS

4.6.4 Priority 4 Operators 1. is tests for equality. If both operators are lists, only the rst item in the list is compared. 2. is not produces the opposite result from is. 3. in tests whether the left string equals any of the items in the list given as the right operator. 4. not in produces the opposite result from in. 5. matches tests whether the left operator matches the regular expression that is given as the right operator. 6. ge tests whether the left operator is (numerically) greater than or equal to the right operator. 7. gt tests whether the left operator is (numerically) greater than the right operator. 8. le tests whether the left operator is (numerically) less than or equal to the right operator. 9. lt tests whether the left operator is (numerically) less than the right operator. 4.6.5 Priority 5 Operators 1. not inverts the result of a comparison. 4.6.6 Priority 6 Operators 1. and combines two tests such that a logical AND comparison is made. If the left operator returns FALSE, the right operator is not evaluated. 2. or combines two tests such that a logical OR comparison is made. If the left operator returns TRUE, the right operator is not evaluated.

4.7 Using Hexadecimal Or Octal Numbers

Exscript also supports hexadecimal and octal numbers using the following syntax: { if 0x0a is 012 sys .message(Yes) else sys .message(No) end }

Page 10

EXSCRIPT COMMANDS

4.8

USING REGULAR EXPRESSIONS

4.8 Using Regular Expressions

At some places Exscript uses Regular Expressions. These are NOT the same as the expressions documented above, and if you do not know what regular expressions are it is recommended that you read a tutorial on regular expressions rst. Exscript regular expressions are similar to Perl and you may also append regular expression modiers to them. For example, the following is a valid regular expression in Exscript : /cisco \d+\s+\ w/i Where the appended i is a modier (meaning case-insensitive). A full explanation of regular expressions is not given here, because plenty of introductions have been written already and may be found with the internet search engine of your choice.

5 Exscript Commands
By default, any content of an Exscript is sent to the remote host. However, you can also add instructions with special meanings. Such instructions are enclosed by curly brackets ( and ). The following commands all use this syntax.

5.1 Extracting Data From A Response

Exscript lets you parse the response of a remote host using regular expressions. If you do not know what regular expressions are, please read a tutorial on regular expressions rst. 5.1.1 extract ... into ... If you already know what regular expressions are, consider the following template: ls l {extract /(d.)/ into directories} The extract command matches each line of the response of ls -l against the regular expression / (d.*)/ and then appends the result of the rst match group (a match group is a part of a regular expression that is enclosed by brackets) to the list variable named directories. You can also extract the value of multiple match groups using the following syntax: ls l {extract /(d\S+)\s.\s(\S+)$/ into modes, directories} This extracts the mode and the directory name from each line and appends them to the modes and directories lists respectively. You can also apply multiple matches to the same response using the following syntax: ls l { extract /[d].\s(\S+)$/ into files

Page 11

EXSCRIPT COMMANDS extract /d.\s(\S+)$/ } into directories

5.2

USING IF-CONDITIONS

There is no limit to the number of extract statements. 5.1.2 extract ... into ... from ... When used without the from keyword, extract gets the values from the last command that was executed. You may however also instruct Exscript to extract the values from a variable. The following example shows how this may be done. ls l { extract /(.)/ into lines extract /(d.)/ into directories from lines }

5.1.3 extract ... as ... The as keyword is similar to into, the dierence being that with as, the destination variable is cleared before new values are appended. ls l {extract /(d.)/ as directories} as may be used anywhere where into is used.

5.2 Using If-Conditions

You can execute commands depending on the runtime value of a variable or expression. 5.2.1 if ... end The following Exscript executes the ls command only if ls -l .prole did not produce a result: ls l . profile {extract /(\.profile)$/ as found} {if found is not . profile} ls {end}

5.2.2 if ... else ... end You can also add an else condition:

Page 12

EXSCRIPT COMMANDS ls l . profile {extract /(\.profile)$/ as found} {if found is not . profile} ls {else} touch . profile {end}

5.3

LOOPS

5.2.3 if ... else if ... You can perform multiple matches using else if: ls l . profile {extract /(.profile)$/ as found} {if found is . profile} ls {else if found matches /my profile/} ls l p {else} touch . profile {end}

5.3 Loops
You can execute commands multiple times using the loop statement. The following Exscript executes the ls command three times: {number = 0} {loop until number is 3} {number = number + 1} ls $directory {end} Similarly, the while statement may be used. The following script is equivalent: {number = 0} {loop while number is not 3} {number = number + 1} ls $directory {end} Another alternative is using the loop from ... to ... syntax, which allows you to specify a range of integers: # Implicit counter variable . {loop from 1 to 3} ls $directory$counter {end}

Page 13

EXSCRIPT COMMANDS

5.4

LOOPS AND LISTS

# Explicit variable name. {loop from 1 to 3 as number} ls $directory$number {end}

5.4 Loops And Lists

The following Exscript uses the ls command to show the content of a list of subdirectories: ls l {extract /d.\s(\S+)$/ as directories} {loop directories as directory} ls $directory {end} You can also walk through multiple lists at once, as long as they have the same number of items in it: ls l {extract /(d\S+)\s.\s(\S+)$/ as modes, directories} {loop modes, directories as mode, directory} echo Directory has the mode $mode ls $directory {end} List loops can also be combined with the until or while statement seen in the previous section: ls l {extract /d.\s(\S+)$/ as directories} {loop directories as directory until directory is my subdir} ls $directory {end}

5.5 Using Functions

Exscript provides builtin functions with the following syntax: type.function(EXPRESSION [EXPRESSION . . . ] ) , , For example, the following function instructs Exscript to wait for 10 seconds: {sys .wait(10)} For a list of supported functions please refer to appendix A.

Page 14

EXSCRIPT COMMANDS

5.6

EXITING A SCRIPT

5.6 Exiting A Script

5.6.1 fail message The fail keyword may be used where a script should terminate immediately. show something {fail Error: Failed!} show something else In this script, the show something else line is never reached. 5.6.2 fail message if ... It is also possible to fail only if a specic condition is met. The following snippet terminates only if a Cisco router does not have a POS interface: show ip int brie { extract /(POS)\S+/ as pos interfaces fail No POS interface found! if POS not in pos interfaces }

5.7 Error Handling

Exscript attempts to detect errors, such as commands that are not understood by the remote host. By default, Exscript considers any response that includes one of the following strings to be an error: invalid incomplete unrecognized unknown command [\r\n]+ not found If this default conguration does not suit your needs, you can override the default, setting it to any regular expression of your choice using the following function: {connection. set error(/[Ff] ailed/)} Whenever such an error is detected, the currently running Exscript is cancelled on the current host. For example, when the following script is executed on a Cisco router, it will fail because there is no ls command: ls l show ip int brief The show ip int brief command is not executed, because an error is detected at ls -l at runtime.

Page 15

TROUBLE SHOOTING

If you want to execute the command regardless, you can wrap the ls command in a try block: {try}ls l{end} show ip int brief You can add as many commands as you like in between a try block. For example, the following will also work: {try} ls l df show running config {end} show ip int brief

6 Trouble Shooting
6.1 Common Pitfalls
Generally, the following kinds of errors that may happen at runtime: 1. A script deadlocks. In other words, Exscript sends no further commands even though the remote host is already waiting for a command. This generally happens when a prompt is not recognized. 2. A script executes a command before the remote host is ready. This happens when a prompt was detected where none was really included in the response. 3. A script terminates before executing all commands. This happens when two (or more) prompts were detected where only one was expected. The following sections explain when these problems may happen and how to x them.

6.2 Deadlocks
Exscript tries to automatically detect a prompt, so generally you should not have to worry about prompt recognition. The following prompt types are supported: [sam123@home ]$ sam@knip:/Code/exscript$ sam@MyHost X123$ MyHost ABCCDE123$ MyHost A1$ MyHost A1(config)$ FA /0/1/2/3$ FA/0/1/2/3(config)$ admin@s x a6.a.bc.de. fg:/$

Page 16

TROUBLE SHOOTING

6.3

A COMMAND IS SENT TOO SOON

Note: The trailing $ may also be any of the following characters: $#% However, in some rare cases, a remote host may have a prompt that Exscript can not recognize. Similarly, in some scripts you might want to execute a special command that triggers a response that does not include a prompt Exscript can recognize. In both cases, the solution includes dening the prompt manually, such that Exscript knows when the remote host is ready. For example, consider the following script: 1. 2. 3. 4. show ip int brief write memory {enter} show configuration

Say that after executing line 2 of this script, the remote host asks for a conrmation, saying something like this: Are you sure you want to overwrite the configuration? [confirm] Because this answer does not contain a standard prompt, Exscript can not recognize it. We have a deadlock. To x this, we must tell Exscript that a non-standard prompt should be expected. The following change xes the script: 1. 2. 3. 4. 5. 6. show ip int brief {connection.set prompt(/\[confirm\]/)} write memory {connection.set prompt()} {enter} show configuration

The second line tells Exscript to wait for [conrm] after executing the following commands. Because of that, when the write memory command was executed in line 3, the script does not deadlock (because the remote hosts response includes [conrm]). In line 4, the prompt is reset to its original value. This must be done, because otherwise the script would wait for another [conrm] after executing line 5 and line 6.

6.3 A Command Is Sent Too Soon

This happens when a prompt was incorrectly detected in the response of a remote host. For example, consider using the following script: show interface descriptions{extract /(\S+\d)/ as interfaces} show diag summary Using this script, the following conversation may take place: 1. router> show interface descriptions 2. Interface Status 3. Lo0 up Protocol Description up Description of my router>

Page 17

THE PYTHON API 4. PO0/0 5. Serial1/0 6. router> admin down up

6.4 down up

THE CONNECTION IS CLOSED TOO SOON

MyW N link A

Note that line 3 happens to contain the string Router, which looks like a prompt when it really is just a description. So after receiving the character in line 3, Exscript believes that the router is asking for the next command to be sent. So it immediately sends the next command (show diag summary) to the router, even that the next prompt was not yet received. Note that this type of error may not immediately show, because the router may actually accept the command even though it was sent before a prompt was sent. It will lead to an oset however, and may lead to errors when trying to capture the response. It may also lead to the script terminating too early. To x this, make sure that the conversation with the remote host does not include any strings that are incorrectly recognized as prompts. You can do this by using the connection.set prompt(...) function as explained in the sections above.

6.4 The Connection Is Closed Too Soon

This is essentially the same problem as explained under A Command Is Sent Too Soon. Whenever a prompt is (correctly or incorrectly) detected, the next command is send to the remote host. If all commands were already executed and the next prompt is received (i.e. the end of the script was reached), the connection is closed. To x this, make sure that the conversation with the remote host does not include any strings that are incorrectly recognized as prompts. You can do this by using the connection.set prompt(...) function as explained in the sections above.

7 The Python API

7.1 Overview
Exscript provides simple, yet powerful Python APIs. There are two ways in which Exscript APIs may be used: 1. Exscript .protocols is a simple replacement for Pythons built-in telnetlib. 2. Exscript .Queue is a powerful, multi-threaded environment for automating more complex tasks. It comes with features such as logging, user account management, and error handling that make things a lot easier. This is the recommended way of using Exscript.

7.2 Exscript .protocols

The telnetlib module shipped with Python is incomplete, poorly implemented, and does not feature a generic API. To make it easy to access hosts via Telnet and SSH using the exact same API, Exscript

Page 18

THE PYTHON API

7.2 EXSCRIPT .PROTOCOLS

.protocols provides a clean and simple replacement. Exscript supports the following protocols at this time: 1. Telnet is a Telnet adapter. 2. SSH is an adapter for SSH version 1 and version 2. 3. Dummy is a virtual pseudo device that may be used for testing. The following example shows how to connect to a host using Telnet: from Exscript. protocols import Telnet conn = Telnet() conn.connect(127.0.0.1) # The default port is 21 conn.authenticate(myuser, mypassword) conn.execute(ls l) conn.send(exit\r) conn. close() The example will execute the ls -l command on the remote host, and waits until the remote host has responded with a prompt. Once the prompt was retrieved, the function returns and conn.send(exit ) is reached. Unlike execute(), the send() method returns immediately without waiting for a response from the remote host. This is necessary here, because the remote host does not normally respond to the exit command; it just closes the connection. The above code also works with SSH - just replace Telnet with SSH: from Exscript. protocols import SSH conn = SSH() ... To fetch the response of a remote host, the following code may be used: ... conn.execute(ls l) print The host said :, repr(conn.response)

7.2.1 Emulating A Remote Device Exscript also provides a dummy protocol adapter for testing purposes. It emulates a remote host and may be used in place of the Telnet and SSH adapters: from Exscript. protocols import D m y u m conn =D m y() u m ... In order to dene the behavior of the dummy, you may dene it by providing a Python le that maps commands to responses. E.g.:

Page 19

THE PYTHON API def echo(command): return command. split( , 1)[1] commands = ( ( ls l , rw r 1 sab nmc 1906 Oct 5 11:18 Makefile r rw r 1 sab nmc 1906 Oct 5 11:18 myfile r ) , (r echo [\r\n]+ , echo) )

7.3 EXSCRIPT .QUEUE

Note that the command name is a regular expression, and the response may be either a string or a function.

7.3 Exscript .Queue

The more powerful and recommended way of using Exscript is by using Exscript .Queue. Consider the following simple example: #!/usr/bin/env python from Exscript. util . f i l e from Exscript. util .match from Exscript. util .template from Exscript. util . start import import import import get hosts from file any match eval file quickstart

def do something(conn): conn.execute( show ip int brie ) ge interfaces = any match(conn, r (Gigabit\S+)) eval file (conn, mytemplate. exscript , interfaces = ge interfaces) # Read a l i s t of hostnames from a fi le . hosts = get hosts from file( hostlist . txt ) # Open a connection (Telnet, by default) to each of the hosts , and run # do something(). To open the connection via SSH, you may prefix the # hostname by the protocol , e.g. : ssh://hostname , telnet://hostname , # etc . # The max threads keyword indicates the maximum number of concurrent # connections. quickstart(hosts , do something, max threads = 5) This code reads a list of hostnames from hostlist.txt, automatically logs into each of the hosts, and executes the do something once for each of the hosts.

Page 20

THE STANDARD LIBRARY

The quickstart() function is a shortcut that you can use in most cases. However, there are some more advanced features that you can use. For example, Exscript can generate a report for all of the executed tasks: #!/usr/bin/env python from Exscript import Queue, Logger from Exscript. util . f i l e import get hosts from file , get accounts from file from Exscript. util .report import status , summarize def do something(conn): conn.open() conn.authenticate() conn.execute( show ip int brie ) # Read input data. accounts = get accounts from file( accounts. cfg ) hosts = get hosts from file( hostlist . txt ) # Run do something on each of the hosts. The given accounts are used # round robin. verbose = 0 instructs the queue to not generate any # output on stdout. Using logdir = ... is equivalent to the following : # logger = FileLogger(queue, my/logdir ) # It instructs the queue to automatically log everything to the filesystem ; # one file is created per host. queue = Queue(verbose = 0, max threads = 5, logdir = my/logdir/) logger = Logger(queue) # Logs everything to memory. queue.add account(accounts) # Adds one or more accounts. queue.run(hosts , do something) # Asynchronously enqueues all hosts. queue.shutdown() # Waits until all hosts are completed. # Print a short report. print status(logger) print summarize(logger) Exscript provides additional methods, and also oers protocol-specic options. For a complete list of supported methods please refer to our API documentation.

A The Standard Library

Page 21

THE STANDARD LIBRARY

A.1

MODULE STDLIB.CONNECTION

A.1 Module stdlib.connection

A.1.1 Functions authenticate(scope, user =[None], password =[None]) Looks for any username/password prompts on the current connection and logs in using the given user and password. If a user and password are not given, the function uses the same user and password that were used at the last login attempt; it is an error if no such attempt was made before. Parameters user: A username. (type=string) password: A password. (type=string) authorize(scope, password =[None]) Looks for a password prompt on the current connection and enters the given password. If a password is not given, the function uses the same password that was used at the last login attempt; it is an error if no such attempt was made before. Parameters password: A password. (type=string) auto authorize(scope, password =[None]) Executes a command on the remote host that causes an authorization procedure to be started, then authorizes using the given password in the same way in which authorize() works. Depending on the detected operating system of the remote host the following commands are started: on IOS, the enable command is executed. nothing on other operating systems yet. Parameters password: A password. (type=string) close(scope) Closes the existing connection with the remote host. This function is rarely used, as normally Exscript closes the connection automatically when the script has completed.

Page 22

THE STANDARD LIBRARY exec(scope, data)

A.1

MODULE STDLIB.CONNECTION

Sends the given data to the remote host and waits until the host has responded with a prompt. If the given data is a list of strings, each item is sent, and after each item a prompt is expected. This function also causes the response of the command to be stored in the built-in response variable. Parameters data: The data that is sent. (type=string) execline(scope, data) Like exec(), but appends a newline to the command in data before sending it. Parameters data: The data that is sent. (type=string) guess os(scope) Guesses the operating system of the connected host. The recognition is based on the past conversation that has happened on the host; Exscript looks for known patterns and maps them to specic operating systems. Return Value The operating system. (type=string) send(scope, data) Like exec(), but does not wait for a response of the remote host after sending the command. Parameters data: The data that is sent. (type=string) sendline(scope, data) Like execline(), but does not wait for a response of the remote host after sending the command. Parameters data: The data that is sent. (type=string)

Page 23

THE STANDARD LIBRARY wait for(scope, prompt)

A.1

MODULE STDLIB.CONNECTION

Waits until the response of the remote host contains the given pattern. Parameters prompt: The prompt pattern. (type=regex) set prompt(scope, prompt=None) Denes the pattern that is recognized at any future time when Exscript needs to wait for a prompt. In other words, whenever Exscript waits for a prompt, it searches the response of the host for the given pattern and continues as soon as the pattern is found. Exscript waits for a prompt whenever it sends a command (unless the send() method was used). set prompt() redenes as to what is recognized as a prompt. Parameters prompt: The prompt pattern. (type=regex) set error(scope, error re=None) Denes a pattern that, whenever detected in the response of the remote host, causes an error to be raised. In other words, whenever Exscript waits for a prompt, it searches the response of the host for the given pattern and raises an error if the pattern is found. Parameters error re: The error pattern. (type=regex) set timeout(scope, timeout) Denes the time after which Exscript fails if it does not receive a prompt from the remote host. Parameters timeout: The timeout in seconds. (type=int)

Page 24

THE STANDARD LIBRARY

A.2

MODULE STDLIB.CRYPT

A.2 Module stdlib.crypt

A.2.1 Functions otp(scope, password, seed, seqs) Calculates a one-time password hash using the given password, seed, and sequence number and returns it. Uses the md4/sixword algorithm as supported by TACACS+ servers. Parameters password: A password. (type=string) seed: A username. (type=string) seqs: A sequence number, or a list of sequence numbers. (type=int) Return Value A hash, or a list of hashes. (type=string)

Page 25

THE STANDARD LIBRARY

A.3

MODULE STDLIB.FILE

A.3 Module stdlib.le

A.3.1 Functions chmod(scope, lename, mode) Changes the permissions of the given le (or list of les) to the given mode. You probably want to use an octal representation for the integer, e.g. chmod(myle, 0644). Parameters filename: A lename. (type=string) mode: The access permissions. (type=int) clear(scope, lename) Clear the contents of the given le. The le is created if it does not exist. Parameters filename: A lename. (type=string) exists(scope, lename) Returns True if the le with the given name exists, False otherwise. If a list of les is given, the function returns True only if ALL of the les exist. Parameters filename: A lename. (type=string) Return Value The operating system of the remote device. (type=bool) mkdir(scope, dirname, mode=None) Creates the given directory (or directories). The optional access permissions are set to the given mode, and default to whatever is the umask on your system dened. Parameters dirname: A lename, or a list of dirnames. (type=string) mode: The access permissions. (type=int)

Page 26

THE STANDARD LIBRARY read(scope, lename)

A.3

MODULE STDLIB.FILE

Reads the given le and returns the result. The result is also stored in the built-in response variable. Parameters filename: A lename. (type=string) Return Value The content of the le. (type=string) rm(scope, lename) Deletes the given le (or les) from the le system. Parameters filename: A lename, or a list of lenames. (type=string) write(scope, lename, lines, mode=[a]) Writes the given string into the given le. The following modes are supported: a: Append to the le if it already exists. w: Replace the le if it already exists. Parameters filename: A lename. (type=string) lines: The data that is written into the le. (type=string) mode: Any of the above listed modes. (type=string)

Page 27

THE STANDARD LIBRARY

A.4

MODULE STDLIB.IPV4

A.4 Module stdlib.ipv4

A.4.1 Functions in network(scope, prexes, destination, default pfxlen=[24]) Returns True if the given destination is in the network range that is dened by the given prex (e.g. 10.0.0.1/22). If the given prex does not have a prex length specied, the given default prex length is applied. If no such prex length is given, the default length is /24. If a list of prexes is passed, this function returns True only if the given destination is in ANY of the given prexes. Parameters prefixes: A prex, or a list of IP prexes. (type=string) destination: An IP address. (type=string) default pfxlen: The default prex length. (type=int) Return Value Whether the given destination is in the given network. (type=True) mask(scope, ips, mask ) Applies the given IP mask (e.g. 255.255.255.0) to the given IP address (or list of IP addresses) and returns it. Parameters ips: A prex, or a list of IP prexes. (type=string) mask: An IP mask. (type=string) Return Value The network(s) that result(s) from applying the mask. (type=string)

Page 28

THE STANDARD LIBRARY mask2pfxlen(scope, masks)

A.4

MODULE STDLIB.IPV4

Converts the given IP mask(s) (e.g. 255.255.255.0) to prex length(s). Parameters masks: An IP mask, or a list of masks. (type=string) Return Value The prex length(s) that result(s) from converting the mask. (type=string) pfxlen2mask(scope, pfxlen) Converts the given prex length(s) (e.g. 30) to IP mask(s). Parameters pfxlen: An IP prex length. (type=int) Return Value The mask(s) that result(s) from converting the prex length. (type=string) pfxmask(scope, ips, pfxlen) Applies the given prex length to the given ips, resulting in a (list of) IP network addresses. Parameters ips: An IP address, or a list of IP addresses. (type=string) pfxlen: An IP prex length. (type=int) Return Value The mask(s) that result(s) from converting the prex length. (type=string)

Page 29

THE STANDARD LIBRARY remote ip(scope, local ips)

A.4

MODULE STDLIB.IPV4

Given an IP address, this function calculates the remaining available IP address under the assumption that it is a /30 network. In other words, given one link net address, this function returns the other link net address. Parameters local ips: An IP address, or a list of IP addresses. (type=string) Return Value The other IP address of the link address pair. (type=string)

Page 30

THE STANDARD LIBRARY

A.5

MODULE STDLIB.LIST

A.5 Module stdlib.list

A.5.1 Functions new(scope) Returns a new, empty list. Return Value The model of the remote device. (type=string) unique(scope, source) Returns a copy of the given list in which all duplicates are removed such that one of each item remains in the list. Parameters source: A list of strings. (type=string) Return Value The cleaned up list of strings. (type=string)

Page 31

THE STANDARD LIBRARY

A.6

MODULE STDLIB.STRING

A.6 Module stdlib.string

A.6.1 Functions replace(scope, strings, source, dest) Returns a copy of the given string (or list of strings) in which all occurrences of the given source are replaced by the given dest. Parameters strings: A string, or a list of strings. (type=string) source: What to replace. (type=string) dest: What to replace it with. (type=string) Return Value The resulting string, or list of strings. (type=string)

Page 32

THE STANDARD LIBRARY

A.7

MODULE STDLIB.SYS

A.7 Module stdlib.sys

A.7.1 Functions message(scope, string) Writes the given string to stdout. Parameters string: A string, or a list of strings. (type=string) tacacs lock(scope, user ) Acquire an exclusive lock on the account of the user with the given name. Parameters user: A username. (type=string) tacacs unlock(scope, user ) Release the exclusive lock on the account of the user with the given name. Parameters user: A username. (type=string) run(scope, hostnames, lename) Runs the template le with the given name on the host with the given hostname. If the lename is not absolute, it is relative to the path of the script that makes the call. Any variables that are dened in the current scope of the calling script are also passed to the template. Parameters hostnames: A hostname, or a list of hostnames. (type=string) filename: The name of the Exscript le to be executed. (type=string) wait(scope, seconds) Waits for the given number of seconds. Parameters seconds: The wait time in seconds. (type=int)

Page 33