gpssh
Provides SSH access to multiple hosts at once.
Synopsis
gpssh { -f <hostfile_gpssh> | - h <hostname> [-h <hostname> ...] } [-s] [-e]
[-d <seconds>] [-t <multiplier>] [-v]
[<bash_command>]
gpssh -?
gpssh --version
Description
The gpssh utility allows you to run bash shell commands on multiple hosts at once using SSH (secure shell). You can run a single command by specifying it on the command-line, or omit the command to enter into an interactive command-line session.
To specify the hosts involved in the SSH session, use the -f option to specify a file containing a list of host names, or use the -h option to name single host names on the command-line. At least one host name (-h) or a host file (-f) is required. Note that the current host is not included in the session by default — to include the local host, you must explicitly declare it in the list of hosts involved in the session.
Before using gpssh, you must have a trusted host setup between the hosts involved in the SSH session. You can use the utility gpssh-exkeys to update the known host files and exchange public keys between hosts if you have not done so already.
If you do not specify a command on the command-line, gpssh will go into interactive mode. At the gpssh command prompt (=>), you can enter a command as you would in a regular bash terminal command-line, and the command will be run on all hosts involved in the session. To end an interactive session, press CTRL+D on the keyboard or type exit or quit.
If a user name is not specified in the host file, gpssh will run commands as the currently logged in user. To determine the currently logged in user, do a whoami command. By default, gpssh goes to $HOME of the session user on the remote hosts after login. To ensure commands are run correctly on all remote hosts, you should always enter absolute paths.
If you encounter network timeout problems when using gpssh, you can use -d and -t options or set parameters in the gpssh.conf file to control the timing that gpssh uses when validating the initial ssh connection. For information about the configuration file, see gpssh configuration file.
Options
bash_command
A bash shell command to run on all hosts involved in this session (optionally enclosed in quotes). If not specified, gpssh starts an interactive session.
-d (delay) seconds
Optional. Specifies the time, in seconds, to wait at the start of a gpssh interaction with ssh. Default is 0.05. This option overrides the delaybeforesend value that is specified in the gpssh.conf configuration file.
Increasing this value can cause a long wait time during gpssh startup.
-e (echo)
Optional. Echoes the commands passed to each host and their resulting output while running in non-interactive mode.
-f hostfile_gpssh
Specifies the name of a file that contains a list of hosts that will participate in this SSH session. The syntax of the host file is one host per line.
-h hostname
Specifies a single host name that will participate in this SSH session. You can use the -h option multiple times to specify multiple host names.
-s
Optional. If specified, before running any commands on the target host, gpssh sources the file greenplum_path.sh in the directory specified by the $GPHOME environment variable.
This option is valid for both interactive mode and single command mode.
-t multiplier
Optional. A decimal number greater than 0 (zero) that is the multiplier for the timeout that gpssh uses when validating the ssh prompt. Default is 1. This option overrides the prompt_validation_timeout value that is specified in the gpssh.conf configuration file.
Increasing this value has a small impact during gpssh startup.
-v (verbose mode)
Optional. Reports additional messages in addition to the command output when running in non-interactive mode.
--version
Displays the version of this utility.
-? (help)
Displays the online help.
gpssh configuration file
The gpssh.conf file contains parameters that let you adjust the timing that gpssh uses when validating the initial ssh connection. These parameters affect the network connection before the gpssh session runs commands with ssh. The location of the file is specified by the environment variable COORDINATOR_DATA_DIRECTORY. If the environment variable is not defined or the gpssh.conf file does not exist, gpssh uses the default values or the values set with the -d and -t options.
The gpssh.conf file is a text file that consists of a [gpssh] section and parameters. On a line, the # (pound sign) indicates the start of a comment. This is an example gpssh.conf file.
[gpssh]
delaybeforesend = 0.05
prompt_validation_timeout = 1.0
sync_retries = 5
These are the gpssh.conf parameters.
delaybeforesend = seconds
Specifies the time, in seconds, to wait at the start of a gpssh interaction with ssh. Default is 0.05. Increasing this value can cause a long wait time during gpssh startup. The -d option overrides this parameter.
prompt_validation_timeout = multiplier
A decimal number greater than 0 (zero) that is the multiplier for the timeout that gpssh uses when validating the ssh prompt. Increasing this value has a small impact during gpssh startup. Default is 1. The -t option overrides this parameter.
sync_retries = attempts
A non-negative integer that specifies the maximum number of times that gpssh attempts to connect to a remote Cloudberry Database host. The default is 3. If the value is 0, gpssh returns an error if the initial connection attempt fails. Increasing the number of attempts also increases the time between retry attempts. This parameter cannot be configured with a command-line option.
The -t option also affects the time between retry attempts.
Increasing this value can compensate for slow network performance or segment host performance issues such as heavy CPU or I/O load. However, when a connection cannot be established, an increased value also increases the delay when an error is returned.
Examples
Start an interactive group SSH session with all hosts listed in the file hostfile_gpssh:
$ gpssh -f hostfile_gpssh
At the gpssh interactive command prompt, run a shell command on all the hosts involved in this session.
=> ls -a /data/primary/*
Exit an interactive session:
=> exit
=> quit
Start a non-interactive group SSH session with the hosts named sdw1 and sdw2 and pass a file containing several commands named command_file to gpssh:
$ gpssh -h sdw1 -h sdw2 -v -e < command_file
Run single commands in non-interactive mode on hosts sdw2 and localhost:
$ gpssh -h sdw2 -h localhost -v -e 'ls -a /data/primary/*'
$ gpssh -h sdw2 -h localhost -v -e 'echo $GPHOME'
$ gpssh -h sdw2 -h localhost -v -e 'ls -1 | wc -l'
