Documentation

ssh - connect via ssh client binary

Synopsis

  • This connection plugin allows ansible to communicate to the target machines via normal ssh command line.

Parameters

Parameter
Choices/Defaults
Configuration
Comments
control_path
ini entries:

[ssh_connection ]
control_path = VALUE

env:ANSIBLE_SSH_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
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
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
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
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
Default:
3
ini entries:

[connection ]
retries = 3

[ssh_connection ]
retries = 3

env:ANSIBLE_SSH_RETRIES
Number of attempts to connect.
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
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
    Choices:
  • no
  • yes ←
ini entries:

[ssh_connection ]
sftp_batch_mode = yes

env:ANSIBLE_SFTP_BATCH_MODE
TODO: write it
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
Arguments to pass to all ssh cli tools
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
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
var: ansible_ssh_extra_args
Extra exclusive to the 'ssh' CLI
use_tty
(added in 2.5)
    Choices:
  • no
  • yes ←
ini entries:

[ssh_connection ]
usetty = yes

env:ANSIBLE_SSH_USETTY
add -tt to ssh commands to force tty allocation

Status

Author

  • ansible (@core)

Hint

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