Whatsconfigured V3.1: Custom Script Language Guide
Whatsconfigured V3.1: Custom Script Language Guide
1
Custom Script Language Guide
Contents
Table of Contents
Script Examples
Example Scripts ........................................................................................................................................................... 20
Copyright notice ......................................................................................................................................................... 22
i
CHAPTER 1
The WhatsConfigured Custom Script
Language
In This Chapter
About the WhatsConfigured Custom Script Language ...........................1
@login
@enable
[-] exit
The WhatsConfigured custom script language is relatively simple and consists primarily of
command-line interface (CLI) commands. The language is not meant to be a full-featured
scripting language, such as JavaScript or VBScript, but rather is kept simple so that is
accessible to all levels of WhatsConfigured users, including those with minimal programming
skills. In order to meet the standards of this target audience, the language contains no
1
WhatsConfigured v3.1Custom Script Language Guide
constructs for looping, branching, or creating subroutines; it only supports simple sequences
of commands.
2
CHAPTER 2
Using WhatsConfigured Comments
In This Chapter
About WhatsConfigured comments ..............................................................3
Note: A # character is interpreted as the beginning of a comment only if it is the first non-
whitespace character on a line. If the # appears later in the line, it has no special significance.
Examples
# This is a comment
123 # This is not a comment because '#' is not the first non-whitespace
character in the line
3
CHAPTER 3
Using WhatsConfigured Variables
In This Chapter
About variables ......................................................................................................4
Accessing protocol settings...............................................................................5
Using variables with WhatsConfigured templates ....................................5
Using reserved WhatsConfigured variable names ....................................6
About variables
Variables are useful for giving names to values referenced in a script, especially values that
are referenced multiple times. For example,
CommandTerminator = "\r\n"
TFTPServerAddress = 192.168.10.50
TransferFileName= startup-config.txt
@login
@write "copy tftp start"
@write $(CommandTerminator)
@write "$(TFTPServerAddress)"
@write "(TransferFileName)"
@write $(CommandTerminator)
Variable definitions
A variable definition must appear on a line by itself, in the following form:
Name = Value
In the example above, Name is the variable's title, and Value is the variable's value.
Variable names must begin with an alphabetic character or an underscore (a-z, A-Z, _), and
subsequent characters can be any alphanumeric character or an underscore (a-z, A-Z, 0-9, _).
4
WhatsConfigured v3.1Custom Script Language Guide
The variable's value consists of all text on the right side of = with leading and trailing
whitespace removed. For example,
The example above defines a variable named "FirstUSPresident" with the value "The
Honorable George Washington".
A variable's value can be referenced anywhere in the script after the variable is defined. A
variable reference consists of '$' immediately followed by the variable's name in parentheses,
as shown below.
$(FirstUSPresident)
A variable reference is replaced by the variable's value. If the variable is defined multiple
times in the script, the most recent definition is used. In the example above, the variable
reference "$(FirstUSPresident)" would be replaced by "The Honorable George
Washington".
Note: The values of these variables are read-only and cannot be modified by scripts, though
scripts are free to reference their values.
5
WhatsConfigured v3.1Custom Script Language Guide
Note: The values of these variables are read-only and cannot be modified by scripts, though
scripts are free to reference their values.
Name Description
DateTime The current system date and time in the format yyMMdd-
HHmmss.
Device.IPv4Address The device's IPv4 address.
Device.IPv6Address The device's IPv6 address.
Device.IpAddress The device's network IP address.
Device.SystemName The device's hostname.
FileCaptureKey The presence of this variable in a script indicates that the
device configuration specified with the variable should be
captured from the file system as part of the transfer task.
FileTransferMethod Determines the file transfer method to be used for the config
file upload. Can be: SCP_SERVER, SCP_Client, SFTP_SERVER,
SFTP_CLIENT, TFTP_SERVER.
ScpClientDirectory The SCP client directory.
ScpServerAddress The IP address of the SCP server.
ScpServerPassword The password of the SCP server.
ScpServerPort The port of the SCP server.
ScpServerUserName The username required to connect to the SCP server.
SftpClientDirectory The SFTP client directory.
SftpServerAddress The IP address of the SFTP server.
SftpServerPassword The password of the SFTP server.
SftpServerPort The port of the SFTP server.
SftpServerUserName The username required to connect to the SFTP server.
6
WhatsConfigured v3.1Custom Script Language Guide
§ AddReadWrite
§ AddUserName
§ CommandPrompt
§ CommandTerminator
§ LoginTerminator
§ MorePrompt
§ MoreResponse
§ Password
§ PasswordPrompt
§ PrivilegedPassword
§ RemoveCommunity RO
§ RemoveCommunity RW
§ RemovePassword
§ RemovePrivilegedPassword
§ RemoveReadOnly
§ RemoveReadWrite
§ RemoveUserName
§ TFTPServerAddress
§ TransferFileName
§ UserName
§ UserNamePrompt
Occassionally, a script may need to re-define one or more of these variables to affect the
internal operation of WhatsConfigured commands. The section on WhatsConfigured
commands describes the meanings and uses of these variables, and how scripts can re-define
them to modify the behavior of WhatsConfigured commands.
7
CHAPTER 4
Using WhatsConfigured Commands
In This Chapter
About commands..................................................................................................8
About basic WhatsConfigured command syntax ......................................9
About strings and regular expressions in WhatsConfigured .................9
About "$" ............................................................................................................... 10
Storing WhatsConfigured command output in the WhatsUp Gold database 11
Editing WhatsConfigured command output............................................ 12
Using WhatsConfigured commands with queries.................................. 12
About WhatsConfigured command layout............................................... 13
WhatsConfigured script variables affecting command execution ... 14
About WhatsConfigured command types ................................................ 15
About commands
Beyond commands and variables definitions, the other lines in a script contain the
commands to be executed by the script.
Examples
@login
@enable
config t
line vty 0 4
login local
exit
exit
[-] exit
8
WhatsConfigured v3.1Custom Script Language Guide
In its simplest form, a command is just a string specifying the name of a command along with
any parameters it requires. For example, the following script contains two simple commands:
@ login
Strings are used to represent literal text values; string values are sequences of characters
delimited by double quotes, such as:
Escape sequences (used to define special characters within strings) may be any of the
following:
9
WhatsConfigured v3.1Custom Script Language Guide
Additionally, the \x escape sequence can be used to include arbitrary characters in strings,
including unprintable and control characters. \x should be followed by one to four
hexadecimal digits which specify the value of the desired character. For example,
Regular expressions are used for matching patterns in the output of script commands.
Regular expression values are .NET regular expression strings delimited by forward slashes.
For example, the following regular expression might be used to match the command prompt
on a particular device (i.e., one or more characters followed by > or #):
/.+(>|#)/
Because forward slashes are used to delimit regular expression values, including a forward
slash as part of the regular expression itself, requires the use of the // escape sequence. For
example, the following regular expression matches one or more characters followed by a
forward slash followed by one or more characters followed by #:
/.+//.+#/
About "$"
Within WhatsConfigured scripts the dollar sign, '$', is a reserved character required for use in
variable references. If a script requires the use of a dollar sign outside of the variable
reference it may be escaped with an additional dollar sign.
10
WhatsConfigured v3.1Custom Script Language Guide
For example to write the Password 'pa$$word' you would escape the two dollar signs with
additional dollar signs: 'pa$$$$word'
Note: To avoid erroneous dollar sign variable references WhatsConfigured allows a single
unescaped dollar sign when not followed by an open parentheses "$(". A line containing
"thi$" would pass without needing to be escaped. Whereas the line "thi$(" would require
the dollar sign be escaped "thi$$(".
Use the table below as an illustration of how many $'s you must enter in WhatsConfigured to
achieve the appropriate number of $'s in a script command.
To achieve x # of $'s Enter this many $'s in the code
$ $$
$$ $$$ or $$$$
$$$ $$$$$ (5) or $$$$$$ (6)
$$$$ $$$$$$$ (7) or $$$$$$$$ (8)
This means, execute the show run command and store its output in the WhatsUp Gold
database under the running-config key.
Note: Key names can include dashes, underscores, and alphanumeric characters (-,_,a-z, A-Z).
However, spaces are not allowed in key names.
11
WhatsConfigured v3.1Custom Script Language Guide
If multiple editing operators are used in the same command, they are applied in the order
shown in the previous table.
12
WhatsConfigured v3.1Custom Script Language Guide
The first value inside the curly braces is a String or Regular Expression describing the query
prompt displayed by the device. The second value inside the curly braces is a String
specifying the query response that should be entered in response to the query prompt. When
the script interpreter executes this command, it will first send shutdown to the device. Next,
it will wait until it receives the "Are you sure? " query prompt. Then, it will send Y to the
device as the query response. Finally, the device will execute the command.
Note: Only Device commands can have a QUERY. WhatsConfigured commands do not need
a QUERY, and, in fact, may not have one.
For example,
For example,
As previously explained, KEY specifies the key to use when storing the command's output in
the WhatsUp Gold database, and possibly operations for trimming the command output.
COMMAND is the text for the command itself. QUERY specifies the query prompt and query
response for commands that ask a question. COMMAND is required, while KEY and QUERY are
optional.
Since commands can become long, it is legal to put the KEY, COMMAND, and QUERY parts of
a command on different lines. For example, the following commands are equivalent:
[last-words]
shutdown
[last-words]
[last-words] shutdown
13
WhatsConfigured v3.1Custom Script Language Guide
While the KEY, COMMAND, and QUERY can be on different lines from each other, each of
these individual elements must start and end on the same line (i.e., they cannot span multiple
lines). For example, the following commands are not valid:
last-words
[last-words] shut
[last-words]
shutdown
"Y"
14
WhatsConfigured v3.1Custom Script Language Guide
a user logs in
CommandPrompt String or regular Pattern describing the command /.+(#|>) /
expression prompt displayed by the device when
prompting the user for a command
MorePrompt String or regular Pattern describing the "more" prompt /--More--|--
expression displayed by the device when More--/
displaying paged output
MoreResponse String String to be entered in response to a ""
"more" prompt
LoginTerminator String Line termination sequence to be used "\r\n"
with logging in
CommandTerminator String Line termination sequence to be used "\n"
when executing commands
@login
Typically, the first step in any WhatsConfigured script is to login to the device. This is typically
done with the WhatsConfigured @login command. The @login command can be used to
login to devices that use a traditional user-name/password login procedure that works as
follows:
1 The device prompts the user for their user name
2 The user enters their user name
3 The device prompts the user for their password
4 The user enters their password
5 If login is successful, the device displays a command prompt and waits for the user to
run commands
The @login command has no parameters, and is invoked as follows:
@login
15
WhatsConfigured v3.1Custom Script Language Guide
@enable
Many device configuration tasks require a script to enter a privileged mode in order to
execute the necessary device commands. On many devices, privileged mode is entered using
the enable command. Typically, running the enable command on a device requires the
user to enter a user name and/or password. For devices that implement this style of enable
command, scripts can use the WhatsConfigured @enable command to easily enter privileged
mode. The @enable command has no parameters, and is invoked as follows:
@enable
Device commands
After invoking the @login command (and possibly @enable as well), most scripts contain a
sequence of Device commands that are sent to the device for execution. A typical Device
command is shown below:
The script sends the command text to the device. It terminates the command with
CommandTerminator.
If the command has a query, the device returns the query to the script. When it detects the
query prompt, the script sends the query response to the device.
16
WhatsConfigured v3.1Custom Script Language Guide
Next, the device executes the commands, and sends its output back to the script.
If the command's output is long enough to result in more prompts, when the script detects a
MorePrompt, it sends MoreResponse to the device.
The script consumes the command's output until it detects CommandPrompt, at which point it
assumes that the command's output is complete.
If at any time the device's output stalls for more than Settings.ReadTimeout, it is assumed
that something is wrong, and the script returns failure.
If the command succeeds, and it has a KEY, its output is saved in the WhatsUp Gold database.
@login
[-] logout
This script first logs in with the @login command, then enters privileged mode with the
@enable command.
Next, the script sends the show run command to the device. The output of this command is
saved in the WUG database under the running-config key.
Finally, the script sends the logout command to the device, at which point the device closes
the network connection.
The [-] key on the logout command tells WhatsConfigured not to expect any output from
the command, because the command causes the device to close the network connection.
Typically, receiving no output from a command indicates failure, but in the case of exit or
logout commands (or any other command that closes the connection), a lack of output
does not indicate failure. Script authors can use the [-] key to indicate such commands and
prevent WhatsConfigured from returning failure when the device closes the connection.
Low-level commands
Many scripts will use only @login, @enable, and Device commands to implement their
functionality. However, some devices have non-standard Telnet or SSH interfaces that won't
work with @login and Device commands. For example, some devices have non-standard
login procedures for which the @login command will not work. Other devices have menu-
driven interfaces rather than a standard command-prompt-style interface. For whatever
reason, if @login, @enable, or Device commands do not work for a particular device,
WhatsConfigured provides a set of low-level commands that can be used to interact with
virtually any device, no matter how non-standard its interface might be.
17
WhatsConfigured v3.1Custom Script Language Guide
The @connect command allows a script to precisely control the process of logging in to a
device. The @write command allows a script to control exactly what input is sent to a device.
The @read command allows a script to read output from a device and optionally store it in
the WhatsUp Gold database.
@connect
The @connect command is an alternative to @login in cases where a script needs to
precisely control the login process (e.g., in cases where @login doesn't work for a particular
device). The @connect command connects to a device without trying to log in. After
connecting to a device with @connect, if the device requires users to login, the script can
control the login process precisely using the @write and @read commands, which are
described later.
When calling @connect, scripts can specify one or more patterns (i.e., strings or regular
expressions) that specify the output the script expects to receive from the device when it
connects. These patterns are used by @connect to detect the end of the device output.
@connect will assume that device output is complete when either the output matches one of
the specified patterns, or no new output has been received from the device for
Settings.ReadTimeout seconds. For example,
When executed, @connect connects to the device, and reads whatever output comes back
from the device. If the output matches one of the specified patterns, the command succeeds.
If the connection attempt fails entirely, or the output received from the device does not
match any of the specified patterns, the command fails (as well as the entire script). As with
any other command, a KEY can be specified to capture the command's output in the
WhatsUp Gold database, although one would rarely want to store the output of an @connect
command.
If no patterns are specified (as shown below), @connect connects to the device, and returns
whatever output comes back from the device. In this case, the command succeeds as long as
a connection is successfully established with the device.
@connect-more
Some devices return paged output that requires more prompts when you initially connect to
them. If a script needs to handle more prompts during the connection process, it can use the
@connect-more command instead of @connect. @connect-more works just like @connect,
except that it handles more prompts during the connection process, while @connect does
not. Specifically, if MorePrompt is detected during the connection process, @connect-more
sends MoreResponse to the device.
18
WhatsConfigured v3.1Custom Script Language Guide
@write
The @write command can be used to send a string of characters to the device. This
command allows a script to precisely control what input is being sent to the device. For
example, the following script sends the show run command to the device, followed by the
CommandTerminator (typically \n or \r\n).
@write $(CommandTerminator)
@read
The @read command can be used by scripts to read the output coming back from the device.
Typically, a call to @read will immediately follow a call to @write. When calling @read, scripts
can specify one or more patterns (i.e., strings or regular expressions) to help @read detect the
end of the device output. @read will assume that device output is complete when either: the
output matches one of the specified patterns, or no new output has been received from the
device for Settings.ReadTimeout seconds. Often, the output will end with
CommandPrompt, so "@read $(CommandPrompt)" is a common way to call @read. If desired,
the output received from the device can be stored in the WhatsUp Gold database, as shown
below:
@write $(CommandTerminator)
When executed, @read will read whatever output comes back from the device. If the output
matches one of the specified patterns, the command succeeds. If the output received from
the device does not match one of the specified patterns, the command fails (as well as the
entire script).
If no patterns are specified (as shown below), @read will return whatever output comes back
from the device. In this case, the command will succeed as long as the connection to the
device is still open.
@read-more
Some devices return paged output that requires more prompts. If a script needs to handle
more prompts during a read operation, it can use the @read-more command instead of
@read. @read-more works just like @read, except that it handles more prompts during the
reading process, while @read does not. Specifically, if MorePrompt is detected during the
reading process, @read-more will send MoreResponse to the device.
19
CHAPTER 5
Script Examples
In This Chapter
Example Scripts ................................................................................................... 20
Copyright notice ................................................................................................. 21
Example Scripts
This example shows a typical script that uses @login to login to the device, uses @enable to
enter privileged mode, and then executes several Device commands.
@login
@enable
[-] exit
This example shows how to login to a device and run a command using only low-level
WhatsConfigured commands:
@write "$(Settings.UserName)"
@write $(LoginTerminator)
@write "$(Settings.Password)"
@write $(LoginTerminator)
@read $(CommandPrompt)
@write "exit"
@write $(CommandTerminator)
This example shows how to combine high-level commands and low-level commands in the
same script as above:
20
WhatsConfigured v3.1Custom Script Language Guide
@login
@enable
@write $(CommandTerminator)
@write "$(TFTPServerAddress)"
@write $(CommandTerminator)
@write "$(TransferFileName)"
@write $(CommandTerminator)
@write $(CommandTerminator)
[-] exit
21
WhatsConfigured v3.1Custom Script Language Guide
Copyright notice
©1991-2013 Ipswitch, Inc. All rights reserved.
This document, as well as the software described in it, is furnished under license and may be
used or copied only in accordance with the terms of such license. Except as permitted by
such license, no part of this publication may be reproduced, photocopied, stored on a
retrieval system, or transmitted, in any form or by any means, electronic, mechanical,
recording, or otherwise, without the expressed prior written consent of Ipswitch, Inc.
The content of this document is furnished for informational use only, is subject to change
without notice, and should not be construed as a commitment by Ipswitch, Inc. While every
effort has been made to assure the accuracy of the information contained herein, Ipswitch,
Inc. assumes no responsibility for errors or omissions. Ipswitch, Inc., also assumes no liability
for damages resulting from the use of the information contained in this document.
IMail, the IMail logo, WhatsUp, the WhatsUp Gold logo, WS_FTP, the WS_FTP logos, Ipswitch,
and the Ipswitch logo are trademarks of Ipswitch, Inc. Portions of Telerik Extensions for
ASP.NET MVC ©2002-2012 by Telerik Corporation. All rights reserved. Other products and
their brands or company names, are or may be trademarks or registered trademarks, and are
the property of their respective companies.
22