1pssh(1)                     General Commands Manual                    pssh(1)
2
3
4

NAME

6       pssh — parallel ssh program
7
8
9

SYNOPSIS

11       pssh  [-vAiIP] [-h hosts_file] [-H [user@]host[:port]] [-g pattern] [-l
12       user] [-p par] [-o outdir] [-e errdir] [-t timeout]  [-O  options]  [-x
13       args] [-X arg] command ...
14
15       pssh  -I  [-vAiIP] [-h hosts_file] [-H [user@]host[:port]] [-g pattern]
16       [-l user] [-p par] [-o outdir] [-e errdir] [-t  timeout]  [-O  options]
17       [-x args] [-X arg] [command ...]
18
19
20

DESCRIPTION

22       pssh  is  a program for executing ssh in parallel on a number of hosts.
23       It provides features such as sending input to  all  of  the  processes,
24       passing a password to ssh, saving output to files, and timing out.
25
26       The  PSSH_NODENUM,  PSSH_NUMNODES,  PSSH_HOST environment variables are
27       sent to the remote host.   The  PSSH_NODENUM  variable  is  assigned  a
28       unique number for each ssh connection, starting with 0 and counting up.
29       The PSSH_NUMNODES variable is assigned the total number of  node  being
30       used. The PSSH_HOST variable is assigned the name of the host as speci‐
31       fied in the hosts list.  Note that sshd drops environment variables  by
32       default, so sshd_config on the remote host must include the line:
33              AcceptEnv PSSH_NODENUM PSSH_NUMNODES PSSH_HOST
34
35

OPTIONS

37       -h host_file
38       --hosts host_file
39              Read hosts from the given host_file.  Lines in the host file are
40              of the form [user@]host[:port] and can include blank  lines  and
41              comments (lines beginning with "#").  If multiple host files are
42              given (the -h option is used more than once), then pssh  behaves
43              as  though these files were concatenated together.  If a host is
44              specified multiple times, then pssh will connect the given  num‐
45              ber of times.
46
47       -H     [user@]host[:port]
48       --host [user@]host[:port]
49       -H     "[user@]host[:port] [ [user@]host[:port ] ... ]"
50       --host "[user@]host[:port] [ [user@]host[:port ] ... ]"
51              Add  the  given  host strings to the list of hosts.  This option
52              may be given multiple times, and may be used in conjunction with
53              the -h option.
54
55       -g pattern
56       --host-glob pattern
57              Filter hosts with glob pattern pattern.  This uses the same syn‐
58              tax as shell globs. Make sure to quote the  pattern  to  prevent
59              shell from expanding it. Examples are "*web*" and "company_*".
60
61       -l user
62       --user user
63              Use  the given username as the default for any host entries that
64              don't specifically specify a user.
65
66       -p parallelism
67       --par parallelism
68              Use the given number as the maximum number of concurrent connec‐
69              tions.
70
71       -t timeout
72       --timeout timeout
73              Make  connections  time  out  after the given number of seconds.
74              With a value of 0, pssh will not timeout any connections.
75
76       -o outdir
77       --outdir outdir
78              Save standard output to files in the given directory.  Filenames
79              are of the form [user@]host[:port][.num] where the user and port
80              are only included for hosts that explicitly specify  them.   The
81              number is a counter that is incremented each time for hosts that
82              are specified more than once.
83
84       -e errdir
85       --errdir errdir
86              Save standard error to files in the given directory.   Filenames
87              are of the same form as with the -o option.
88
89       -x args
90       --extra-args args
91              Passes extra SSH command-line arguments (see the ssh(1) man page
92              for more information about SSH arguments).  This option  may  be
93              specified  multiple times.  The arguments are processed to split
94              on whitespace, protect text within quotes, and escape with back‐
95              slashes.   To pass arguments without such processing, use the -X
96              option instead.
97
98       -X arg
99       --extra-arg arg
100              Passes a single SSH command-line argument (see  the  ssh(1)  man
101              page  for  more information about SSH arguments).  Unlike the -x
102              option, no processing is performed on  the  argument,  including
103              word  splitting.   To  pass multiple command-line arguments, use
104              the option once for each argument.
105
106       -O options
107       --options options
108              SSH options in the format used in  the  SSH  configuration  file
109              (see the ssh_config(5) man page for more information).  This op‐
110              tion may be specified multiple times.
111
112       -A
113       --askpass
114              Prompt for a password and pass it to ssh.  The password  may  be
115              used  for either to unlock a key or for password authentication.
116              The password is transferred in a fairly secure manner (e.g.,  it
117              will  not  show up in argument lists).  However, be aware that a
118              root user on your system could potentially intercept  the  pass‐
119              word.
120
121       -i
122       --inline
123              Display  standard  output  and  standard error as each host com‐
124              pletes.
125
126       --inline-stdout
127              Display standard output (but not standard error)  as  each  host
128              completes.
129
130       -v
131       --verbose
132              Include error messages from ssh with the -i and -e options.
133
134       -I
135       --send-input
136              Read  input  and  send  to each ssh process.  Since ssh allows a
137              command script to be sent on standard input, the -I  option  may
138              be used in lieu of the command argument.
139
140       -P
141       --print
142              Display output as it arrives.  This option is of limited useful‐
143              ness because output from different hosts are interleaved.
144
145

EXAMPLES

147       Connect to host1 and host2, and print "hello, world" from each:
148              pssh -i -H "host1 host2" echo "hello, world"
149
150       Print "hello, world" from each host specified in the file hosts.txt:
151              pssh -i -h hosts.txt echo "hello, world"
152
153       Run a command as root with a prompt for the root password:
154              pssh -i -h hosts.txt -A -l root echo hi
155
156       Run a long command without timing out:
157              pssh -i -h hosts.txt -t 0 sleep 10000
158
159       If the file hosts.txt has a large number of entries, say 100, then  the
160       parallelism  option  may also be set to 100 to ensure that the commands
161       are run concurrently:
162              pssh -i -h hosts.txt -p 100 -t 0 sleep 10000
163
164       Run a command without checking or saving host keys:
165              pssh -i -H host1 -H host2  -x  "-O  StrictHostKeyChecking=no  -O
166              UserKnownHostsFile=/dev/null  -O GlobalKnownHostsFile=/dev/null"
167              echo hi
168
169       Print the node number for each connection (this will print  0,  1,  and
170       2):
171              pssh -i -H host1 -H host1 -H host2 'echo $PSSH_NODENUM'
172

TIPS

174       If you have a set of hosts that you connect to frequently with specific
175       options, it may be helpful to create an alias such as:
176              alias pssh_servers="pssh -h /path/to/server_list.txt -l root -A"
177
178       Note that when an ssh command is terminated, it does  not  kill  remote
179       processes  (OpenSSH bug #396 has been open since 2002).  One workaround
180       is to instruct ssh to allocate a pseudo-terminal, which makes it behave
181       more  like  a  normal  interactive ssh session.  To do this, use pssh's
182       "-x" option to pass "-tt" to ssh.  For example:
183              pssh -i -x "-tt" -h hosts.txt -t 10 sleep 1000
184       will ensure that all of the sleep commands will terminate (with SIGHUP)
185       after the 10 second timeout.
186
187       By default, ssh uses full buffering for non-interactive commands.  Line
188       buffering may be preferrable to full buffering if you intend to look at
189       the  files  in  an output directory as a command is running.  To switch
190       ssh to use line buffering, use its  "-tt"  option  (which  allocates  a
191       pseudo-terminal) using the "-x" option in pssh.
192
193       The  ssh_config  file can include an arbitrary number of Host sections.
194       Each host entry specifies ssh options which apply  only  to  the  given
195       host.   Host  definitions  can even behave like aliases if the HostName
196       option is included.  This ssh feature, in combination  with  pssh  host
197       files, provides a tremendous amount of flexibility.
198
199

EXIT STATUS

201       The exit status codes from pssh are as follows:
202
203       0      Success
204
205       1      Miscellaneous error
206
207       2      Syntax or usage error
208
209       3      At least one process was killed by a signal or timed out.
210
211       4      All  processes  completed, but at least one ssh process reported
212              an error (exit status 255).
213
214       5      There were no ssh errors, but at least one remote command had  a
215              non-zero exit status.
216
217

AUTHORS

219       Written  by  Brent  N. Chun <bnc@theether.org> and Andrew McNabb <amcn‐
220       abb@mcnabbs.org>.
221
222       https://github.com/lilydjwg/pssh
223
224

SEE ALSO

226       ssh(1), ssh_config(5), pscp(1), prsync(1), pslurp(1), pnuke(1),
227
228
229
230                               January 24, 2012                        pssh(1)
Impressum