pssh
Run commands on multiple remote hosts
TLDR
Run a command on two hosts, and print its output on each server inline
Run a command and save the output to separate files
Run a command on multiple hosts, specified in a new-line separated file
Run a command as root (this asks for the root password)
Run a command with extra SSH arguments
Run a command limiting the number of parallel connections to 10
SYNOPSIS
pssh [options] [command [arg ...]]
Examples:
pssh -h /etc/pssh/hosts.txt -l root "uptime"
pssh -H "user1@host1" -H "host2" "ls -la /tmp"
PARAMETERS
-h FILE, --hosts FILE
Reads the list of target hosts from the specified FILE. Each line in the file should contain a single host entry, optionally prefixed with a username and port (e.g., user@host:port).
-H [USER@]HOST[:PORT], --host [USER@]HOST[:PORT]
Adds a single host to the list of targets. This option can be specified multiple times to target several hosts directly from the command line.
-l USER, --user USER
Specifies the username to use for SSH login on all remote hosts. Overrides any username specified in the host file or via -H.
-p NUM, --parallel NUM
Sets the maximum number of parallel SSH connections that pssh will attempt to establish simultaneously. The default value is 32.
-t SECONDS, --timeout SECONDS
Sets a timeout, in SECONDS, for each individual SSH connection and the execution of the remote command. If the command does not complete within this time, it is terminated.
-o DIR, --output-dir DIR
Saves the standard output (stdout) of each remote command to separate files within the specified DIRectory. Each file is named after the hostname.
-e DIR, --error-dir DIR
Saves the standard error (stderr) of each remote command to separate files within the specified DIRectory. Similar to -o, files are named after the hostname.
-i, --inline
Prints the standard output and standard error from remote commands to the local console immediately as they complete, interleaving results from different hosts.
-v, --verbose
Enables verbose output, providing more detailed information about the execution process, including connection attempts and command status.
-A, --askpass
Prompts the user for a password to use for SSH authentication. Useful when using password-based authentication instead of SSH keys.
-x ARGS, --extra-args ARGS
Passes additional arguments directly to the underlying ssh command for each connection (e.g., -x "-o StrictHostKeyChecking=no").
DESCRIPTION
pssh, or Parallel SSH, is a powerful command-line tool designed to execute commands on multiple remote hosts concurrently via SSH. It's an integral part of the pssh utilities package, which streamlines system administration tasks across a cluster of machines. Users can specify a list of target hosts either from a file or directly via command-line options. pssh then establishes parallel SSH connections to these hosts and runs the specified command, collecting and displaying the output. It offers robust options for controlling parallelism, setting timeouts, handling errors, and managing output redirection, making it highly efficient for tasks like deploying software, applying configuration changes, performing system audits, or monitoring across numerous servers simultaneously. Its primary goal is to significantly reduce manual effort and save time when managing large numbers of remote systems.
CAVEATS
When using pssh, ensure that SSH is properly configured on all target hosts and that appropriate authentication (e.g., SSH keys with an agent) is in place to avoid repeated password prompts. For large numbers of hosts, pssh can consume significant local resources (CPU, memory, file descriptors) depending on the --parallel setting. Care should be taken when executing commands that modify system state, as errors on a subset of hosts can lead to inconsistent configurations across the cluster. Output management can also be complex for many hosts; consider using --output-dir and --error-dir for detailed logging rather than relying solely on --inline.
HOST FILE FORMAT
The hosts file specified with -h or --hosts expects one host entry per line. Each entry can be in the format [user@]host[:port]. Blank lines and lines starting with a # character are treated as comments and ignored.
EXIT STATUS
pssh returns an exit status of 0 if all remote commands executed successfully and there were no internal pssh errors. A non-zero exit status indicates that one or more remote commands failed, or an error occurred during pssh's operation itself. This is crucial for scripting and error handling.
AUTHENTICATION
pssh leverages standard SSH authentication mechanisms. It will typically try SSH keys first (honoring ~/.ssh/config and ssh-agent), and if unsuccessful and -A is used, it will prompt for a password.
HISTORY
pssh is part of the pssh utilities suite, originally developed by Andrew McNabb. It emerged as a lightweight yet powerful solution for executing commands across multiple servers in parallel, bridging the gap between simple shell scripting with ssh loops and more comprehensive configuration management systems like Ansible or SaltStack. Its design focuses on simplicity, efficiency, and direct command execution, making it a popular choice for ad-hoc administration tasks and integration into larger automation scripts where full-fledged orchestration tools might be overkill.
SEE ALSO
ssh(1), pscp(1), prsync(1), pslurp(1), pnuke(1)