ansible.builtin.winrm – Run tasks over Microsoft’s WinRM

Note

This connection plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name winrm even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same connection plugin name.

New in version 2.0: of ansible.builtin

Synopsis

  • Run commands or put/fetch on a target via WinRM

  • This plugin allows extra arguments to be passed that are supported by the protocol but not explicitly defined here. They should take the form of variables declared with the following pattern ansible_winrm_<option>.

Requirements

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

  • pywinrm (python library)

Parameters

Parameter

Comments

connection_timeout

integer

Sets the operation and read timeout settings for the WinRM connection.

Corresponds to the operation_timeout_sec and read_timeout_sec args in pywinrm so avoid setting these vars with this one.

The default value is whatever is set in the installed version of pywinrm.

Configuration:

  • Variable: ansible_winrm_connection_timeout

kerberos_command

string

kerberos command to use to request a authentication ticket

Default: “kinit”

Configuration:

  • Variable: ansible_winrm_kinit_cmd

kerberos_mode

string

kerberos usage mode.

The managed option means Ansible will obtain kerberos ticket.

While the manual one means a ticket must already have been obtained by the user.

If having issues with Ansible freezing when trying to obtain the Kerberos ticket, you can either set this to manual and obtain it outside Ansible or install pexpect through pip and try again.

Choices:

  • managed

  • manual

Configuration:

  • Variable: ansible_winrm_kinit_mode

kinit_args

string

added in 2.11 of ansible.builtin

Extra arguments to pass to kinit when getting the Kerberos authentication ticket.

By default no extra arguments are passed into kinit unless ansible_winrm_kerberos_delegation is also set. In that case -f is added to the kinit args so a forwardable ticket is retrieved.

If set, the args will overwrite any existing defaults for kinit, including -f for a delegated ticket.

Configuration:

  • Variable: ansible_winrm_kinit_args

path

string

URI path to connect to

Default: “/wsman”

Configuration:

  • Variable: ansible_winrm_path

pipelining

boolean

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.

Choices:

  • no

  • yes

Default: “ANSIBLE_PIPELINING”

Configuration:

  • INI entry:

    [defaults]
pipelining = ANSIBLE_PIPELINING

  • Environment variable: ANSIBLE_PIPELINING

  • Variable: ansible_pipelining

port

integer

port for winrm to connect on remote target

The default is the https (5986) port, if using http it should be 5985

Default: 5986

Configuration:

  • Variable: ansible_port

  • Variable: ansible_winrm_port

remote_addr

string

Address of the windows machine

Default: “inventory_hostname”

Configuration:

  • Variable: ansible_host

  • Variable: ansible_winrm_host

remote_password

aliases: password

string

Authentication password for the remote_user. Can be supplied as CLI option.

Configuration:

  • Variable: ansible_password

  • Variable: ansible_winrm_pass

  • Variable: ansible_winrm_password

remote_user

string

The user to log in as to the Windows machine

Configuration:

  • Variable: ansible_user

  • Variable: ansible_winrm_user

scheme

string

URI scheme to use

If not set, then will default to https or http if port is 5985.

Choices:

  • http

  • https

Configuration:

  • Variable: ansible_winrm_scheme

transport

list / elements=string

List of winrm transports to attempt to use (ssl, plaintext, kerberos, etc)

If None (the default) the plugin will try to automatically guess the correct list

The choices available depend on your version of pywinrm

Configuration:

  • Variable: ansible_winrm_transport

Authors

  • Ansible Core Team