ansible / ansible.builtin / v2.16.5 / connection / ssh connect via SSH client binary | "added in version" historical of ansible.builtin" Authors: ansible (@core)ansible.builtin.ssh (v2.16.5) — connection
pip
Install with pip install ansible-core==2.16.5
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.
host: default: inventory_hostname description: Hostname/IP to connect to. type: string vars: - name: inventory_hostname - name: ansible_host - name: ansible_ssh_host - name: delegated_vars['ansible_host'] - name: delegated_vars['ansible_ssh_host'] port: description: Remote port to connect to. env: - name: ANSIBLE_REMOTE_PORT ini: - key: remote_port section: defaults keyword: - name: port type: int vars: - name: ansible_port - name: ansible_ssh_port timeout: cli: - name: timeout default: 10 description: - 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: - name: ANSIBLE_TIMEOUT - name: ANSIBLE_SSH_TIMEOUT version_added: '2.11' version_added_collection: ansible.builtin ini: - key: timeout section: defaults - key: timeout section: ssh_connection version_added: '2.11' version_added_collection: ansible.builtin type: integer vars: - name: ansible_ssh_timeout version_added: '2.11' version_added_collection: ansible.builtin use_tty: default: true description: add -tt to ssh commands to force tty allocation. env: - name: ANSIBLE_SSH_USETTY ini: - key: usetty section: ssh_connection type: bool vars: - name: ansible_ssh_use_tty version_added: '2.7' version_added_collection: ansible.builtin version_added: '2.5' version_added_collection: ansible.builtin password: description: Authentication password for the O(remote_user). Can be supplied as CLI option. type: string vars: - name: ansible_password - name: ansible_ssh_pass - name: ansible_ssh_password ssh_args: default: -C -o ControlMaster=auto -o ControlPersist=60s description: Arguments to pass to all SSH CLI tools. env: - name: ANSIBLE_SSH_ARGS ini: - key: ssh_args section: ssh_connection type: string vars: - name: ansible_ssh_args version_added: '2.7' version_added_collection: ansible.builtin pipelining: default: false description: - 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. env: - name: ANSIBLE_PIPELINING - name: ANSIBLE_SSH_PIPELINING ini: - key: pipelining section: defaults - key: pipelining section: connection - key: pipelining section: ssh_connection type: boolean vars: - name: ansible_pipelining - name: ansible_ssh_pipelining scp_if_ssh: default: smart deprecated: alternatives: O(ssh_transfer_method) collection_name: ansible.builtin version: '2.17' why: In favor of the O(ssh_transfer_method) option. description: - Preferred method to use when transferring files over SSH. - When set to V(smart), Ansible will try them until one succeeds or they all fail. - If set to V(True), it will force 'scp', if V(False) it will use 'sftp'. - For OpenSSH >=9.0 you must add an additional option to enable scp (C(scp_extra_args="-O")) - This setting will overridden by O(ssh_transfer_method) if set. env: - name: ANSIBLE_SCP_IF_SSH ini: - key: scp_if_ssh section: ssh_connection vars: - name: ansible_scp_if_ssh version_added: '2.7' version_added_collection: ansible.builtin remote_user: cli: - name: user description: - 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: - name: ANSIBLE_REMOTE_USER ini: - key: remote_user section: defaults keyword: - name: remote_user type: string vars: - name: ansible_user - name: ansible_ssh_user control_path: description: - 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: - name: ANSIBLE_SSH_CONTROL_PATH ini: - key: control_path section: ssh_connection type: string vars: - name: ansible_control_path version_added: '2.7' version_added_collection: ansible.builtin scp_executable: default: scp description: - This defines the location of the scp binary. It defaults to V(scp) which will use the first binary available in $PATH. env: - name: ANSIBLE_SCP_EXECUTABLE ini: - key: scp_executable section: ssh_connection type: string vars: - name: ansible_scp_executable version_added: '2.7' version_added_collection: ansible.builtin version_added: '2.6' version_added_collection: ansible.builtin scp_extra_args: cli: - name: scp_extra_args default: '' description: Extra exclusive to the C(scp) CLI env: - name: ANSIBLE_SCP_EXTRA_ARGS version_added: '2.7' version_added_collection: ansible.builtin ini: - key: scp_extra_args section: ssh_connection version_added: '2.7' version_added_collection: ansible.builtin type: string vars: - name: ansible_scp_extra_args ssh_executable: default: ssh description: - 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: - name: ANSIBLE_SSH_EXECUTABLE ini: - key: ssh_executable section: ssh_connection type: string vars: - name: ansible_ssh_executable version_added: '2.7' version_added_collection: ansible.builtin version_added: '2.2' version_added_collection: ansible.builtin ssh_extra_args: cli: - name: ssh_extra_args default: '' description: Extra exclusive to the SSH CLI. env: - name: ANSIBLE_SSH_EXTRA_ARGS version_added: '2.7' version_added_collection: ansible.builtin ini: - key: ssh_extra_args section: ssh_connection version_added: '2.7' version_added_collection: ansible.builtin type: string vars: - name: ansible_ssh_extra_args sshpass_prompt: default: '' description: - 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: - name: ANSIBLE_SSHPASS_PROMPT ini: - key: sshpass_prompt section: ssh_connection type: string vars: - name: ansible_sshpass_prompt version_added: '2.10' version_added_collection: ansible.builtin pkcs11_provider: default: '' description: - '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: - name: ANSIBLE_PKCS11_PROVIDER ini: - key: pkcs11_provider section: ssh_connection type: string vars: - name: ansible_ssh_pkcs11_provider version_added: '2.12' version_added_collection: ansible.builtin sftp_batch_mode: default: true description: 'TODO: write it' env: - name: ANSIBLE_SFTP_BATCH_MODE ini: - key: sftp_batch_mode section: ssh_connection type: bool vars: - name: ansible_sftp_batch_mode version_added: '2.7' version_added_collection: ansible.builtin sftp_executable: default: sftp description: - This defines the location of the sftp binary. It defaults to V(sftp) which will use the first binary available in $PATH. env: - name: ANSIBLE_SFTP_EXECUTABLE ini: - key: sftp_executable section: ssh_connection type: string vars: - name: ansible_sftp_executable version_added: '2.7' version_added_collection: ansible.builtin version_added: '2.6' version_added_collection: ansible.builtin sftp_extra_args: cli: - name: sftp_extra_args default: '' description: Extra exclusive to the C(sftp) CLI env: - name: ANSIBLE_SFTP_EXTRA_ARGS version_added: '2.7' version_added_collection: ansible.builtin ini: - key: sftp_extra_args section: ssh_connection version_added: '2.7' version_added_collection: ansible.builtin type: string vars: - name: ansible_sftp_extra_args ssh_common_args: cli: - name: ssh_common_args default: '' description: Common extra args for all SSH CLI tools. env: - name: ANSIBLE_SSH_COMMON_ARGS version_added: '2.7' version_added_collection: ansible.builtin ini: - key: ssh_common_args section: ssh_connection version_added: '2.7' version_added_collection: ansible.builtin type: string vars: - name: ansible_ssh_common_args control_path_dir: default: ~/.ansible/cp description: - 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: - name: ANSIBLE_SSH_CONTROL_PATH_DIR ini: - key: control_path_dir section: ssh_connection type: string vars: - name: ansible_control_path_dir version_added: '2.7' version_added_collection: ansible.builtin private_key_file: cli: - name: private_key_file option: --private-key description: - Path to private key file to use for authentication. env: - name: ANSIBLE_PRIVATE_KEY_FILE ini: - key: private_key_file section: defaults type: string vars: - name: ansible_private_key_file - name: ansible_ssh_private_key_file host_key_checking: default: true description: Determines if SSH should check host keys. env: - name: ANSIBLE_HOST_KEY_CHECKING - name: ANSIBLE_SSH_HOST_KEY_CHECKING version_added: '2.5' version_added_collection: ansible.builtin ini: - key: host_key_checking section: defaults - key: host_key_checking section: ssh_connection version_added: '2.5' version_added_collection: ansible.builtin type: boolean vars: - name: ansible_host_key_checking version_added: '2.5' version_added_collection: ansible.builtin - name: ansible_ssh_host_key_checking version_added: '2.5' version_added_collection: ansible.builtin ssh_transfer_method: choices: - sftp - scp - piped - smart description: - 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 - For OpenSSH >=9.0 you must add an additional option to enable scp (scp_extra_args="-O") - Using 'piped' creates an ssh pipe with C(dd) on either side to copy the data env: - name: ANSIBLE_SSH_TRANSFER_METHOD ini: - key: transfer_method section: ssh_connection type: string vars: - name: ansible_ssh_transfer_method version_added: '2.12' version_added_collection: ansible.builtin reconnection_retries: default: 0 description: - 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: - name: ANSIBLE_SSH_RETRIES ini: - key: retries section: connection - key: retries section: ssh_connection type: integer vars: - name: ansible_ssh_retries version_added: '2.7' version_added_collection: ansible.builtin