SSH Connector

The SSH connector is pyinfra’s default connector for connecting to remote hosts using SSH. It uses Paramiko for SSH communication and supports various authentication methods.

Overview

The SSH connector is used by default for all hosts unless another connector is specified:

# These are identical
pyinfra my-host.net ...
pyinfra @ssh/my-host.net ...

Connection Data

Configure SSH connection using inventory data:

str

SSH hostname or IP address to connect to.

int

default:22

SSH port number.

str

SSH username for authentication.

str

SSH password for authentication (not recommended, use keys instead).

str

Path to SSH private key file.

str

Password for encrypted SSH private key.

bool

default:true

Whether to use SSH agent for authentication.

bool

default:true

Whether to search for SSH keys in standard locations.

bool

default:false

Whether to enable SSH agent forwarding.

str

Path to SSH config file.

str

Path to SSH known_hosts file.

str

default:"accept-new"

Host key checking mode: accept-new, yes, or no.

dict

Additional keyword arguments passed to Paramiko’s SSHClient.connect().

int

default:0

Number of connection retry attempts.

float

Minimum delay between retries (seconds).

float

Maximum delay between retries (seconds).

str

default:"sftp"

Protocol for file transfers: sftp or scp.

Inventory Examples

Single Host with SSH Forward Agent

# inventory.py
hosts = [
    ("my-host.net", {"ssh_forward_agent": True}),
]

Multiple Hosts with Shared SSH User

# inventory.py
hosts = (
    ["host1.example.com", "host2.example.com"],
    {"ssh_user": "deploy"},
)

Multiple Hosts with Different Users

# inventory.py
hosts = [
    ("host1.example.com", {"ssh_user": "ubuntu"}),
    ("host2.example.com", {"ssh_user": "admin"}),
    ("host3.example.com", {"ssh_user": "centos"}),
]

Using SSH Config File

# inventory.py
hosts = [
    ("host1", {"ssh_config_file": "~/.ssh/config"}),
]

With ~/.ssh/config:

Host host1
    HostName 192.168.1.100
    User deploy
    Port 2222
    IdentityFile ~/.ssh/deploy_key

Custom SSH Port and Key

# inventory.py
hosts = [
    ("my-host.net", {
        "ssh_port": 2222,
        "ssh_user": "deploy",
        "ssh_key": "~/.ssh/deploy_key",
    }),
]

Connection Retries

# inventory.py
hosts = [
    ("unreliable-host.net", {
        "ssh_connect_retries": 3,
        "ssh_connect_retry_min_delay": 1.0,
        "ssh_connect_retry_max_delay": 5.0,
    }),
]

Using SCP Instead of SFTP

# inventory.py
hosts = [
    ("legacy-host.net", {
        "ssh_file_transfer_protocol": "scp",
    }),
]

Authentication Methods

SSH Agent (Recommended)

Use SSH agent for secure key management:

# Start SSH agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

# Run pyinfra (will use agent)
pyinfra inventory.py deploy.py

# inventory.py - agent is used by default
hosts = [
    ("host.example.com", {"ssh_user": "deploy"}),
]

SSH Key File

Specify a private key file:

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_user": "deploy",
        "ssh_key": "~/.ssh/deploy_key",
    }),
]

Encrypted SSH Key

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_user": "deploy",
        "ssh_key": "~/.ssh/encrypted_key",
        "ssh_key_password": "key-password",
    }),
]

Password Authentication (Not Recommended)

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_user": "deploy",
        "ssh_password": "password",
    }),
]

Password authentication is not recommended for production use. Use SSH keys with SSH agent instead.

Host Key Verification

Control how SSH host keys are verified:

Accept New Keys (Default)

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_strict_host_key_checking": "accept-new",
    }),
]

Accepts new hosts but verifies known hosts.

Strict Checking

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_strict_host_key_checking": "yes",
    }),
]

Rejects unknown hosts.

Disable Checking (Not Recommended)

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_strict_host_key_checking": "no",
    }),
]

Disabling host key checking makes you vulnerable to man-in-the-middle attacks. Only use in trusted environments.

Agent Forwarding

Enable SSH agent forwarding to use local SSH keys on remote hosts:

# inventory.py
hosts = [
    ("bastion.example.com", {
        "ssh_forward_agent": True,
    }),
]

Useful for:

Accessing Git repositories from remote hosts
SSHing from one remote host to another
Using local credentials on remote systems

Advanced Configuration

Paramiko Connection Options

Pass additional options to Paramiko:

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_paramiko_connect_kwargs": {
            "timeout": 30,
            "banner_timeout": 60,
            "auth_timeout": 30,
            "compress": True,
        },
    }),
]

Custom Known Hosts File

# inventory.py
hosts = [
    ("host.example.com", {
        "ssh_known_hosts_file": "/custom/path/known_hosts",
    }),
]

Complete Example

Here’s a comprehensive inventory using SSH connector:

# inventory.py
from pyinfra import Inventory

inventory = Inventory(
    # Production servers
    ([
        ("web1.example.com", {
            "ssh_user": "ubuntu",
            "ssh_forward_agent": True,
        }),
        ("web2.example.com", {
            "ssh_user": "ubuntu",
            "ssh_forward_agent": True,
        }),
        ("db1.example.com", {
            "ssh_user": "postgres",
            "ssh_port": 2222,
            "ssh_key": "~/.ssh/db_key",
        }),
    ], {
        # Global SSH settings
        "ssh_connect_retries": 3,
        "ssh_strict_host_key_checking": "yes",
    }),
    
    # Web servers group
    webservers=([
        "web1.example.com",
        "web2.example.com",
    ], {}),
    
    # Database servers group
    databases=([
        "db1.example.com",
    ], {}),
)

File Transfer Methods

The SSH connector supports two file transfer protocols:

SFTP (Default)

Recommended for most use cases:

More reliable
Better error handling
Works with more SSH server configurations

SCP

Useful for legacy systems:

Compatible with older SSH servers
Simpler protocol

# inventory.py
hosts = [
    ("legacy-host", {
        "ssh_file_transfer_protocol": "scp",
    }),
]

Troubleshooting

Connection Timeouts

Increase timeout and enable retries:

hosts = [
    ("slow-host.example.com", {
        "ssh_connect_retries": 5,
        "ssh_connect_retry_max_delay": 10.0,
        "ssh_paramiko_connect_kwargs": {
            "timeout": 60,
        },
    }),
]

Authentication Failures

Enable verbose logging:

pyinfra -vv inventory.py deploy.py

Check:

SSH key permissions (chmod 600 ~/.ssh/id_rsa)
SSH agent is running (ssh-add -l)
User has correct permissions on remote host
SSH service is running on remote host

Host Key Verification Failed

Update known_hosts:

ssh-keygen -R hostname
ssh hostname  # Accept new key

Source Reference

Location: src/pyinfra/connectors/ssh.py:119

Key Methods

connect() - Establish SSH connection
disconnect() - Close SSH connection
run_shell_command() - Execute commands via SSH
put_file() - Upload files via SFTP/SCP
get_file() - Download files via SFTP/SCP

Overview

Core API

Commands

Connectors

Facts

Overview

Connection Data

Inventory Examples

Single Host with SSH Forward Agent

Multiple Hosts with Shared SSH User

Multiple Hosts with Different Users

Using SSH Config File

Custom SSH Port and Key

Connection Retries

Using SCP Instead of SFTP

Authentication Methods

SSH Agent (Recommended)

SSH Key File

Encrypted SSH Key

Password Authentication (Not Recommended)

Host Key Verification

Accept New Keys (Default)

Strict Checking

Disable Checking (Not Recommended)

Agent Forwarding

Advanced Configuration

Paramiko Connection Options

Custom Known Hosts File

Complete Example

File Transfer Methods

SFTP (Default)

SCP

Troubleshooting

Connection Timeouts

Authentication Failures

Host Key Verification Failed

Source Reference

Key Methods

​Overview

​Connection Data

​Inventory Examples

​Single Host with SSH Forward Agent

​Multiple Hosts with Shared SSH User

​Multiple Hosts with Different Users

​Using SSH Config File

​Custom SSH Port and Key

​Connection Retries

​Using SCP Instead of SFTP

​Authentication Methods

​SSH Agent (Recommended)

​SSH Key File

​Encrypted SSH Key

​Password Authentication (Not Recommended)

​Host Key Verification

​Accept New Keys (Default)

​Strict Checking

​Disable Checking (Not Recommended)

​Agent Forwarding

​Advanced Configuration

​Paramiko Connection Options

​Custom Known Hosts File

​Complete Example

​File Transfer Methods

​SFTP (Default)

​SCP

​Troubleshooting

​Connection Timeouts

​Authentication Failures

​Host Key Verification Failed

​Source Reference

​Key Methods

Overview

Connection Data

Inventory Examples

Single Host with SSH Forward Agent

Multiple Hosts with Shared SSH User

Multiple Hosts with Different Users

Using SSH Config File

Custom SSH Port and Key

Connection Retries

Using SCP Instead of SFTP

Authentication Methods

SSH Agent (Recommended)

SSH Key File

Encrypted SSH Key

Password Authentication (Not Recommended)

Host Key Verification

Accept New Keys (Default)

Strict Checking

Disable Checking (Not Recommended)

Agent Forwarding

Advanced Configuration

Paramiko Connection Options

Custom Known Hosts File

Complete Example

File Transfer Methods

SFTP (Default)

SCP

Troubleshooting

Connection Timeouts

Authentication Failures

Host Key Verification Failed

Source Reference

Key Methods