ansible.builtin.ssh – connect via ssh client binary

Note

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

Synopsis

  • This connection plugin allows ansible to communicate to the target machines via 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 Choices/Defaults Configuration Comments
control_path
string
ini entries:

[ssh_connection]
control_path = None

env:ANSIBLE_SSH_CONTROL_PATH
var: ansible_control_path
added in 2.7 of ansible.builtin
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.
control_path_dir
string
Default:
"~/.ansible/cp"
ini entries:

[ssh_connection]
control_path_dir = ~/.ansible/cp

env:ANSIBLE_SSH_CONTROL_PATH_DIR
var: ansible_control_path_dir
added in 2.7 of ansible.builtin
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.
host
string
var: inventory_hostname
var: ansible_host
var: ansible_ssh_host
var: delegated_vars['ansible_host']
var: delegated_vars['ansible_ssh_host']
Hostname/ip to connect to.
host_key_checking
boolean
    Choices:
  • no
  • yes
ini entries:

[defaults]
host_key_checking = None

[ssh_connection]
host_key_checking = None

added in 2.5 of ansible.builtin

env:ANSIBLE_HOST_KEY_CHECKING
env:ANSIBLE_SSH_HOST_KEY_CHECKING
added in 2.5 of ansible.builtin
var: ansible_host_key_checking
added in 2.5 of ansible.builtin
var: ansible_ssh_host_key_checking
added in 2.5 of ansible.builtin
Determines if ssh should check host keys
password
string
var: ansible_password
var: ansible_ssh_pass
var: ansible_ssh_password
Authentication password for the remote_user. Can be supplied as CLI option.
pipelining
boolean
    Choices:
  • no
  • yes
Default:
"ANSIBLE_PIPELINING"
ini entries:

[connection]
pipelining = ANSIBLE_PIPELINING

[ssh_connection]
pipelining = ANSIBLE_PIPELINING

env:ANSIBLE_PIPELINING
env:ANSIBLE_SSH_PIPELINING
var: ansible_pipelining
var: ansible_ssh_pipelining
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.
port
integer
ini entries:

[defaults]
remote_port = None

env:ANSIBLE_REMOTE_PORT
var: ansible_port
var: ansible_ssh_port
Remote port to connect to.
private_key_file
string
ini entries:

[defaults]
private_key_file = None

env:ANSIBLE_PRIVATE_KEY_FILE
var: ansible_private_key_file
var: ansible_ssh_private_key_file
cli: --private-key-file
Path to private key file to use for authentication
reconnection_retries
integer
Default:
0
ini entries:

[connection]
retries = 0

[ssh_connection]
retries = 0

env:ANSIBLE_SSH_RETRIES
var: ansible_ssh_retries
added in 2.7 of ansible.builtin
Number of attempts to connect.
remote_user
string
ini entries:

[defaults]
remote_user = None

env:ANSIBLE_REMOTE_USER
var: ansible_user
var: ansible_ssh_user
cli: --user
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
scp_executable
string
added in 2.6 of ansible.builtin
Default:
"scp"
ini entries:

[ssh_connection]
scp_executable = scp

env:ANSIBLE_SCP_EXECUTABLE
var: ansible_scp_executable
added in 2.7 of ansible.builtin
This defines the location of the scp binary. It defaults to `scp` which will use the first binary available in $PATH.
scp_extra_args
string
Default:
""
ini entries:

[ssh_connection]
scp_extra_args =

added in 2.7 of ansible.builtin

env:ANSIBLE_SCP_EXTRA_ARGS
added in 2.7 of ansible.builtin
var: ansible_scp_extra_args
cli: --scp-extra-args
Extra exclusive to the ``scp`` CLI
scp_if_ssh
string
Default:
"smart"
ini entries:

[ssh_connection]
scp_if_ssh = smart

env:ANSIBLE_SCP_IF_SSH
var: ansible_scp_if_ssh
added in 2.7 of ansible.builtin
Preferred method to use when transfering 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'
sftp_batch_mode
boolean
    Choices:
  • no
  • yes ←
ini entries:

[ssh_connection]
sftp_batch_mode = yes

env:ANSIBLE_SFTP_BATCH_MODE
var: ansible_sftp_batch_mode
added in 2.7 of ansible.builtin
TODO: write it
sftp_executable
string
added in 2.6 of ansible.builtin
Default:
"sftp"
ini entries:

[ssh_connection]
sftp_executable = sftp

env:ANSIBLE_SFTP_EXECUTABLE
var: ansible_sftp_executable
added in 2.7 of ansible.builtin
This defines the location of the sftp binary. It defaults to ``sftp`` which will use the first binary available in $PATH.
sftp_extra_args
string
Default:
""
ini entries:

[ssh_connection]
sftp_extra_args =

added in 2.7 of ansible.builtin

env:ANSIBLE_SFTP_EXTRA_ARGS
added in 2.7 of ansible.builtin
var: ansible_sftp_extra_args
cli: --sftp-extra-args
Extra exclusive to the ``sftp`` CLI
ssh_args
string
Default:
"-C -o ControlMaster=auto -o ControlPersist=60s"
ini entries:

[ssh_connection]
ssh_args = -C -o ControlMaster=auto -o ControlPersist=60s

env:ANSIBLE_SSH_ARGS
var: ansible_ssh_args
added in 2.7 of ansible.builtin
cli: --ssh-args
Arguments to pass to all ssh cli tools
ssh_common_args
string
Default:
""
ini entries:

[ssh_connection]
ssh_common_args =

added in 2.7 of ansible.builtin

env:ANSIBLE_SSH_COMMON_ARGS
added in 2.7 of ansible.builtin
var: ansible_ssh_common_args
cli: --ssh-common-args
Common extra args for all ssh CLI tools
ssh_executable
string
added in 2.2 of ansible.builtin
Default:
"ssh"
ini entries:

[ssh_connection]
ssh_executable = ssh

env:ANSIBLE_SSH_EXECUTABLE
var: ansible_ssh_executable
added in 2.7 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.
ssh_extra_args
string
Default:
""
ini entries:

[ssh_connection]
ssh_extra_args =

added in 2.7 of ansible.builtin

env:ANSIBLE_SSH_EXTRA_ARGS
added in 2.7 of ansible.builtin
var: ansible_ssh_extra_args
cli: --ssh-extra-args
Extra exclusive to the 'ssh' CLI
ssh_transfer_method
string
    Choices:
  • sftp
  • scp
  • piped
  • smart
ini entries:

[ssh_connection]
transfer_method = None

env:ANSIBLE_SSH_TRANSFER_METHOD
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
sshpass_prompt
string
added in 2.10 of ansible.builtin
Default:
""
ini entries:

[ssh_connection]
sshpass_prompt =

env:ANSIBLE_SSHPASS_PROMPT
var: ansible_sshpass_prompt
Password prompt that sshpass should search for. Supported by sshpass 1.06 and up.
timeout
integer
Default:
10
ini entries:

[defaults]
timeout = 10

[ssh_connection]
timeout = 10

added in 2.11 of ansible.builtin

env:ANSIBLE_TIMEOUT
env:ANSIBLE_SSH_TIMEOUT
added in 2.11 of ansible.builtin
var: ansible_ssh_timeout
added in 2.11 of ansible.builtin
cli: --timeout
This is the default ammount 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)
use_tty
boolean
added in 2.5 of ansible.builtin
    Choices:
  • no
  • yes ←
ini entries:

[ssh_connection]
usetty = yes

env:ANSIBLE_SSH_USETTY
var: ansible_ssh_use_tty
added in 2.7 of ansible.builtin
add -tt to ssh commands to force tty allocation

Notes

Note

  • Many options default to ‘None’ here but that only means we don’t 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)