Added the :print_read_buffer control command to see what gsh just read

[polysh.git] / gsh.1

.TH "gsh" "1" "0.3" "Guillaume Chazarain" "Remote shells"
.SH "NAME"
gsh \- Group Shell
.SH "SYNOPSIS"
\fBgsh\fR [OPTIONS]... HOSTS...
.SH "DESCRIPTION"
\fIgsh\fR spawns many remote shells at once and allows to manage them in a single interface.
.SH "PROMPTS"
The \fIgsh\fR 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 like Ctrl\-C and Ctrl\-Z sent to \fIgsh\fR are forwarded to the remote shells.
.SH "COMPLETION"
The \fIgsh\fR prompt supports completion by pressing the Tab key. Completion results are taken from the command line history, absolute paths from the local filesystem and commands from the user $PATH.
.SH "HOST NAMES EXPANSION"
Host names with numbers can be generated by gsh using the <START\-END> syntax. The generated numbers will be zero padded according to the number of zeroes in the START and END numbers.
.SH "OPTIONS"
.TP 
\fB\-\-version\fR
Show program's version number and exit.
.TP 
\fB\-h, \-\-help\fR
Show the help message and exit.
.TP 
\fB\-\-hosts\-file=FILE\fR
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.
.TP 
\fB\-\-command=CMD\fR
Command to execute on the remote shells. This starts \fIgsh\fR 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.
.TP 
\fB\-\-ssh=SSH\fR
Ssh command to use [ssh]. By default, \fIgsh\fR spawns remote shells using the ssh command, 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 launchs a pty, this may need the \-t option for ssh.
.TP 
\fB\-\-log\-file=LOG_FILE\fR
File to log each machine conversation [none]. If specified, \fIgsh\fR will log all executed commands and their output in the file. The logging destination can be dynamically changed with the :log_output control command.
.TP 
\fB\-\-abort\-errors\fR
Abort if some shell fails to initialize [ignore]. By default, \fIgsh\fR just logs an error when it cannot succesfully open a remote shell. With this option, it exits with a failure.
.TP 
\fB\-\-debug\fR
Print debugging information. Use this option to see exactly what is transferred between \fIgsh\fR and the remote shells. This option can be dynamically toggled using the set_debug command in the control shell.
.SH "CONTROL COMMANDS"
Control commands are special purpose commands prefixed by a colon and directed at \fIgsh\fR itself instead of the remote shells. These commands are:
\" BEGIN AUTO-GENERATED CONTROL COMMANDS DOCUMENTATION
.TP
\fB:add NAMES...\fR
Add one or many remote shells.
.TP
\fB:chdir PATH\fR
Change the current directory of \fIgsh\fR (not the remote shells).
.TP
\fB:disable [SHELLS...]\fR
Disable sending commands to remote shells. The special characters * ? and [] work as expected.
.TP
\fB:enable [SHELLS...]\fR
Enable sending commands to remote shells. The special characters * ? and [] work as expected.
.TP
\fB:export_rank\fR
Set GSH_RANK and GSH_NR_SHELLS on enabled remote shells. The GSH_RANK shell variable uniquely identifies each shell with a number between 0 and GSH_NR_SHELLS - 1. GSH_NR_SHELLS is the total number of enabled shells.
.TP
\fB:help [COMMAND]\fR
List control commands or show their documentations.
.TP
\fB:hide_password\fR
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.
.TP
\fB:list [SHELLS...]\fR
List remote shells and their states. The special characters * ? and [] work as expected.
.TP
\fB:log_output [PATH]\fR
Duplicate every console output into the given local file. If PATH is not given, restore the default behaviour of not logging the output.
.TP
\fB:print_read_buffer [SHELLS...]\fR
Print the data read by remote shells. The special characters * ? and [] work as expected.
.TP
\fB:purge [SHELLS...]\fR
Delete disabled remote shells. This helps to have a shorter list. The special characters * ? and [] work as expected.
.TP
\fB:quit\fR
Quit \fIgsh\fR.
.TP
\fB:reconnect [SHELLS...]\fR
Try to reconnect to disconnected remote shells. The special characters * ? and [] work as expected.
.TP
\fB:rename [NEW_NAME]\fR
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.
.TP
\fB:replicate SHELL:path\fR
Copy a path from one remote shell to all others
.TP
\fB:reset_prompt [SHELLS...]\fR
Change the prompt to be recognized by \fIgsh\fR. The special characters * ? and [] work as expected.
.TP
\fB:send_ctrl LETTER [SHELLS...]\fR
Send a control character to remote shells. The first argument is the control character to send: c, d or z. The remaining optional arguments are the destination shells. The special characters * ? and [] work as expected.
.TP
\fB:set_debug y|n [SHELLS...]\fR
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.
\" END AUTO-GENERATED CONTROL COMMANDS DOCUMENTATION
.SH "AUTHOR"
Guillaume Chazarain <guichaz@gmail.com>
.br 
See http://guichaz.free.fr/gsh