ansible.builtin.ssh connection – connect via SSH client binary

Note

This connection plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name ssh even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same connection plugin name.

Synopsis

  • This connection plugin allows Ansible to communicate to the target machines through normal SSH command line.

  • Ansible does not expose a channel to allow communication between the user and the SSH process to accept a password manually to decrypt an SSH key when using this connection plugin (which is the default). The use of ssh-agent is highly recommended.

Parameters

Parameter

Comments

control_path

string

This is the location to save SSH’s ControlPath sockets, it uses SSH’s variable substitution.

Since 2.3, if null (default), ansible will generate a unique hash. Use %(directory)s to indicate where to use the control dir path setting.

Before 2.3 it defaulted to control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r.

Be aware that this setting is ignored if -o ControlPath is set in ssh args.

Configuration:

  • INI entry:

    [ssh_connection]
    control_path = None
    
  • Environment variable: ANSIBLE_SSH_CONTROL_PATH

  • Variable: ansible_control_path

    added in 2.7 of ansible.builtin

control_path_dir

string

This sets the directory to use for ssh control path if the control path setting is null.

Also, provides the %(directory)s variable for the control path setting.

Default: “~/.ansible/cp”

Configuration:

  • INI entry:

    [ssh_connection]
    control_path_dir = ~/.ansible/cp
    
  • Environment variable: ANSIBLE_SSH_CONTROL_PATH_DIR

  • Variable: ansible_control_path_dir

    added in 2.7 of ansible.builtin

host

string

Hostname/IP to connect to.

Default: “inventory_hostname”

Configuration:

  • Variable: inventory_hostname

  • Variable: ansible_host

  • Variable: ansible_ssh_host

  • Variable: delegated_vars[‘ansible_host’]

  • Variable: delegated_vars[‘ansible_ssh_host’]

host_key_checking

boolean

Determines if SSH should check host keys.

Choices:

  • no

  • yes ← (default)

Configuration:

  • INI entries:

    [defaults]
    host_key_checking = yes
    
    [ssh_connection]
    host_key_checking = yes
    

    added in 2.5 of ansible.builtin

  • Environment variable: ANSIBLE_HOST_KEY_CHECKING

  • Environment variable: ANSIBLE_SSH_HOST_KEY_CHECKING

    added in 2.5 of ansible.builtin

  • Variable: ansible_host_key_checking

    added in 2.5 of ansible.builtin

  • Variable: ansible_ssh_host_key_checking

    added in 2.5 of ansible.builtin

password

string

Authentication password for the remote_user. Can be supplied as CLI option.

Configuration:

  • Variable: ansible_password

  • Variable: ansible_ssh_pass

  • Variable: ansible_ssh_password

pipelining

boolean

Pipelining reduces the number of connection operations required to execute a module on the remote server, by executing many Ansible modules without actual file transfers.

This can result in a very significant performance improvement when enabled.

However this can conflict with privilege escalation (become). For example, when using sudo operations you must first disable ‘requiretty’ in the sudoers file for the target hosts, which is why this feature is disabled by default.

Choices:

  • no

  • yes

Default: “ANSIBLE_PIPELINING”

Configuration:

  • INI entries:

    [defaults]
    pipelining = ANSIBLE_PIPELINING
    
    [connection]
    pipelining = ANSIBLE_PIPELINING
    
    [ssh_connection]
    pipelining = ANSIBLE_PIPELINING
    
  • Environment variable: ANSIBLE_PIPELINING

  • Environment variable: ANSIBLE_SSH_PIPELINING

  • Variable: ansible_pipelining

  • Variable: ansible_ssh_pipelining

pkcs11_provider

string

added in 2.12 of ansible.builtin

PKCS11 SmartCard provider such as opensc, example: /usr/local/lib/opensc-pkcs11.so

Requires sshpass version 1.06+, sshpass must support the -P option.

Default: “”

Configuration:

  • INI entry:

    [ssh_connection]
    pkcs11_provider =
    
  • Environment variable: ANSIBLE_PKCS11_PROVIDER

  • Variable: ansible_ssh_pkcs11_provider

port

integer

Remote port to connect to.

Configuration:

  • INI entry:

    [defaults]
    remote_port = None
    
  • Environment variable: ANSIBLE_REMOTE_PORT

  • Variable: ansible_port

  • Variable: ansible_ssh_port

  • Keyword: port

private_key_file

string

Path to private key file to use for authentication.

Configuration:

  • INI entry:

    [defaults]
    private_key_file = None
    
  • Environment variable: ANSIBLE_PRIVATE_KEY_FILE

  • Variable: ansible_private_key_file

  • Variable: ansible_ssh_private_key_file

  • CLI argument: –private-key

reconnection_retries

integer

Number of attempts to connect.

Ansible retries connections only if it gets an SSH error with a return code of 255.

Any errors with return codes other than 255 indicate an issue with program execution.

Default: 0

Configuration:

  • INI entries:

    [connection]
    retries = 0
    
    [ssh_connection]
    retries = 0
    
  • Environment variable: ANSIBLE_SSH_RETRIES

  • Variable: ansible_ssh_retries

    added in 2.7 of ansible.builtin

remote_user

string

User name with which to login to the remote server, normally set by the remote_user keyword.

If no user is supplied, Ansible will let the SSH client binary choose the user as it normally.

Configuration:

  • INI entry:

    [defaults]
    remote_user = None
    
  • Environment variable: ANSIBLE_REMOTE_USER

  • Variable: ansible_user

  • Variable: ansible_ssh_user

  • Keyword: remote_user

  • CLI argument: –user

scp_executable

string

added in 2.6 of ansible.builtin

This defines the location of the scp binary. It defaults to scp which will use the first binary available in $PATH.

Default: “scp”

Configuration:

  • INI entry:

    [ssh_connection]
    scp_executable = scp
    
  • Environment variable: ANSIBLE_SCP_EXECUTABLE

  • Variable: ansible_scp_executable

    added in 2.7 of ansible.builtin

scp_extra_args

string

Extra exclusive to the scp CLI

Default: “”

Configuration:

  • INI entry:

    [ssh_connection]
    scp_extra_args =
    

    added in 2.7 of ansible.builtin

  • Environment variable: ANSIBLE_SCP_EXTRA_ARGS

    added in 2.7 of ansible.builtin

  • Variable: ansible_scp_extra_args

  • CLI argument: –scp-extra-args

scp_if_ssh

string

Removed in: version 2.17

Why: In favor of the “ssh_transfer_method” option.

Alternative: ssh_transfer_method

Preferred method to use when transferring files over SSH.

When set to smart, Ansible will try them until one succeeds or they all fail.

If set to True, it will force ‘scp’, if False it will use ‘sftp’.

This setting will overridden by ssh_transfer_method if set.

Default: “smart”

Configuration:

  • INI entry:

    [ssh_connection]
    scp_if_ssh = smart
    
  • Environment variable: ANSIBLE_SCP_IF_SSH

  • Variable: ansible_scp_if_ssh

    added in 2.7 of ansible.builtin

sftp_batch_mode

boolean

TODO: write it

Choices:

  • no

  • yes ← (default)

Configuration:

  • INI entry:

    [ssh_connection]
    sftp_batch_mode = yes
    
  • Environment variable: ANSIBLE_SFTP_BATCH_MODE

  • Variable: ansible_sftp_batch_mode

    added in 2.7 of ansible.builtin

sftp_executable

string

added in 2.6 of ansible.builtin

This defines the location of the sftp binary. It defaults to sftp which will use the first binary available in $PATH.

Default: “sftp”

Configuration:

  • INI entry:

    [ssh_connection]
    sftp_executable = sftp
    
  • Environment variable: ANSIBLE_SFTP_EXECUTABLE

  • Variable: ansible_sftp_executable

    added in 2.7 of ansible.builtin

sftp_extra_args

string

Extra exclusive to the sftp CLI

Default: “”

Configuration:

  • INI entry:

    [ssh_connection]
    sftp_extra_args =
    

    added in 2.7 of ansible.builtin

  • Environment variable: ANSIBLE_SFTP_EXTRA_ARGS

    added in 2.7 of ansible.builtin

  • Variable: ansible_sftp_extra_args

  • CLI argument: –sftp-extra-args

ssh_args

string

Arguments to pass to all SSH CLI tools.

Default: “-C -o ControlMaster=auto -o ControlPersist=60s”

Configuration:

  • INI entry:

    [ssh_connection]
    ssh_args = -C -o ControlMaster=auto -o ControlPersist=60s
    
  • Environment variable: ANSIBLE_SSH_ARGS

  • Variable: ansible_ssh_args

    added in 2.7 of ansible.builtin

ssh_common_args

string

Common extra args for all SSH CLI tools.

Default: “”

Configuration:

  • INI entry:

    [ssh_connection]
    ssh_common_args =
    

    added in 2.7 of ansible.builtin

  • Environment variable: ANSIBLE_SSH_COMMON_ARGS

    added in 2.7 of ansible.builtin

  • Variable: ansible_ssh_common_args

  • CLI argument: –ssh-common-args

ssh_executable

string

added in 2.2 of ansible.builtin

This defines the location of the SSH binary. It defaults to ssh which will use the first SSH binary available in $PATH.

This option is usually not required, it might be useful when access to system SSH is restricted, or when using SSH wrappers to connect to remote hosts.

Default: “ssh”

Configuration:

  • INI entry:

    [ssh_connection]
    ssh_executable = ssh
    
  • Environment variable: ANSIBLE_SSH_EXECUTABLE

  • Variable: ansible_ssh_executable

    added in 2.7 of ansible.builtin

ssh_extra_args

string

Extra exclusive to the SSH CLI.

Default: “”

Configuration:

  • INI entry:

    [ssh_connection]
    ssh_extra_args =
    

    added in 2.7 of ansible.builtin

  • Environment variable: ANSIBLE_SSH_EXTRA_ARGS

    added in 2.7 of ansible.builtin

  • Variable: ansible_ssh_extra_args

  • CLI argument: –ssh-extra-args

ssh_transfer_method

string

Preferred method to use when transferring files over ssh

Setting to ‘smart’ (default) will try them in order, until one succeeds or they all fail

Using ‘piped’ creates an ssh pipe with dd on either side to copy the data

Choices:

  • sftp

  • scp

  • piped

  • smart

Configuration:

  • INI entry:

    [ssh_connection]
    transfer_method = None
    
  • Environment variable: ANSIBLE_SSH_TRANSFER_METHOD

  • Variable: ansible_ssh_transfer_method

    added in 2.12 of ansible.builtin

sshpass_prompt

string

added in 2.10 of ansible.builtin

Password prompt that sshpass should search for. Supported by sshpass 1.06 and up.

Defaults to Enter PIN for when pkcs11_provider is set.

Default: “”

Configuration:

  • INI entry:

    [ssh_connection]
    sshpass_prompt =
    
  • Environment variable: ANSIBLE_SSHPASS_PROMPT

  • Variable: ansible_sshpass_prompt

timeout

integer

This is the default amount of time we will wait while establishing an SSH connection.

It also controls how long we can wait to access reading the connection once established (select on the socket).

Default: 10

Configuration:

  • INI entries:

    [defaults]
    timeout = 10
    
    [ssh_connection]
    timeout = 10
    

    added in 2.11 of ansible.builtin

  • Environment variable: ANSIBLE_TIMEOUT

  • Environment variable: ANSIBLE_SSH_TIMEOUT

    added in 2.11 of ansible.builtin

  • Variable: ansible_ssh_timeout

    added in 2.11 of ansible.builtin

  • CLI argument: –timeout

use_tty

boolean

added in 2.5 of ansible.builtin

add -tt to ssh commands to force tty allocation.

Choices:

  • no

  • yes ← (default)

Configuration:

  • INI entry:

    [ssh_connection]
    usetty = yes
    
  • Environment variable: ANSIBLE_SSH_USETTY

  • Variable: ansible_ssh_use_tty

    added in 2.7 of ansible.builtin

Notes

Note

  • Many options default to None here but that only means we do not override the SSH tool’s defaults and/or configuration. For example, if you specify the port in this plugin it will override any Port entry in your .ssh/config.

Authors

  • ansible (@core)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.