base.py

Bladerunner provides a method of pushing changes or running audits on groups of similar hosts over SSH using pexpect (http://pexpect.sourceforge.net). Can be extended to use an intermediary host if there are networking restrictions.

This file is part of Bladerunner.

Copyright (c) 2014, Activision Publishing, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Activision Publishing, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

class bladerunner.base.Bladerunner(options=None)

Main logic for the serial execution of commands on hosts.

Initialized by a dictionary with the following optional keys (defaults):

username: string username (None/current user)
password: string plain text password, if required (None)
ssh_key: string non-default ssh key file location (None)
delay: integer in seconds to pause between servers (None)
extra_prompts: list of strings of additional expect prompts ([])
width: integer terminal width for output, or it uses all (None/guess)
jump_host: string hostname of intermediary host (None)
jump_user: alternate username for jump_host (None)
jump_password: alternate password for jump_host (None)
jump_port: SSH port for jump_host (22)
second_password: an additional different password for commands (None)
password_safety: check if the first login succeeds first (False)
port: SSH port for the servers (22)
cmd_timeout: integer in seconds to wait for commands (20)
timeout: integer in seconds to wait to connect (20)
threads: integer number of parallel threads to run (100)
style: integer for outputting. Between 0-3 are pretty, or CSV (0)
csv_char: string character to use for CSV results (",")
progressbar: boolean to declare if we want a progress display (False)
unix_line_endings: force sending LF as line endings for commands
windows_line_endings: force sending CRLF as line endings for commands

close(sshc, terminate)

Closes a connection object.

Args:

sshc: the pexpect object to close
terminate: a boolean value to terminate all connections or not

Returns:

None: the sshc will be at the jumpbox, or the connection is closed

connect(target, username, password, port)

Connects to a server, maybe from another server.

Args:

target: the hostname, as a string
username: the user we are connecting as
password: list or string plain text password(s) to try
port: ssh port number, as integer

Returns:

a pexpect object that can be passed back here or to send_commands()

end_interactive(hosts=None)

Ends an interactive stored session.

Args:

hosts: optional string or list of hostnames to end, or None for all

interactive(server, connect=True)

Builds a BladerunnerInteractive version of this instance for a host.

Args:

server: string name or IP to connect interactively to connect: boolean, used to intially connect at this time or later

Returns:

BladerunnerInteractive object, connected if connect is True

login(sshc, password, login_response)

Internal method for logging in, used by connect/_multipass.

Args:

sshc: the pexpect object
password: plain text password to send
login_response: the pexpect return status integer

Returns:

a tuple of the connection object and error code

run(commands=None, servers=None, commands_on_servers=None)

Executes commands on servers.

Args:

commands: a list of strings of commands to run
servers: a list of strings of hostnames
commands_on_servers: an optional dictionary used when providing
                     unique lists of commands per server

Returns:

a list of dictionaries with two keys: name, and results. results is a list of tuples of commands issued and their replies.

run_interactive(command, hosts=None, print_results=True)

Runs a single command interactively on a list of hostnames.

Note:

the hosts kwarg can be omitted after the first run or if you call setup_interactive before calling this method

Args:

command: string command to send
hosts: string or list of hostnames to add to the interactive list
print_results: boolean to print the results or return a dict

Returns:

None, or a dictionary of {host: result}

run_interactive_function(function, hosts=None)

Runs a function defined by the user over a list of hosts.

The function made can contain logic within to send a different set of commands based on the output of earlier ones issued.

The results returned are in the structure you decide in your own function. If you do not return anything, this function will also return None. The single argument that you are passed in your function will be a BladerunnerInteractive object inialized for one of the hosts in the list provided. Order of execution is not guarenteed.

Note also that the hosts kwarg is only required for the first run of this function. Further runs will reuse the same interactive session(s).

Args:

function: a function to call with a BladerunnerInteractive object
hosts: list of hosts to run the function with

Returns:

list of returns from the function calls, or None

run_threaded(commands=None, servers=None, commands_on_servers=None, callback=None)

Non-blocking call which creates and starts a thread for self.run().

Args:

commands: a list of strings of commands to run
servers: a list of strings of hostnames
commands_on_servers: an optional dictionary used when providing
                     unique lists of commands per server
callback: function that will receive results when run is finished

Returns:

the started thread object which is running commands on servers

send_commands(server, hostname)

Executes the commands on a pexpect object.

Args:

server: the pexpect host object
hostname: the string hostname of the server

Returns:

a dictionary with two keys:

name: string of the server's hostname
results: a list of tuples with each command and its result

send_interrupt(sshc)

Sends ^c and pushes pexpect forward on the object.

Args:

sshc: the pexpect object

Returns:

None: the sshc maintains its state and should be ready for use

setup_interactive(hosts, connect=True)

Initializes a list of hosts to be used interactively.

Args:

hosts: list of hostnames to connect to for interative use later connect: boolean used to make the initial connection now or later