SSH Core Module

RadSSH Module Simplified Paramiko interface for managing clustered SSH interaction

class radssh.ssh.Chunker(grouping=10, delay=30)

Allow list of host connections to be chunkified into sublists

class radssh.ssh.Cluster(hostlist, auth=None, console=None, mux={}, defaults={}, commandline_options={})

SSH Cluster

close_connections()

Disconnect from all remote hosts

connection_summary()

Determine counts of various connection statuses

enable(enable_list=None)

Set active set of connections via list of fnmatch/IP patterns to limit run_command; pass in None to reset to enable all connections

locate(s)

Lookup cluster entry - keys may be netaddr.IPAddress, not string

log_result(logdir=None, command_header=True, encoding='UTF-8')

Save last_result content to a log directory - 1 file per host

multiplex(mux_command='echo /mnt/gluster-brick*')

Create a multiplex cluster based on the output of a command against the current cluster

prep_command(cmd, target)

Preprocess command line for target host execution (%ip%, %host%, etc)

reauth(user)

Attempt to reconnect and reauthenticate to any hosts in the cluster that are not already properly established

run_command(template)

Execute a command line (template) string across all enabled host connections

sftp(src, dst=None, attrs=None)

SFTP a file (put) to all nodes

status()

Return a combined list of connection status text messages

tunnel_connections(hostlist, jumpbox=None)

Create a cluster of tunneled connections through a jumpbox

update_connections()

Pull completed transport creations and save in connections dict

class radssh.ssh.CommandResult(**kwargs)

Generic object to save a bunch of fields

class radssh.ssh.Quota(defaults={})

Quota values for auto-termination of in-flight commands

radssh.ssh.close_connection(t, k, signoff='')

Close Paramiko transport connections

radssh.ssh.exec_command(host, t, cmd, quota, streamQ, encoding='UTF-8')

Run a command across a transport via exec_cmd. Capture stdout, stderr, and return code, streaming to an optional output queue

radssh.ssh.filter_tty_attrs(line)

Handle the attributes for colors, etc.

radssh.ssh.run_local_command(original_name, remote_hostname, port, remote_username, sshconfig)

Handle preparing command line to run on connecting to remote host. This includes doing possible substitutions that are not done by Paramiko’s ssh_config, as they involve connection specific values that are not known at the time of original lookup.

Shell Module

Python wrapper for parallel execution shell

* This module should be run, not imported *

Usage: `python -m radssh.shell host [...]`

Will read settings from /etc/radssh_config, and supplement with ~/.radssh_config. Settings may also be provided on the command line, using the form –keyword=value.

class radssh.shell.radssh_tab_handler(cluster, star)

Class wrapper for readline TAB key completion

radssh.shell.shell(cluster, logdir=None, playbackfile=None, defaults=None)

Very basic interactive shell

Plugins Module

RadSSH Plugins

Command line module to assist in installation and reporting info on available plugin modules. Also used by Shell API to manage the discovery and loading of plugin modules.

A RadSSH plugin module is a Python source file that can be dynamically imported at runtime by the RadSSH Shell. In order for the Shell to make use of a plugin module, the module should contain at least one of the following named objects:

  • A callable init() function
  • A callable lookup() function
  • A dict (or dict-like) object named star_commands

Init Function

If a module has an init() function, this will be called by the shell when the module is loaded. The shell will pass a limited number of keyword arguments, and for future/backward compatibility, the plugin’s init function should be defined as init(**kwargs) and permit the caller to pass in any superset of arguments beyond what is strictly necessary for the plugin’s initialization needs.

The current (API v1.0) list of arguments passed into a plugin init() call:
  • defaults: Dictionary of configuration settings {keyword: value}
  • auth: The shell’s AuthManager object
  • plugins: The shell’s list object of loaded plugin modules
  • star_commands: The shell’s dict object mapping *command to callable function

Lookup Function

If a module has a lookup() function, it may be called from the shell in an attempt to translate a symbolic name into a collection of zero or more host connections to add to the cluster. If the plugin can translate the given string, the lookup function should pass back an iterator object, otherwise the function should return None.

The iterator should yield a 3-tuple with the following elements:
  • Label: Typically the hostname, for display purposes in the shell
  • Host: A DNS resolvable host (or IP) to connect. Use None if Label is appropriate to use
  • Connection: An established socket-like connection to use, or None if RadSSH should initiate

For the baseline case, a tuple of (hostname, None, None) is suitable.

Star Commands

If a module has a dictionary object named ‘star_commands’, this mapping will be integrated into the RadSSH shell star_command mapping. The keys should be strings of the form ‘*command’, and the values should either be objects of type StarCommand, or plain callable functions that the shell will use to create StarCommand objects from (with defaults).

When the user enters ‘*command’ to the shell, the corresponding function is called, passing the following arguments:

  • cluster: the RadSSH Cluster object managed by the shell
  • logdir: the path to the RadSSH shell log directory
  • command_line: the entire command line text, including the *command and all embedded spaces
  • *args: The space-delimited arguments from the command line (spaces are stripped)

The *command routine is passed total control of the RadSSH shell execution process. It can make use of the Cluster object to perform remote command execution, file transfers, connections and disconnections, enables & disables, etc. It can also create, update, read, delete files in the log directory. It can also create a new Cluster object and pass it back as a return value, which will cause RadSSH to shift context to the new cluster for the remainder of the session.

class radssh.plugins.StarCommand(handler, synopsis=None, help_text=None, auto_help=True, min_args=0, max_args=None, version=None, tab_completion=None)

StarCommand Class Allow offloading of special help/synopsis text handling from a basic callable *command handler callable function. If no synopsis or help text is provided, the function docstring will be used. Help can be auto-invoked if help flags are discovered on the command line or if the parameter count is out of range.

radssh.plugins.discover_plugin(src)

Attempts to load a module. If successful, returns tuple (init, lookup, star_commands). If an exception occurs, translate to RuntimeWarning, and return (None, None, {}).

radssh.plugins.load_plugin(src)

Load a RadSSH Plugin module Returns successfully imported module object

Low Level Process

RadSSH Console

Handle output text streamed to a Queue to present on terminal.

Messages are expected to be tagged as to their origin, expected to be a pair (label, stderr), where label is typically a hostname and stderr is a boolean indicating if the message content came from stderr (highlight) or not.

class radssh.console.RadSSHConsole(q=None, formatter=<function colorizer>, retain_recent=0)

Combine a Queue object with a daemon thread that pulls message output from the queue and pretties it up for on screen display. When run in a terminal window, uses ANSI escape sequences to colorize output, and use the window/tab title for status messages.

console_thread()

Background-able thread to pull from outputQ and format and print to screen

message(message, label='CONSOLE')

Main thread can submit CONSOLE messages directly through instance

progress(s)

For progress-bar like output; no newlines

quiet(enable=True)

Set (or clear) console quietmode. Returns prior setting.

replay_recent(label)

Output the recent lines sent tagged from “label” - Used for Ctrl-C handler

status(message)

Set console (titlebar) status message

radssh.console.colorizer(tag, text)

Basic ANSI colorized output - host hash value map to 7-color palette, stderr bold

radssh.console.monochrome(tag, text)

Basic Formatter for plain (monochrome) output

Dispatcher Module

class radssh.dispatcher.Dispatcher(outQ=None, threadpool_size=100, dynamic_expansion=False)

Generic threaded queue job dispatcher

async_results(timeout=3)

Poll for results - can be used as iterator

start_threads(num=1)

Grow the threadpool by the requested size, up to limit threadpool_size, set in __init__()

terminate()

Clenup a Dispatcher as best as we can

class radssh.dispatcher.JobSummary(completed, job_id, result, start_time=None, **kwargs)

Dispatcher info returned from a submitted Job

exception radssh.dispatcher.UnfinishedJobs(remaining, total)

Exception raised by async_results() iterator when queue is stalled

radssh.dispatcher.generic_dispatch(inQ, outQ)

General purpose dispatch thread

StreamBuffer Module Class definition for converting a stream of input data into chunks, typically newline delimited, into a python queue object. Pushed data is acculumulated and delivered to the queue per selectable thresholds.

class radssh.streambuffer.StreamBuffer(queue=None, tag=None, delimiter='n', blocksize=1024, presplit=False, encoding='utf-8')

StreamBuffer Class

close()

Signal end of writes - flushes queue but saves position for further pulls

pull(size=0)

Non-queue access to accumulated data as bytes

push(data)

Appends data to buffer, and adds records (lines of text) to queue

Indices and tables