--- title: "gpssh" source: https://cloudberry.apache.org/docs/sys-utilities/gpssh --- # gpssh Provides SSH access to multiple hosts at once. ## Synopsis ```shell gpssh { -f | - h [-h ...] } [-s] [-e] [-d ] [-t ] [-v] [] 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](#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. ```conf [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 Apache Cloudberry 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`: ```shell $ gpssh -f hostfile_gpssh ``` At the `gpssh` interactive command prompt, run a shell command on all the hosts involved in this session. ```shell => ls -a /data/primary/* ``` Exit an interactive session: ```shell => 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`: ```shell $ gpssh -h sdw1 -h sdw2 -v -e < command_file ``` Run single commands in non-interactive mode on hosts `sdw2` and `localhost`: ```shell $ 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' ``` ## See also [gpssh-exkeys](/docs/sys-utilities/gpssh-exkeys.md), [gpsync](/docs/sys-utilities/gpsync.md)