PSSH Command in Linux: Parallel SSH Examples, Syntax & Cheat Sheet

PSSH (Parallel SSH) allows you to execute commands on multiple Linux servers simultaneously from a single node. It is widely used by system administrators and DevOps engineers to automate tasks like monitoring, deployments, and troubleshooting across clusters.

In this guide, you will learn practical PSSH command examples, key options, and real-world use cases to efficiently manage multiple servers in parallel.

PSSH Syntax and Quick Cheat Sheet

Basic Syntax

pssh [options] -h hosts.txt command

Common PSSH Options Reference

Run Commands on Multiple Servers

Using host file

You can store multiple hosts in a file and use it with PSSH to execute commands on all servers at once.

cat hosts.txt
root@10.43.138.2:22
root@10.43.138.3:22
root@10.43.138.9:22

Run a command on all hosts:

pssh -h /tmp/host_file.txt date

Output:

[1] 19:29:01 [SUCCESS] root@10.43.138.3:22
[2] 19:29:01 [SUCCESS] root@10.43.138.2:22
[3] 19:29:01 [SUCCESS] root@10.43.138.9:22

Using inline host list

If you have a small number of servers, you can pass them directly using -H.

pssh -H "server1 server2 server3" -l <user> <command>

Example:

pssh -H "10.43.138.2 10.43.138.3 10.43.138.9" -l root date

Output:

[1] 19:39:00 [SUCCESS] 10.43.138.3
[2] 19:39:00 [SUCCESS] 10.43.138.2
[3] 19:39:00 [SUCCESS] 10.43.138.9

Display output per host

By default, PSSH only shows status. Use -i to print output from each host.

pssh -i -h hosts.txt "hostname && uptime"

Control Execution and Performance

Limit parallel connections (-p)

Control how many servers are accessed simultaneously. This is useful when working with large clusters to avoid overloading your network or the control node.

pssh -p 5 -h hosts.txt uptime

The -p option limits the number of parallel SSH connections. PSSH will:

• Start connections to the first 5 hosts from the list
• Wait for any one of them to finish
• As soon as a slot is free, it picks the next host from the list
• Continue this process until all hosts are processed

So if you have 20 hosts and use -p 5, PSSH will execute commands in batches of 5, but not strictly sequential batches — it dynamically schedules the next host as soon as any running task completes.

Set timeout (-t)

Set a timeout for each host connection to avoid hanging commands.

pssh -t 10 -h hosts.txt uptime

Run Commands and Scripts

Execute inline commands

Run one-liner commands across all servers.

pssh -h hosts.txt -l root "df -h"

Example: Restart a service on all servers

pssh -h hosts.txt -l root "systemctl restart nginx"

Run script on multiple servers

Execute a script across multiple servers.

pssh -h hosts.txt -l root "bash -s" < script.sh

Alternatively, if script is already present on remote hosts:

pssh -h hosts.txt -l root "chmod +x /tmp/script.sh && /tmp/script.sh"

Capture Output and Debug Failures

Save stdout and stderr

When running PSSH commands on multiple servers, it is important to capture output for analysis and troubleshooting. You can store standard output and error logs separately for each host.

pssh -h hosts.txt -o /tmp/out -e /tmp/err "df -h"

This helps in debugging issues across multiple servers and is useful for automation scripts where logs need to be analyzed later.

Identify failed hosts

PSSH provides exit status per host, which can be used to identify failed executions. Commands returning non-zero exit codes indicate failure.

pssh -i -h hosts.txt "systemctl status nginx"

Look for [FAILURE] in output to quickly detect problematic servers when running parallel SSH commands.

File Transfer Across Servers

Copy files using pscp

Use pscp to copy files to multiple Linux servers in parallel. This is useful for deploying scripts or configuration files.

pscp -h hosts.txt /tmp/script.sh /tmp/

This allows you to distribute files across servers efficiently using parallel SSH.

Sync directories using prsync

Use prsync to synchronize directories across multiple servers, similar to rsync but in parallel.

prsync -h hosts.txt /local/dir /remote/dir

This is commonly used in DevOps workflows for deploying applications or syncing configuration data.

Pass Multiple SSH Options with PSSH

Pass multiple SSH options using -x

PSSH allows you to pass additional SSH options using the -x flag. This is useful when you need to customize SSH behavior such as disabling host key checking, setting authentication methods, or tuning connection parameters.

pssh -h hosts.txt -l root -x "-o StrictHostKeyChecking=no -o ConnectTimeout=5" hostname

You can pass multiple SSH options inside quotes. These options are forwarded to the underlying ssh command.

Common use cases include:

• Disabling host key verification for automation
• Setting connection timeout
• Forcing specific authentication methods
• Disabling GSSAPI authentication to speed up login

Example with multiple SSH options:

pssh -h hosts.txt -l root -x "-q -o StrictHostKeyChecking=no -o GSSAPIAuthentication=no -o PreferredAuthentications=publickey" uptime

Difference between -x and -X

• -x → Splits arguments on whitespace and passes them to SSH
• -X → Passes arguments as-is without splitting

Example:

pssh -h hosts.txt -X "-tt" uptime

Use -X when you want to pass raw SSH flags exactly as written.

How to get list of supported SSH options

PSSH itself uses the standard OpenSSH client, so all supported options come from the ssh command.

To view available SSH options:

ssh -h

For detailed explanation of all options:

man ssh

You can also check SSH configuration options:

man ssh_config

Any option supported by ssh (such as -o, -p, -i, etc.) can be passed through PSSH using -x or -X.

Run PSSH Without Password

Quick SSH key setup

To run PSSH without password prompts, configure SSH key-based authentication between servers.

ssh-keygen -t rsa -b 4096
ssh-copy-id user@server

This enables secure and automated access across multiple Linux servers.

Execute without password

Once SSH keys are configured, you can execute PSSH commands without entering a password.

pssh -h hosts.txt -l user uptime

This is essential for automation, scripting, and managing large-scale server environments.

Get Success and Failed Hosts from PSSH Execution

When running PSSH across multiple servers, the tool provides a combined output, but it does not directly give a clean list of successful and failed hosts.

To solve this, you can use -o (stdout) and -e (stderr) directories and process the results using a simple script.

We can run PSSH with output directories:

OUT_DIR=$(mktemp -d /tmp/pssh_out.XXX)
ERR_DIR=$(mktemp -d /tmp/pssh_err.XXX)

pssh -h hosts.txt -l root -o "$OUT_DIR" -e "$ERR_DIR" "uptime"

Simple script to identify success and failed hosts

#!/bin/bash

OUT_DIR=$1
ERR_DIR=$2

success_hosts=""
failed_hosts=""

for host_file in "$ERR_DIR"/*; do
    host=$(basename "$host_file")

    # If error file is not empty → failure
    if [ -s "$ERR_DIR/$host" ]; then
        failed_hosts="$failed_hosts $host"
    else
        success_hosts="$success_hosts $host"
    fi
done

echo ""
echo "======================"
echo "PSSH EXECUTION SUMMARY"
echo "======================"
echo "Success Hosts: $success_hosts"
echo "Failed Hosts : $failed_hosts"
echo ""

Execute the script

./pssh_summary.sh "$OUT_DIR" "$ERR_DIR"

Output:

======================
PSSH EXECUTION SUMMARY
======================
Success Hosts: server1 server2
Failed Hosts : server3

How this works

• PSSH creates one file per host in both output directories
• If a command fails, the error is written to the corresponding file in ERR_DIR
• If the error file is empty → command succeeded
• If the error file contains data → command failed

Detect failure using exit codes or custom error message

You can also explicitly mark failures in your command:

pssh -h hosts.txt -l root -o "$OUT_DIR" -e "$ERR_DIR" "your_command || echo ERROR"

Then enhance detection:

grep -q ERROR "$OUT_DIR/$host"

Troubleshooting PSSH Issues

Permission denied errors

If you encounter Permission denied (publickey) errors, ensure SSH keys are correctly configured and permissions are set properly.

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Also verify that the correct user and key are being used for authentication.

SSH connection issues

Connection problems may occur due to firewall rules, DNS issues, or SSH configuration.

pssh -h hosts.txt -l user -x "-o ConnectTimeout=5" hostname

You can also disable strict host key checking if needed:

pssh -h hosts.txt -x "-o StrictHostKeyChecking=no" hostname

These steps help resolve common issues when using PSSH for parallel SSH execution across servers.

Summary

PSSH (Parallel SSH) is a powerful tool for executing commands across multiple Linux servers simultaneously, making it ideal for system administrators and DevOps engineers managing large infrastructures.

In this guide, you learned how to:

• Run commands on multiple servers using host files and inline lists
• Control parallel execution and optimize performance
• Capture output and debug failures using stdout and stderr
• Transfer files using pscp and sync directories with prsync
• Use SSH key-based authentication to avoid password prompts
• Pass advanced SSH options for customized connections
• Identify successful and failed hosts using automation scripts

By combining PSSH with simple shell scripting, you can build efficient automation workflows, reduce manual effort, and improve operational reliability across distributed systems.

Official Documentation

• PSSH Manual Page (linux.die.net)
• PSSH Debian Man Page
• OpenSSH ssh Manual
• SSH Configuration Options (ssh_config)