community.general.wsl connection – Run tasks in WSL distribution using wsl.exe CLI via SSH

Note

This connection plugin is part of the community.general collection (version 10.7.3).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this connection plugin, see Requirements for details.

To use it in a playbook, specify: community.general.wsl.

New in community.general 10.6.0

Synopsis

  • Run commands or put/fetch files to an existing WSL distribution using wsl.exe CLI via SSH.
  • Uses the Python SSH implementation (Paramiko) to connect to the WSL host.

Requirements

The below requirements are needed on the local controller node that executes this connection.

  • paramiko

Parameters

Parameter

Comments

banner_timeout

float

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.

Default: 30.0

Configuration:

become

boolean

whether to use the user defined by ansible_become_user.

Choices:

  • false ← (default)
  • true

Configuration:

  • Variable: become
  • Variable: ansible_become

become_user

string

WSL distribution user

Default: "root"

Configuration:

  • Variable: become_user
  • Variable: ansible_become_user

host_key_auto_add

boolean

Automatically add host keys to ~/.ssh/known_hosts.

Choices:

  • false
  • true

Configuration:

host_key_checking

boolean

Set this to false if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host.

Choices:

  • false
  • true ← (default)

Configuration:

lock_file_timeout

integer

Number of seconds until the plugin gives up on trying to write a lock file when writing SSH known host keys.

Default: 60

Configuration:

look_for_keys

boolean

Set to false to disable searching for private key files in ~/.ssh/.

Choices:

  • false
  • true ← (default)

Configuration:

password

string

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 --ask-pass option.

Configuration:

  • Variable: ansible_password
  • Variable: ansible_ssh_pass
  • Variable: ansible_ssh_password
  • Variable: ansible_paramiko_pass
  • Variable: ansible_paramiko_password

port

integer

Remote port to connect to.

Default: 22

Configuration:

  • INI entries:

    [defaults]
remote_port = 22

    [paramiko_connection]
remote_port = 22
  • Environment variable: ANSIBLE_REMOTE_PORT
  • Environment variable: ANSIBLE_REMOTE_PARAMIKO_PORT
  • Keyword: port
  • Variable: ansible_port
  • Variable: ansible_ssh_port
  • Variable: ansible_paramiko_port

private_key_file

path

Path to private key file to use for authentication.

Configuration:

  • INI entries:

    [defaults]
private_key_file = VALUE

    [paramiko_connection]
private_key_file = VALUE
  • Environment variable: ANSIBLE_PRIVATE_KEY_FILE
  • Environment variable: ANSIBLE_PARAMIKO_PRIVATE_KEY_FILE
  • CLI argument: –private-key
  • Variable: ansible_private_key_file
  • Variable: ansible_ssh_private_key_file
  • Variable: ansible_paramiko_private_key_file

proxy_command

string

Proxy information for running the connection via a jumphost.

This option is supported by paramiko version 1.9.0 or newer.

Default: ""

Configuration:

record_host_keys

boolean

Save the host keys to a file.

Choices:

  • false
  • true ← (default)

Configuration:

remote_addr

string

Address of the remote target.

Default: "inventory_hostname"

Configuration:

  • Variable: inventory_hostname
  • Variable: ansible_host
  • Variable: ansible_ssh_host
  • Variable: ansible_paramiko_host

remote_user

string

User to login/authenticate as.

Can be set from the CLI via the --user or -u options.

Configuration:

  • INI entries:

    [defaults]
remote_user = VALUE

    [paramiko_connection]
remote_user = VALUE
  • Environment variable: ANSIBLE_REMOTE_USER
  • Environment variable: ANSIBLE_PARAMIKO_REMOTE_USER
  • Keyword: remote_user
  • Variable: ansible_user
  • Variable: ansible_ssh_user
  • Variable: ansible_paramiko_user

timeout

integer

Number of seconds until the plugin gives up on failing to establish a TCP connection.

This option is supported by paramiko version 2.2.0 or newer.

Default: 10

Configuration:

  • INI entries:

    [defaults]
timeout = 10

    [ssh_connection]
timeout = 10

    [paramiko_connection]
timeout = 10
  • Environment variable: ANSIBLE_TIMEOUT
  • Environment variable: ANSIBLE_SSH_TIMEOUT
  • Environment variable: ANSIBLE_PARAMIKO_TIMEOUT
  • CLI argument: –timeout
  • Variable: ansible_ssh_timeout
  • Variable: ansible_paramiko_timeout

use_persistent_connections

boolean

Toggles the use of persistence for connections.

Choices:

  • false ← (default)
  • true

Configuration:

use_rsa_sha2_algorithms

boolean

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 false.

Choices:

  • false
  • true ← (default)

Configuration:

user_known_hosts_file

path

Path to the user known hosts file.

Used to verify the ssh hosts keys.

Default: "~/.ssh/known_hosts"

Configuration:

  • INI entry:

    [paramiko_connection]
user_known_hosts_file = ~/.ssh/known_hosts
  • Variable: ansible_paramiko_user_known_hosts_file

wsl_distribution

string / required

WSL distribution name

Configuration:

  • Variable: wsl_distribution

wsl_user

string

WSL distribution user

Configuration:

  • Variable: wsl_user

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Examples

# ------------------------
# Inventory: inventory.yml
# ------------------------
---
all:
  children:
    wsl:
      hosts:
        example-wsl-ubuntu:
          ansible_host: 10.0.0.10
          wsl_distribution: ubuntu
          wsl_user: ubuntu
      vars:
        ansible_connection: community.general.wsl
        ansible_user: vagrant
# ----------------------
# Playbook: playbook.yml
# ----------------------
---
- name: WSL Example
  hosts: wsl
  gather_facts: true
  become: true
  tasks:
    - name: Ping
      ansible.builtin.ping:
    - name: Id (with become false)
      become: false
      changed_when: false
      args:
        executable: /bin/bash
      ansible.builtin.shell: |
        exec 2>&1
        set -x
        echo "$0"
        pwd
        id
    - name: Id (with become true)
      changed_when: false
      args:
        executable: /bin/bash
      ansible.builtin.shell: |
        exec 2>&1
        set -x
        echo "$0"
        pwd
        id
    - name: Reboot
      ansible.builtin.reboot:
        boot_time_command: systemctl show -p ActiveEnterTimestamp init.scope

Authors

  • Rui Lopes (@rgl) <ruilopes.com>

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/wsl_connection.html