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.
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 Requires sshpass version 1.06+, sshpass must support the -P option. Env: ANSIBLE_PKCS11_PROVIDER Version Added: 2.12
port int		Remote port to connect to. Env: ANSIBLE_REMOTE_PORT
private_key_file string		Path to private key file to use for authentication. Env: ANSIBLE_PRIVATE_KEY_FILE
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	TODO: write it 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 sshpass should search for. Supported by sshpass 1.06 and up. Defaults to C(Enter PIN for) when pkcs11_provider is set. 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

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)