Polysh (formerly called Group Shell or gsh) is a remote shell multiplexer. It lets you control many remote shells at once in a single shell. Unlike other commands dispatchers, it is interactive, so shells spawned on the remote hosts are persistent. It requires only a SSH server on the remote hosts, or some other way to open a remote shell.
Python >= 3.6 is required.
Usage:
polysh [OPTIONS]... HOSTS...
The polysh prompt shows either ready (X)> or waiting (X/Y)>. The ready prompt means that all enabled remote shells are ready to receive commands and there are X such remote shells. Failing that, the waiting prompt is shown, meaning that X remote shells are not yet ready to receive commands. Either way, all the readline editing features like navigation in the history, searching in the history, and completion are available.
Commands prefixed by an exclamation mark are executed locally. Signals Ctrl-C and Ctrl-D are forwarded to the remote shells.
The prompt supports completion by pressing the Tab key. Completion results are taken from the command line history, paths from the local filesystem and commands from the user $PATH.
Hostnames with numbers can be generated by polysh using the <START-END> syntax. The generated numbers will be zero padded according to the number of zeroes in the START and END numbers.
- --version
- Show program`s version number and exit
- -h, --help
- Show the help message and exit
- --hosts-file=FILE
Read hostnames from given file, one per line
Hostnames are given on the command line, but they can also be read from files. The format is one hostname per line, # comments and blank lines are skipped.
- --command=CMD
Command to execute on the remote shells
This starts polysh in non-interactive mode. It will start the remote shells, send the command, print the output and exit when the command is completed on all remote shells. This is the same as piping a command on the standard input. Exit codes from the remote shells will be aggregated (taking the max) to form polysh's exit code.
- --ssh=SSH
Command to use for SSH
By default, exec ssh -oLogLevel=Quiet -t %(host)s %(port)s. polysh spawns ssh for each connection which may spawn your default login shell on the remote, but another shell command can be specified here. For example, with --ssh='usleep $((RANDOM*50)); exec ssh' a delay will be introduced to avoid all hosts accessing a NFS server at the same time. If the hostname should not be added at the end of the command, the macro %(host)s can be inserted where the hostname should be placed. Also, make sure the command you use launches a pty, this may need the -t option for ssh.
- -l, --line-buffering
Only print whole lines of remote output
By default, when a remote goes quiet with an unfinished line sitting in the read buffer, polysh prints it right away, so that partial output and interactive prompts are not withheld. The price is that a remote flushing its output in small pieces gets one prefixed line per piece:
10.92.255.20 : ge 10.92.255.20 : tractime
With this option polysh waits for the newline instead, and the above becomes a single 10.92.255.20 : getractime line. An unterminated last line is still printed when the remote goes away. This is mostly useful together with --prompt, as those remotes echo back what polysh sends them, a fragment at a time.
- --prompt=REGEX
Regex matching the prompt of a non POSIX shell remote
By default polysh sets PS1 on the remote shell to a generated marker, and also sends stty and other shell setup commands, so that it knows exactly when a remote is ready for the next command. Some remotes are not POSIX shells and would choke on that, for example the Dell iDRAC racadm>> shell. With --prompt='racadm>>' no shell initialization is sent at all, and polysh instead considers a remote ready as soon as this regex matches the end of its output. The regex is a Python regex, so a plain string works as long as it contains no regex metacharacter; trailing blanks after the prompt are ignored. The matched prompt is swallowed instead of being printed as remote output.
Since no stty -echo is sent either, such remotes usually echo back the commands polysh sends them, and those echoes show up in the output. They tend to arrive in fragments, so --line-buffering is recommended along with this option.
Note that control commands relying on shell features, such as :reset_prompt and :rename, are of no use with these remotes.
The same matching can be turned on and off during a session with the :prompt control command, which is handy when the remote is a normal shell that only later drops into something else.
- --user=USER
Remote user to log in as
When specified, polysh will ssh to USER@HOST instead of simply HOST.
- --no-color
Disable colored hostnames, enabled by default
When specified, polysh will not use tty colors for the hostname prefix.
- --password-file=FILE
Read a password from the specified file
- is the tty. This can be used when public key authentication is not available, either write the password in a file, or set FILE to - so that polysh will prompt for a password.
- --log-file=LOG_FILE
File to log each machine conversation
If specified, polysh will log all executed commands and their output in the file. The logging destination can be dynamically changed with the :set_log control command.
- --abort-errors
Abort if some shell fails to initialize
By default, polysh just logs an error when it cannot successfully open a remote shell. With this option, it exits with a failure.
- --debug
Print debugging information
Use this option to see exactly what is transferred between polysh and the remote shells. This option can be dynamically toggled using the :set_debug command in the control shell.
Control commands are special purpose commands prefixed by a colon and directed at polysh itself instead of the remote shells. These commands are:
- :add NAMES...
- Add one or many remote shells
- :chdir LOCAL_PATH
- Change the current directory of polysh (not the remote shells)
- :disable [SHELLS...]
Disable sending commands to remote shells
If the command would have no effect, it changes all other shells to the inverse enable value. That is, if you disable only already disabled shells, it will first enable all other shells. The special characters *, ?, and [] work as expected.
- :enable [SHELLS...]
- Enable sending commands to remote shells. If the command would have no effect, it changes all other shells to the inverse enable value. That is, if you enable only already enabled shells, it will first disable all other shells. The special characters *, ?, and [] work as expected.
- :export_vars
Export some environment variables on enabled remote shells
POLYSH_NR_SHELLS is the total number of enabled shells. POLYSH_RANK uniquely identifies each shell with a number between 0 and POLYSH_NR_SHELLS - 1. POLYSH_NAME is the hostname as specified on the command line and POLYSH_DISPLAY_NAME the hostname as displayed by :list (most of the time the same as POLYSH_NAME).
- :hide_password
Do not echo the next typed line
This is useful when entering password. If debugging or logging is enabled, it will be disabled to avoid displaying a password. Therefore, you will have to re-enable logging or debugging afterwards if need be.
- :list [SHELLS...]
List remote shells and their states
The output consists of: <hostname> <enabled?> <state>: <last printed line>. The special characters *, ?, and [] work as expected.
- :prompt [REGEX]
Change the prompt polysh waits for, on the fly
Same matching as the --prompt option, but applied to the running session. This is what to reach for when a normal remote shell drops into something else mid-session, for example after typing racadm: polysh is then stuck in waiting, and :prompt racadm>> gets it back to ready. With no argument, or with an empty one, polysh goes back to setting PS1 on the remote shells itself and re-sends its own shell initialization. An invalid regex is reported and leaves the current setting alone.
- :purge [SHELLS...]
Delete disabled remote shells
This helps to have a shorter list. The special characters *, ?, and [] work as expected.
- :quit
- Quit polysh
- :reconnect [SHELLS...]
Try to reconnect to disconnected remote shells
The special characters *, ?, and [] work as expected.
- :rename [NEW_NAME]
Rename all enabled remote shells with the argument
The argument will be shell expanded on the remote processes. With no argument, the original hostname will be restored as the displayed name.
- :reset_prompt [SHELLS...]
Change the prompt to be recognized by polysh
The special characters *, ?, and [] work as expected.
- :send_ctrl LETTER [SHELLS...]
Send a control character to remote shells
The first argument is the control character to send, either a letter or one of
@ [ \ ] ^ _, so :send_ctrl c sends Ctrl-C and :send_ctrl ` sends Ctrl-. Note that Ctrl-C and Ctrl-can also be sent simply by typing them. Ctrl-Z is not forwarded, it suspends `polysh itself. The remaining optional arguments are the destination shells. The special characters *, ?, and [] work as expected.- :set_debug y|n [SHELLS...]
Enable or disable debugging output for remote shells
The first argument is y to enable the debugging output, n to disable it. The remaining optional arguments are the selected shells. The special characters *, ?, and [] work as expected.
- :set_log [LOCAL_PATH]
Duplicate every console I/O into the given local file
If LOCAL_PATH is not given, restore the default behaviour of not logging.
- :show_read_buffer [SHELLS...]
Print the data read by remote shells
The special characters *, ?, and [] work as expected.
The tool is authored by Guillaume Chazarain <guichaz@gmail.com>. The first version released in 2006. It has been maintained by InnoGames GmbH since 2018.