1pssh(1) General Commands Manual pssh(1)
2
6 pssh — parallel ssh program
7
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 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
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 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
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 -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 -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 -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 -p parallelism
67 --par parallelism
68 Use the given number as the maximum number of concurrent connec‐
69 tions.
70 -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 -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 -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 -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 -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 -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 -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 -i
122 --inline
123 Display standard output and standard error as each host com‐
124 pletes.
125 --inline-stdout
127 Display standard output (but not standard error) as each host
128 completes.
129 -v
131 --verbose
132 Include error messages from ssh with the -i and -e options.
133 -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 -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
147 Connect to host1 and host2, and print "hello, world" from each:
148 pssh -i -H "host1 host2" echo "hello, world"
149 Print "hello, world" from each host specified in the file hosts.txt:
151 pssh -i -h hosts.txt echo "hello, world"
152 Run a command as root with a prompt for the root password:
154 pssh -i -h hosts.txt -A -l root echo hi
155 Run a long command without timing out:
157 pssh -i -h hosts.txt -t 0 sleep 10000
158 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 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 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
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 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 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 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
201 The exit status codes from pssh are as follows:
202 0 Success
204 1 Miscellaneous error
206 2 Syntax or usage error
208 3 At least one process was killed by a signal or timed out.
210 4 All processes completed, but at least one ssh process reported
212 an error (exit status 255).
213 5 There were no ssh errors, but at least one remote command had a
215 non-zero exit status.
216
219 Written by Brent N. Chun <bnc@theether.org> and Andrew McNabb <amcn‐
220 abb@mcnabbs.org>.
221 https://github.com/lilydjwg/pssh
223
226 ssh(1), ssh_config(5), pscp(1), prsync(1), pslurp(1), pnuke(1),
227 January 24, 2012 pssh(1)