gpMgmt/doc/gpssh_help

COMMAND NAME: gpssh

Provides ssh access to multiple hosts at once.


*****************************************************
SYNOPSIS
*****************************************************

gpssh { -f <hostfile_gpssh> | -h <hostname> [-h <hostname> ...] } 
[-u userid] [-s] [-v] [-e] [-d seconds] [-t multiplier] [<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 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.

If a user name is not specified in the host list 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.

*****************************************************
OPTIONS
*****************************************************

<bash_command>

 A bash shell command to execute on all hosts involved in this 
 session (optionally enclosed in quotes). If not specified, gpssh 
 will start 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 host name is required.
 The syntax of the host file is one host per line as follows:
  
  <hostname>


-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 cloudberry-env.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.


-u <userid>

 Specifies the userid for this SSH session. 


-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
executes 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 in the directory
gpssh uses the default values or the values set with the -d and -t
options. For information about the environment variable, see the
Apache Cloudberry Reference Guide.

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 = 3


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_retry = attempts

 A non-negative integer that specifies the maximum number of retry attempts
 that gpssh performs to try connecting to a Apache Cloudberry remote host. The
 default is 3. If the value is 0, gpssh returns an error if the initial
 connection attempt fails. This parameter cannot be configured with a
 command-line option.

 Increasing this value compensates for slow network performance or performance
 issues such as heavy CPU or I/O load on the segment host. 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


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


Execute 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'


*****************************************************
SEE ALSO
*****************************************************

gpssh-exkeys, gpscp