ansible.builtin.paramiko_ssh (v2.16.5) — connection

Install Ansible via pip

Install with pip install ansible-core==2.16.5

Description

Use the Python SSH implementation (Paramiko) to connect to targets

The paramiko transport is provided because many distributions, in particular EL6 and before do not support ControlPersist in their SSH implementations.

This is needed on the Ansible control machine to be reasonably efficient with connections. Thus paramiko is faster for most users on these platforms. Users with ControlPersist capability can consider using -c ssh or configuring the transport in the configuration file.

This plugin also borrows a lot of settings from the ssh plugin as they both cover the same protocol.

Inputs

    
pty:
    default: true
    description: SUDO usually requires a PTY, True to give a PTY and False to not give
      a PTY.
    env:
    - name: ANSIBLE_PARAMIKO_PTY
    ini:
    - key: pty
      section: paramiko_connection
    type: boolean

port:
    default: 22
    description: Remote port to connect to.
    env:
    - name: ANSIBLE_REMOTE_PORT
    - name: ANSIBLE_REMOTE_PARAMIKO_PORT
      version_added: '2.15'
      version_added_collection: ansible.builtin
    ini:
    - key: remote_port
      section: defaults
    - key: remote_port
      section: paramiko_connection
      version_added: '2.15'
      version_added_collection: ansible.builtin
    keyword:
    - name: port
    type: int
    vars:
    - name: ansible_port
    - name: ansible_ssh_port
    - name: ansible_paramiko_port
      version_added: '2.15'
      version_added_collection: ansible.builtin

timeout:
    cli:
    - name: timeout
    default: 10
    description: Number of seconds until the plugin gives up on failing to establish a
      TCP connection.
    env:
    - name: ANSIBLE_TIMEOUT
    - name: ANSIBLE_SSH_TIMEOUT
      version_added: '2.11'
      version_added_collection: ansible.builtin
    - name: ANSIBLE_PARAMIKO_TIMEOUT
      version_added: '2.15'
      version_added_collection: ansible.builtin
    ini:
    - key: timeout
      section: defaults
    - key: timeout
      section: ssh_connection
      version_added: '2.11'
      version_added_collection: ansible.builtin
    - key: timeout
      section: paramiko_connection
      version_added: '2.15'
      version_added_collection: ansible.builtin
    type: int
    vars:
    - name: ansible_ssh_timeout
      version_added: '2.11'
      version_added_collection: ansible.builtin
    - name: ansible_paramiko_timeout
      version_added: '2.15'
      version_added_collection: ansible.builtin

password:
    description:
    - Secret used to either login the ssh server or as a passphrase for ssh keys that
      require it
    - Can be set from the CLI via the C(--ask-pass) option.
    type: string
    vars:
    - name: ansible_password
    - name: ansible_ssh_pass
    - name: ansible_ssh_password
    - name: ansible_paramiko_pass
    - name: ansible_paramiko_password
      version_added: '2.5'
      version_added_collection: ansible.builtin

ssh_args:
    default: ''
    deprecated:
      alternatives: proxy_command
      collection_name: ansible.builtin
      version: '2.18'
      why: In favor of the "proxy_command" option.
    description: Only used in parsing ProxyCommand for use in this plugin.
    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

remote_addr:
    default: inventory_hostname
    description:
    - Address of the remote target
    type: string
    vars:
    - name: inventory_hostname
    - name: ansible_host
    - name: ansible_ssh_host
    - name: ansible_paramiko_host

remote_user:
    description:
    - User to login/authenticate as
    - Can be set from the CLI via the C(--user) or C(-u) options.
    env:
    - name: ANSIBLE_REMOTE_USER
    - name: ANSIBLE_PARAMIKO_REMOTE_USER
      version_added: '2.5'
      version_added_collection: ansible.builtin
    ini:
    - key: remote_user
      section: defaults
    - key: remote_user
      section: paramiko_connection
      version_added: '2.5'
      version_added_collection: ansible.builtin
    keyword:
    - name: remote_user
    type: string
    vars:
    - name: ansible_user
    - name: ansible_ssh_user
    - name: ansible_paramiko_user

look_for_keys:
    default: true
    description: False to disable searching for private key files in ~/.ssh/
    env:
    - name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS
    ini:
    - key: look_for_keys
      section: paramiko_connection
    type: boolean

proxy_command:
    default: ''
    description:
    - Proxy information for running the connection via a jumphost
    - Also this plugin will scan 'ssh_args', 'ssh_extra_args' and 'ssh_common_args' from
      the 'ssh' plugin settings for proxy information if set.
    env:
    - name: ANSIBLE_PARAMIKO_PROXY_COMMAND
    ini:
    - key: proxy_command
      section: paramiko_connection
    type: string
    vars:
    - name: ansible_paramiko_proxy_command
      version_added: '2.15'
      version_added_collection: ansible.builtin

banner_timeout:
    default: 30
    description:
    - Configures, in seconds, the amount of time to wait for the SSH banner to be presented.
      This option is supported by paramiko version 1.15.0 or newer.
    env:
    - name: ANSIBLE_PARAMIKO_BANNER_TIMEOUT
    ini:
    - key: banner_timeout
      section: paramiko_connection
    type: float
    version_added: '2.14'
    version_added_collection: ansible.builtin

ssh_extra_args:
    cli:
    - name: ssh_extra_args
    default: ''
    deprecated:
      alternatives: proxy_command
      collection_name: ansible.builtin
      version: '2.18'
      why: In favor of the "proxy_command" option.
    description: Only used in parsing ProxyCommand for use in this plugin.
    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

ssh_common_args:
    cli:
    - name: ssh_common_args
    default: ''
    deprecated:
      alternatives: proxy_command
      collection_name: ansible.builtin
      version: '2.18'
      why: In favor of the "proxy_command" option.
    description: Only used in parsing ProxyCommand for use in this plugin.
    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

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
    - name: ANSIBLE_PARAMIKO_PRIVATE_KEY_FILE
      version_added: '2.15'
      version_added_collection: ansible.builtin
    ini:
    - key: private_key_file
      section: defaults
    - key: private_key_file
      section: paramiko_connection
      version_added: '2.15'
      version_added_collection: ansible.builtin
    type: string
    vars:
    - name: ansible_private_key_file
    - name: ansible_ssh_private_key_file
    - name: ansible_paramiko_private_key_file
      version_added: '2.15'
      version_added_collection: ansible.builtin

record_host_keys:
    default: true
    description: Save the host keys to a file
    env:
    - name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS
    ini:
    - key: record_host_keys
      section: paramiko_connection
    type: boolean

host_key_auto_add:
    description: Automatically add host keys
    env:
    - name: ANSIBLE_PARAMIKO_HOST_KEY_AUTO_ADD
    ini:
    - key: host_key_auto_add
      section: paramiko_connection
    type: boolean

host_key_checking:
    default: true
    description: Set this to "False" if you want to avoid host key checking by the underlying
      tools Ansible uses to connect to the host
    env:
    - name: ANSIBLE_HOST_KEY_CHECKING
    - name: ANSIBLE_SSH_HOST_KEY_CHECKING
      version_added: '2.5'
      version_added_collection: ansible.builtin
    - name: ANSIBLE_PARAMIKO_HOST_KEY_CHECKING
      version_added: '2.5'
      version_added_collection: ansible.builtin
    ini:
    - key: host_key_checking
      section: defaults
    - key: host_key_checking
      section: paramiko_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
    - name: ansible_paramiko_host_key_checking
      version_added: '2.5'
      version_added_collection: ansible.builtin

use_rsa_sha2_algorithms:
    default: true
    description:
    - Whether or not to enable RSA SHA2 algorithms for pubkeys and hostkeys
    - On paramiko versions older than 2.9, this only affects hostkeys
    - For behavior matching paramiko<2.9 set this to V(False)
    env:
    - name: ANSIBLE_PARAMIKO_USE_RSA_SHA2_ALGORITHMS
    ini:
    - key: use_rsa_sha2_algorithms
      section: paramiko_connection
    type: boolean
    vars:
    - name: ansible_paramiko_use_rsa_sha2_algorithms
    version_added: '2.14'
    version_added_collection: ansible.builtin

use_persistent_connections:
    default: false
    description: Toggles the use of persistence for connections
    env:
    - name: ANSIBLE_USE_PERSISTENT_CONNECTIONS
    ini:
    - key: use_persistent_connections
      section: defaults
    type: boolean