Skip to content

ssh

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version historical.

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 C(ssh-agent) is highly recommended.

Parameters

Parameter Defaults / Choices 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 C(-o ControlPath) is set in ssh args.
Env: ANSIBLE_SSH_CONTROL_PATH
control_path_dir
string		 Default: ~/.ansible/cp
 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.
Env: ANSIBLE_SSH_CONTROL_PATH_DIR
host
string		 Default: inventory_hostname
 Hostname/IP to connect to.
host_key_checking
boolean		 Default: True
 Determines if SSH should reject or not a connection after checking host keys.
Env: ANSIBLE_HOST_KEY_CHECKING
Env: ANSIBLE_SSH_HOST_KEY_CHECKING
password
string		 Authentication password for the O(remote_user). Can be supplied as CLI option.
password_mechanism
string		 Default: ssh_askpass
Choices: ssh_askpass, sshpass, disable		 Mechanism to use for handling ssh password prompt
Env: ANSIBLE_SSH_PASSWORD_MECHANISM
Version Added: 2.19
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 (C(become)). For example, when using sudo operations you must first disable C(requiretty) in the sudoers file for the target hosts, which is why this feature is disabled by default.
Env: ANSIBLE_PIPELINING
Env: ANSIBLE_SSH_PIPELINING
pkcs11_provider
string		 PKCS11 SmartCard provider such as opensc, example: /usr/local/lib/opensc-pkcs11.so
Env: ANSIBLE_PKCS11_PROVIDER
Version Added: 2.12
port
int		 Remote port to connect to.
Env: ANSIBLE_REMOTE_PORT
private_key
string		 Private key contents in PEM format. Requires the C(SSH_AGENT) configuration to be enabled.
Env: ANSIBLE_PRIVATE_KEY
Version Added: 2.19
private_key_file
string		 Path to private key file to use for authentication.
Env: ANSIBLE_PRIVATE_KEY_FILE
private_key_passphrase
string		 Private key passphrase, dependent on O(private_key).
This does NOT have any effect when used with O(private_key_file).
Env: ANSIBLE_PRIVATE_KEY_PASSPHRASE
Version Added: 2.19
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.
Env: ANSIBLE_SSH_RETRIES
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.
Env: ANSIBLE_REMOTE_USER
scp_executable
string		 Default: scp
 This defines the location of the scp binary. It defaults to V(scp) which will use the first binary available in $PATH.
Env: ANSIBLE_SCP_EXECUTABLE
Version Added: 2.6
scp_extra_args
string		 Extra exclusive to the C(scp) CLI
Env: ANSIBLE_SCP_EXTRA_ARGS
sftp_batch_mode
bool		 Default: True
 When set to C(True), sftp will be run in batch mode, allowing detection of transfer errors.
When set to C(False), sftp will not be run in batch mode, preventing detection of transfer errors.
Env: ANSIBLE_SFTP_BATCH_MODE
sftp_executable
string		 Default: sftp
 This defines the location of the sftp binary. It defaults to V(sftp) which will use the first binary available in $PATH.
Env: ANSIBLE_SFTP_EXECUTABLE
Version Added: 2.6
sftp_extra_args
string		 Extra exclusive to the C(sftp) CLI
Env: ANSIBLE_SFTP_EXTRA_ARGS
ssh_args
string		 Default: -C -o ControlMaster=auto -o ControlPersist=60s
 Arguments to pass to all SSH CLI tools.
Env: ANSIBLE_SSH_ARGS
ssh_common_args
string		 Common extra args for all SSH CLI tools.
Env: ANSIBLE_SSH_COMMON_ARGS
ssh_executable
string		 Default: ssh
 This defines the location of the SSH binary. It defaults to V(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.
Env: ANSIBLE_SSH_EXECUTABLE
Version Added: 2.2
ssh_extra_args
string		 Extra exclusive to the SSH CLI.
Env: ANSIBLE_SSH_EXTRA_ARGS
ssh_transfer_method
string		 Default: smart
Choices: piped, scp, sftp, smart		 Preferred method to use when transferring files over ssh
Env: ANSIBLE_SSH_TRANSFER_METHOD
sshpass_prompt
string		 Password prompt that C(sshpass)/C(SSH_ASKPASS) should search for.
Supported by sshpass 1.06 and up when O(password_mechanism) set to V(sshpass).
Defaults to C(Enter PIN for) when pkcs11_provider is set.
Defaults to C(assword) when O(password_mechanism) set to V(ssh_askpass).
Env: ANSIBLE_SSHPASS_PROMPT
Version Added: 2.10
timeout
integer		 Default: 10
 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).
Env: ANSIBLE_TIMEOUT
Env: ANSIBLE_SSH_TIMEOUT
use_tty
bool		 Default: True
 add -tt to ssh commands to force tty allocation.
Env: ANSIBLE_SSH_USETTY
Version Added: 2.5
verbosity
int		 Requested verbosity level for the SSH CLI.
Env: ANSIBLE_SSH_VERBOSITY
Version Added: 2.19

Notes

Note

  • This plugin is mostly a wrapper to the ssh CLI utility and the exact behavior of the options depends on this tool. This means that the documentation provided here is subject to be overridden by the CLI tool itself.
  • Many options default to V(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 C(Port) entry in your C(.ssh/config).
  • The ssh CLI tool uses return code 255 as a 'connection error', this can conflict with commands/tools that also return 255 as an error code and will look like an 'unreachable' condition or 'connection error' to this plugin.

Authors

  • Ansible (@core)