Welcome to RadSSH’s documentation!¶
Contents:
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
-