You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

ssh – connect via ssh client binary¶

Synopsis
Parameters
Status

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 -		ini entries: [ssh_connection] control_path = VALUE env:ANSIBLE_SSH_CONTROL_PATH var: ansible_control_path	This is the location to save ssh's ControlPath sockets, it uses ssh's variable substitution. Since 2.3, if null, ansible will generate a unique hash. Use `%(directory)s` to indicate where to use the control dir path setting.
control_path_dir -	Default: "~/.ansible/cp"	ini entries: [ssh_connection] control_path_dir = ~/.ansible/cp env:ANSIBLE_SSH_CONTROL_PATH_DIR var: ansible_control_path_dir	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 -	Default: "inventory_hostname"	var: ansible_host var: ansible_ssh_host	Hostname/ip to connect to.
host_key_checking boolean		ini entries: [defaults] host_key_checking = VALUE [ssh_connection] host_key_checking = VALUE env:ANSIBLE_HOST_KEY_CHECKING env:ANSIBLE_SSH_HOST_KEY_CHECKING var: ansible_host_key_checking var: ansible_ssh_host_key_checking	Determines if ssh should check host keys
password -		var: ansible_password var: ansible_ssh_pass	Authentication password for the `remote_user`. Can be supplied as CLI option.
pipelining boolean	Default: "ANSIBLE_PIPELINING"	ini entries: [defaults] pipelining = ANSIBLE_PIPELINING env:ANSIBLE_PIPELINING var: ansible_pipelining var: ansible_ssh_pipelining	Pipelining reduces the number of SSH operations required to execute a module on the remote server, by executing many Ansible modules without actual file transfer. This can result in a very significant performance improvement when enabled. However this conflicts 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	Default: 22	ini entries: [defaults] remote_port = 22 env:ANSIBLE_REMOTE_PORT var: ansible_port var: ansible_ssh_port	Remote port to connect to.
private_key_file -		ini entries: [defaults] private_key_file = VALUE env:ANSIBLE_PRIVATE_KEY_FILE var: ansible_private_key_file var: ansible_ssh_private_key_file	Path to private key file to use for authentication
remote_user -		ini entries: [defaults] remote_user = VALUE env:ANSIBLE_REMOTE_USER var: ansible_user var: ansible_ssh_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
retries integer	Default: 3	ini entries: [connection] retries = 3 [ssh_connection] retries = 3 env:ANSIBLE_SSH_RETRIES var: ansible_ssh_retries	Number of attempts to connect.
scp_executable - added in 2.6	Default: "scp"	ini entries: [ssh_connection] scp_executable = scp env:ANSIBLE_SCP_EXECUTABLE var: ansible_scp_executable	This defines the location of the scp binary. It defaults to `scp` which will use the first binary available in $PATH.
scp_extra_args -		ini entries: [ssh_connection] scp_extra_args = VALUE env:ANSIBLE_SCP_EXTRA_ARGS var: ansible_scp_extra_args	Extra exclusive to the ``scp`` CLI
scp_if_ssh -	Default: "smart"	ini entries: [ssh_connection] scp_if_ssh = smart env:ANSIBLE_SCP_IF_SSH var: ansible_scp_if_ssh	Prefered 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	TODO: write it
sftp_executable - added in 2.6	Default: "sftp"	ini entries: [ssh_connection] sftp_executable = sftp env:ANSIBLE_SFTP_EXECUTABLE var: ansible_sftp_executable	This defines the location of the sftp binary. It defaults to ``sftp`` which will use the first binary available in $PATH.
sftp_extra_args -		ini entries: [ssh_connection] sftp_extra_args = VALUE env:ANSIBLE_SFTP_EXTRA_ARGS var: ansible_sftp_extra_args	Extra exclusive to the ``sftp`` CLI
ssh_args -	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	Arguments to pass to all ssh cli tools
ssh_common_args -		ini entries: [ssh_connection] ssh_common_args = VALUE env:ANSIBLE_SSH_COMMON_ARGS var: ansible_ssh_common_args	Common extra args for all ssh CLI tools
ssh_executable - added in 2.2	Default: "ssh"	ini entries: [ssh_connection] ssh_executable = ssh env:ANSIBLE_SSH_EXECUTABLE var: ansible_ssh_executable	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 -		ini entries: [ssh_connection] ssh_extra_args = VALUE env:ANSIBLE_SSH_EXTRA_ARGS var: ansible_ssh_extra_args	Extra exclusive to the 'ssh' CLI
use_tty boolean added in 2.5	Choices: no yes ←	ini entries: [ssh_connection] usetty = yes env:ANSIBLE_SSH_USETTY var: ansible_ssh_use_tty	add -tt to ssh commands to force tty allocation

Status ¶

Authors¶

ansible (@core)

Hint

If you notice any issues in this documentation you can edit this document to improve it.