gpssh

    Description

    The utility allows you to run bash shell commands on multiple hosts at once using SSH (secure shell). You can execute 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 executed 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 execute 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 executed 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.

    bash_command

    A bash shell command to execute 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 . 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

    -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 executing 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 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 file.

    1. [gpssh]
    2. prompt_validation_timeout = 1.0
    3. 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 Greenplum 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 retuned.

    Start an interactive group SSH session with all hosts listed in the file hostfile_gpssh:

    At the gpssh interactive command prompt, run a shell command on all the hosts involved in this session.

    1. => ls -a /data/primary/*

    Exit an interactive session:

    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:

      See Also

      , gpscp