12.2. SteelScript Command Line Sources¶

12.2.1. CLI Objects¶

class steelscript.cmdline.cli.__init__.CLI(hostname=None, username=u'admin', password=None, private_key_path=None, terminal=u'console', prompt=None, port=None, machine_name=None, machine_manager_uri=u'qemu:///system', channel_class=<class 'steelscript.cmdline.sshchannel.SSHChannel'>, **channel_args)¶

Base class CLI implementation for Network Devices

Vendor specific CLIs can inherit from this base class. This class by itself will try to work on a generic CLI if vendor specific class is not present.

For the “should match any prompt” regular expressions, the focus was mostly on common OSes in Riverbed’s internal environment. Other systems may require subclassing this class and overriding the prompt regexes.

Parameters:

host – host/ip user – username to log in with password (string) – password to log in with private_key_path (string) – absolute path to RSA private key, used instead of password terminal (string) – terminal emulation to use; default to ‘console’ prompt (regex pattern) – A prompt to match. Defaults to CLI_ANY_PROMPT transport_type (string) – DEPRECATED (use channel_class): telnet or ssh, defaults to ssh user – DEPRECATED (use username) host – DEPRECATED (use hostname) channel_class (class) – Class object to instantiate for persistent communication. Defaults to steelscript.cmdline.sshchannel.SSHChannel channel_args – additional transport_type-dependent arguments, passed blindly to the transport start method.

CLI_ANY_PROMPT = u'(^|\n|\r)(\\[?\\S+\\s?\\S+\\]?)(#|\\$|>|~)(\\s)?$'¶

A regex that is suitable for most CLIs, root or regular user.

Note that this does not specifically check hostnames, which might lead to false positive matches.

CLI_ROOT_PROMPT = u'(^|\n|\r)(\\[?\\S+\\s?\\S+\\]?)(#)(\\s)?$'¶

A regex intended for use with POSIX prompts for root ending in ‘#’

CLI_START_PROMPT = u'(^|\n|\r)(\\[?\\S+\\s?\\S+\\]?)(#|\\$|>|~)(\\s)?$'¶

A regex suitable for most initial CLI prompts, root or non-root

exec_command(command, timeout=60, output_expected=None, prompt=None)¶

Executes the given command.

This method handles detecting simple boolean conditions such as the presence of output or errors.

Parameters:	command – command to execute, newline appended automatically timeout – maximum time, in seconds, to wait for the command to finish. 0 to wait forever. output_expected (bool or None) – If not None, indicates whether output is expected (True) or no output is expected (False). If the opposite occurs, raise UnexpectedOutput. Default is None. prompt – Prompt regex for matching unusual prompts. This should almost never needed. This parameter is for unusual situations like an install config wizard.
Returns:	output of the command, minus the command itself.
Raises:	TypeError – if output_expected type is incorrect CmdlineTimeout – on timeout UnexpectedOutput – if output occurs when no output was expected, or no output occurs when output was expected

start(start_prompt=None)¶

Initialize underlying channel.

Parameters:	start_prompt (regex pattern) – A non-default prompt to match, if any.

12.2.2. Channel Objects¶

class steelscript.cmdline.channel.Channel¶

Abstract class to define common interface for a two communication channel.

expect(match_res, timeout=60)¶

Waits for some text to be received that matches one or more regex patterns.

Parameters:	match_res – A list of regex pattern(s) to look for to be considered successful. timeout – maximum time, in seconds, to wait for a regular expression match. 0 to wait forever.
Returns:	(output, re.MatchObject) where output is the output of the command (without the matched text), and MatchObject is a Python re.MatchObject containing data on what was matched. You may use MatchObject.string[m.start():m.end()] to recover the actual matched text. MatchObject.re.pattern will contain the pattern that matched, which will be one of the elements of match_res passed in.

fixup_carriage_returns(data)¶

To work around all the different \r\n combos we are getting from the CLI, we normalize it as:

1. Eat consecutive \r’s (a\r\r\nb -> a\r\nb)
2. Convert \r\n’s to \n (a\r\nb -> a\nb)
3. Convert \n\r to \n (a\r\n\rb) -> (a\n\rb) -> (a\nb)
4. Convert single \r’s to \n, unless at end of strings (a\rb -> a\nb)

#4 doesn’t trigger at the end of the line to cover partially received

data; the next character that comes in may be a \n, \r, etc.

Parameters:	data – string to convert
Returns:	the string data with the linefeeds converted into only \n’s

receive_all()¶

Returns all text currently in the receive buffer, effectively flushing it.

Returns:	the text that was present in the receive queue, if any.

safe_line_feeds(in_string)¶

Parameters:	in_string – string to replace linefeeds
Returns:	a string that has the linefeeds converted to ASCII representation for printing

send(text_to_send)¶

Sends text to the channel immediately. Does not wait for any response.

Parameters:	text_to_send – Text to send, including command terminator(s) when applicable.

12.2.3. CmdlineException Objects¶

class steelscript.cmdline.exceptions.CmdlineException(command=None, output=None, _subclass_msg=None)¶

Base exception representing an error executing the command line.

Parameters:	command – The command that produced the error. output – The output returned, possibly None.
Variables:	command – The command that produced the error. output – The output returned. None if the command did not return.

12.2.4. LibVirtChannel Objects¶

class steelscript.cmdline.libvirtchannel.LibVirtChannel(machine_name, machine_manager_uri=u'qemu:///system', username=u'root', password=u'', **kwargs)¶

Channel for connecting to a serial port via libvirt.

Parameters:	machine_name – The libvirt domain to which to connect. machine_manager_uri – The hypervisor uri where the domain may be found. Defaults to a local qemu hypervisor. user – username for authentication password – password for authentication

expect(match_res, timeout=300)¶

Matches regular expressions against singles lines in the stream.

Internally, this method works with bytes, but input and output are unicode as usual.

Parameters:	match_res – a list of regular expressions to match against the output. timeout – Time to wait for matching data in the stream, in seconds. Note that the default timeout is longer than on most channels.
Returns:	(output, match_object) where output is the output of the command (without the matched text), and match_object is a Python re.MatchObject containing data on what was matched. You may use MatchObject.string[m.start():m.end()] to recover the actual matched text, which will be unicode. re.MatchObject.pattern will contain the pattern that matched, which will be one of the elements of match_res passed in.
Raises:	CmdlineTimeout – if no match found before timeout.

receive_all()¶

Returns all text currently in the receive buffer, effectively flushing it.

Returns:	the text that was present in the receive queue, if any.

send(text_to_send)¶

Sends text to the channel immediately. Does not wait for any response.

Parameters:	text_to_send – Text to send, including command terminator(s) when applicable.

start(match_res=(u'(^|\n|\r)([-a-zA-Z0-9_.]* )?# ', ), timeout=300)¶

Opens a console and logs in.

Parameters:	match_res – Pattern(s) of prompts to look for. May be a single regex string, or a list of them. timeout – maximum time, in seconds, to wait for a regular expression match. 0 to wait forever.
Returns:	Python re.MatchObject containing data on what was matched.

12.2.5. Shell Objects¶

class steelscript.cmdline.shell.Shell(host, user=u'root', password=u'')¶

Class for running shell command remotely and statelessly.

No persistent channel is maintained, so changes to environment variables or other state will not be present for subsequent commands.

Parameters:	host – host/ip to ssh into user – username to log in with password – password to log in with

exec_command(command, timeout=60, output_expected=None, error_expected=False, exit_info=None, retry_count=3, retry_delay=5, expect_output=None, expect_error=None)¶

Executes the given command statelessly.

Since this is stateless, an exec_command cannot use environment variables/directory changes/whatever from a previous exec_command.

This method handles detecting simple boolean conditions such as the presence of output or errors.

Parameters:	command – command to send timeout – seconds to wait for command to finish. None to disable output_expected (bool or None) – If not None, indicates whether output is expected (True) or no output is expected (False). If the opposite occurs, raise UnexpectedOutput. Default is None. error_expected (bool) – If true, a nonzero exit status will not trigger an exception as it normally would. Default is False, and error_expected always overrides output_expected. exit_info (dict or None) – If set to a dict, the exit status is added to the dictionary under the key ‘status’. Primarily used in conjunction with error_expected when multiple nonzero statuses are possible. retry_count (int) – the number of tries to reconnect if underlying connection is disconnected. Default is 3 retry_delay (int) – delay in seconds between each retry to connect. Default is 5
Returns:	output from the command
Raises:	ConnectionError – if the connection is lost CmdlineTimeout – on timeout ShellError – on an unexpected nonzero exit status UnexpectedOutput – if output occurs when no output was expected, or no output occurs when output was expected

12.2.6. SSHChannel Objects¶

class steelscript.cmdline.sshchannel.SSHChannel(hostname, username, password=None, private_key_path=None, port=22, terminal=u'console', width=80, height=24, **kwargs)¶

Two-way SSH channel that allows sending and receiving data.

Parameters:

hostname (string) – hostname, fqdn, or ip address of the target system. port – optional port for the connection. Default is 22. username – account to use for authentication password – password for authentication private_key_path – absolute system path to private key file terminal – terminal emulation to use; defaults to ‘console’ width – width (in characters) of the terminal screen; defaults to 80 height – height (in characters) of the terminal screen; defaults to 24

Both password and private_key_path may be passed, but private keys will take precedence for authentication, with no fallback to password attempt.

Additional arguments are accepted and ignored for compatibility with other channel implementations.

expect(match_res, timeout=60)¶

Waits for text to be received that matches one or more regex patterns.

Note that data may have been received before this call and is waiting in the buffer; you may want to call receive_all() to flush the receive buffer before calling send() and call this function to match the output from your send() only.

Parameters:	match_res – Pattern(s) to look for to be considered successful. May be a single regex string, or a list of them. Currently cannot match multiple lines. timeout – maximum time, in seconds, to wait for a regular expression match. 0 to wait forever.
Returns:	(output, match_object) where output is the output of the command (without the matched text), and match_object is a Python re.MatchObject containing data on what was matched. You may use MatchObject.string[m.start():m.end()] to recover the actual matched text, which will be unicode. re.MatchObject.pattern will contain the pattern that matched, which will be one of the elements of match_res passed in.
Raises:	CmdlineTimeout – if no match found before timeout. ConnectionError – if the channel is closed.

receive_all()¶

Flushes the receive buffer, returning all text that was in it.

Returns:	the text that was present in the receive queue, if any.

send(text_to_send)¶

Sends text to the channel immediately. Does not wait for any response.

Parameters:	text_to_send – Text to send, may be an empty string.

start(match_res=None, timeout=60)¶

Start an interactive ssh session and logs in.

Parameters:	match_res – Pattern(s) of prompts to look for. May be a single regex string, or a list of them. timeout – maximum time, in seconds, to wait for a regular expression match. 0 to wait forever.
Returns:	Python re.MatchObject containing data on what was matched.

12.2.7. SSHProcess Objects¶

class steelscript.cmdline.sshprocess.SSHProcess(host, user=u'root', password=None, private_key=None, port=22)¶

SSH transport class to handle ssh connection setup.

Parameters:	host – host/ip to ssh into user – username to log in with password – password to log in with private_key – paramiko private key (Pkey) object

If a private_key is passed, it will take precendence over a password, no fallback attempt will be made if the private key connection fails, however.

connect()¶

Connects to the host and logs in.

Raises:	ConnectionError – on error

disconnect()¶

Disconnects from the host

is_connected()¶

Check whether SSH connection is established or not.

Returns:	True if it is connected; returns False otherwise.

open_interactive_channel(term=u'console', width=80, height=24)¶

Creates and starts a stateful interactive channel.

This should be used whenever the channel must remain open between commands for interactive processing, or when a terminal/tty is necessary; e.g., CLIs with modes.

Parameters:	term – terminal type to emulate; defaults to ‘console’ width – width (in characters) of the terminal screen; defaults to 80 height – height (in characters) of the terminal screen; defaults to 24
Returns:	A Paramiko channel that communicate with the remote end in a stateful way.
Raises:	ConnectionError – if the SSH connection has not yet been established.

12.2.8. TelnetChannel Objects¶

class steelscript.cmdline.telnetchannel.TelnetChannel(hostname, username='root', password='', port=23, **kwargs)¶

Two-way telnet channel that allows sending and receiving data.

Accepts and ignores additional parameters for compatibility with other channel construction interfaces.

Parameters:	hostname – host/ip to telnet into username – username to log in with password – password to log in with port – telnet port, defaults to 23

expect(match_res, timeout=60)¶

Waits for some text to be received that matches one or more regex patterns.

Note that data may have been received before this call and is waiting in the buffer; you may want to call receive_all() to flush the receive buffer before calling send() and call this function to match the output from your send() only.

Parameters:	match_res – Pattern(s) to look for to be considered successful. May be a single regex string, or a list of them. timeout – maximum time, in seconds, to wait for a regular expression match. 0 to wait forever.
Returns:	(output, match_object) where output is the output of the command (without the matched text), and match_object is a Python re.MatchObject containing data on what was matched. You may use MatchObject.string[m.start():m.end()] to recover the actual matched text, which will be unicode. re.MatchObject.pattern will contain the pattern that matched, which will be one of the elements of match_res passed in.
Raises:	CmdlineTimeout – if no match found before timeout.

receive_all()¶

Flushes the receive buffer, returning all text that was in it.

Returns:	the text that was present in the receive queue, if any.

send(text_to_send)¶

Sends text to the channel immediately. Does not wait for any response.

Parameters:	text_to_send – Text to send, may be an empty string.

start(match_res=None, timeout=15)¶

Start telnet session and log it in

Parameters:	match_res – Pattern(s) of prompts to look for. May be a single regex string, or a list of them. timeout – maximum time, in seconds, to wait for a regular expression match. 0 to wait forever.
Returns:	Python re.MatchObject containing data on what was matched.

12.2.9. Transport Objects¶

class steelscript.cmdline.transport.Transport¶

Abstract class to define common interfaces for a transport.

A transport is used by Cli/Shell object to handle connection setup.

connect()¶

Abstract method to start a connection

disconnect()¶

Abstract method to tear down current connection

is_connected()¶

Check whether a connection is established or not.

Returns:	True if it is connected; returns False otherwise.

12.2.10. Parsers¶

Functions for parsing command line responses

steelscript.cmdline.parsers.cli_parse_basic(input_string)¶

Standard cli parsers for key: value style

This parser goes through all the lines in the input string and returns a dictionary of parsed output. In addition to splitting the output into key value pairs, the values will be fed through parse_boolean to turn strings such as yes and true into boolean objects, leaving other strings alone.

This function will parse cli commands such as:

hw1-int1 (config) # show load balance fair-peer-v2
Fair peering V2: yes
Threshold:       15 %

creating a dictionary:

{
    'fair peering v2': True,
    'threshold' : '15 %'
}

For this example one would want to perform further manipulation on the dictionary to get it into a usable state, changing fair peering v2 to enabled and 15 % to 15 for threshold. See enable_squash() for part of this.

Parameters:	input_string – A string of CLI output to be parsed
Returns:	a dictionary of parsed output

steelscript.cmdline.parsers.cli_parse_table(input_string, headers)¶

Parser for Generic Table style output. More complex tables outputs may require a custom parser.

Parses output such as:

Destination       Mask              Gateway           Interface
10.3.0.0          255.255.248.0     0.0.0.0           aux
default           0.0.0.0           10.3.0.1

The left/right bounds of each data field are expected to fall underneath exactly 1 header. If a data item falls under none or more than 1, an error will be raised.

Data fields are initially divided by 2 spaces. This allows single spaces within the data fields. However, if the data crosses more than 1 header, it is then divided by single spaces and each piece will be part of whatever header it falls under. If any part doesn’t fall underneath a header, an error is raised.

The example output above would produce the following structure:

[
    {
        destination: 10.3.0.0,
        mask: 255.255.248.0,
        gateway: 0.0.0.0,
        interface: aux
    },
    {
        destination: default,
        mask: 0.0.0.0,
        gateway: 10.3.0.1
    },
]

Parameters:	input_string – A string of CLI output to be parsed headers – array of headers in-order starting from the left.
Returns:	an array of dictionaries of parsed output

steelscript.cmdline.parsers.check_numeric(value_string)¶

This function tries to determine if a string would be better represented with a numeric type, either int or float. If neither works, for example 10 Mb, it will simply return the same string provided

Parameters:	value_string – input string to be parsed.
Returns:	the input string, an int, or a float

steelscript.cmdline.parsers.enable_squash(input)¶

Convert long specific enable strings to ‘enabled’

Takes in a dictionary of parsed output, iterates over the keys and looks for key names containing the string “enabled” at the end of the key name. Specifically the end of the key name is matched for safety. Replaces the key with simply “enabled”, for example an input dictionary:

{"Path-selection enabled": False}

becomes:

{"enabled": False}

Parameters:	input – A dictionary of parsed output
Return result:	A dictionary with keys ending in “enabled” replaced with just “enabled”

steelscript.cmdline.parsers.parse_boolean(value_string)¶

Determine the boolean value of the input string.

“yes”, “no”, “true” and “false” are recognized (case-insensitive).

Parameters:	value_string – input string to be parsed.
Returns:	boolean value based on input string
Raises:	ValueError – if the string is not recognized as a boolean

steelscript.cmdline.parsers.restart_required(input)¶

Take result from a cli command and check if a service restart is required. Return True if cli result indicates restart required

Parameters:	input – result from a cli command
Return type:	bool

steelscript.cmdline.parsers.reboot_required(input)¶

Take result from a cli command and check if a reboot is required. Return True if cli result indicates reboot required

Parameters:	input – result from a cli command
Return type:	bool

steelscript.cmdline.parsers.parse_ip_and_port(input)¶

Parse IP and Port number combo to a dictionary:

1.1.1.1:2000

to:

{'ip': IPv4Address('1.1.1.1'), 'port': 2000}

Parameters:	input – IP and port type – string
Returns:	dictionary with keys ip and port

steelscript.cmdline.parsers.parse_url_to_host_port_protocol(input)¶

Parse url to a dictionary using urlparse.urlparse(), inferring the port from the scheme (a.k.a. protocol):

http://blah.com

becomes:

{'host': 'blah.com', 'port': 80, 'protocol': 'http'}

Parameters:	input – url type – string
Returns:	dict with port always specified

steelscript.cmdline.parsers.parse_saasinfo_data(input)¶

Parse saasinfo data to a dictionary contained ip, port and geodns mapping data structures:

=================================
SaaS Application
=================================
SAMPLEAPP

=================================
SaaS IP
=================================
10.41.222.0/24 [0-65535]
111.221.112.0/21 [1-65535]
111.221.116.0/24 [1-65535]
111.221.17.160/27 [1-65535]
111.221.20.128/25 [0-65535]

=================================
SaaS Hostname
=================================
*.mail.apac.example.com
*.example1.com
*.example2.com
example1.com

=================================
GeoDNS
=================================
---------------------------------
MBX Region
---------------------------------
blu nam.ca.bay-area
apc nam.ca.bay-area
xyz nam.ca.bay-area
abc nam.tx.san-antonio
---------------------------------
Regional IPs
---------------------------------
nam.ca.bay-area
132.245.80.146
132.245.80.150
nam.tx.san-antonio
132.245.80.153
132.245.80.156
132.245.81.114

to:

{
    'appid': 'SAMPLEAPP',
    'ip': [
        '10.41.222.0/24 [0-65535]',
        '111.221.112.0/21 [1-65535]',
        '111.221.116.0/24 [1-65535]',
        '111.221.17.160/27 [1-65535]',
        '111.221.20.128/25 [0-65535]',
    ],
    'host': [
        '*.mail.apac.example.com',
        '*.example1.com',
        '*.example2.com',
        'example1.com',
    ],
    'geodns': {
        'nam.ca.bay-area': {
            'mbx': ['blu', 'apc', 'xyz'],
            'ip': ['132.245.80.146', '132.245.80.150'],
        },
        'nam.tx.san-antonio': {
            'mbx': ['abc'],
            'ip': [
                '132.245.80.153',
                '132.245.80.156',
                '132.245.81.114',
            ]
        },
    },
}

Parameters:	input – CLI output of saasinfo data type – string
Returns:	dictionary with saasinfo data as above