ansible.builtin.winrm connection – 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. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.winrm for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same connection plugin name.

Synopsis

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

Requirements

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

  • pywinrm (python library)

Parameters

Parameter

Comments

ca_trust_path

path

The path to a PEM encoded CA bundle or an OpenSSL CA directory to use when validating the server certificate.

If not set, the REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE environment variables are used if present, falling back to the default CA trust store of the requests Python library.

This option is ignored if server_cert_validation is ignore.

Configuration:

  • Variable: ansible_winrm_ca_trust_path

cert_key_pem

path

The path to a PEM encoded private key to use for authentication when transport is certificate.

The private key must not be encrypted as pywinrm only supports plaintext keys.

Use cert_pem to specify the path to the PEM encoded certificate for this key.

Configuration:

  • Variable: ansible_winrm_cert_key_pem

cert_pem

path

The path to a PEM encoded certificate to use for authentication when transport is certificate.

Use cert_key_pem to specify the path to the PEM encoded private key for this certificate.

Configuration:

  • Variable: ansible_winrm_cert_pem

connection_timeout

integer

Despite its name, sets both the ‘operation’ and ‘read’ timeout settings for the WinRM connection.

The operation timeout belongs to the WS-Man layer and runs on the winRM-service on the managed windows host.

The read timeout belongs to the underlying python Request call (http-layer) and runs on the ansible controller.

The operation timeout sets the WS-Man ‘Operation timeout’ that runs on the managed windows host. The operation timeout specifies how long a command will run on the winRM-service before it sends the message ‘WinRMOperationTimeoutError’ back to the client. The client (silently) ignores this message and starts a new instance of the operation timeout, waiting for the command to finish (long running commands).

The read timeout sets the client HTTP-request timeout and specifies how long the client (ansible controller) will wait for data from the server to come back over the HTTP-connection (timeout for waiting for in-between messages from the server). When this timer expires, an exception will be thrown and the ansible connection will be terminated with the error message ‘Read timed out’

To avoid the above exception to be thrown, the read timeout will be set to 10 seconds higher than the WS-Man operation timeout, thus make the connection more robust on networks with long latency and/or many hops between server and client network wise.

Setting the difference between the operation and the read timeout to 10 seconds aligns it to the defaults used in the winrm-module and the PSRP-module which also uses 10 seconds (30 seconds for read timeout and 20 seconds for operation timeout)

If set, this overrides both operation_timeout_sec and read_timeout_sec so avoid setting those options with this one.

Configuration:

  • Variable: ansible_winrm_connection_timeout

credssp_disable_tlsv1_2

boolean

Removed in: version 2.26

Why: All supported Windows versions support TLSv1.2 so there is no longer a reason to disable it.

Alternative: Remove the option, TLSv1.2 is always used for the CredSSP authentication channel.

Disables the use of TLSv1.2 on the CredSSP authentication channel when transport is credssp.

Choices:

  • false ← (default)

  • true

Configuration:

  • Variable: ansible_winrm_credssp_disable_tlsv1_2

kerberos_command

string

kerberos command to use to request a authentication ticket

Default: "kinit"

Configuration:

  • Variable: ansible_winrm_kinit_cmd

kerberos_delegation

boolean

Requests a forwardable Kerberos ticket so the credentials can be delegated to another server from the Windows host, also known as unconstrained delegation.

This can be used to overcome the double hop problem with WinRM.

If kerberos_mode is manual, the ticket obtained by the user must already be forwardable for delegation to work.

Choices:

  • false ← (default)

  • true

Configuration:

  • Variable: ansible_winrm_kerberos_delegation

kerberos_hostname_override

string

The hostname to use in the Service Principal Name (SPN) when requesting the Kerberos service ticket.

By default the hostname from remote_addr is used. This allows Ansible to connect to an IP address or alias but authenticate using the DNS name of the Windows host.

Only used when transport is kerberos.

Configuration:

  • Variable: ansible_winrm_kerberos_hostname_override

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.

Choices:

  • "managed"

  • "manual"

Configuration:

  • Variable: ansible_winrm_kinit_mode

kerberos_service

string

The service part of the Service Principal Name (SPN) used when requesting the Kerberos service ticket.

Only used when transport is kerberos.

Default: "HTTP"

Configuration:

  • Variable: ansible_winrm_service

  • Variable: ansible_winrm_kerberos_service

kinit_args

string

added in ansible-core 2.11

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

By default no extra arguments are passed into kinit unless 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

kinit_env_vars

list / elements=string

added in ansible-core 2.12

A list of environment variables to pass through to kinit when getting the Kerberos authentication ticket.

By default no environment variables are passed through and kinit is run with a blank slate.

The environment variable KRB5CCNAME cannot be specified here as it’s used to store the temp Kerberos ticket used by WinRM.

Default: []

Configuration:

  • INI entry:

    [winrm]
kinit_env_vars =

  • Variable: ansible_winrm_kinit_env_vars

message_encryption

string

Controls WinRM message encryption, which is separate from the TLS encryption used when scheme is https.

Only the ntlm, kerberos, and credssp transports support message encryption.

auto uses message encryption only when connecting over http with a transport that supports it. Over https the TLS layer already encrypts the data.

always requires message encryption even over https and will fail if the transport does not support it, for example basic or certificate.

never disables message encryption even over http. This is only recommended for debugging as all data will be sent in the clear.

Choices:

  • "auto" ← (default)

  • "always"

  • "never"

Configuration:

  • Variable: ansible_winrm_message_encryption

operation_timeout_sec

integer

The WS-Man operation timeout in seconds that runs on the managed Windows host.

This value must be less than read_timeout_sec.

See connection_timeout for more information on how the operation and read timeouts interact.

This option is ignored if connection_timeout is set.

Default: 20

Configuration:

  • Variable: ansible_winrm_operation_timeout_sec

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:

  • false ← (default)

  • true

Configuration:

  • INI entries:

    [defaults]
pipelining = false

    [connection]
pipelining = false

  • 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:

  • Keyword: port

  • Variable: ansible_port

  • Variable: ansible_winrm_port

proxy

string

The proxy URL to use when connecting to the Windows host.

If not set, the proxy settings from the environment are used.

Set to the string None to disable the use of any proxy, including any proxy settings from the environment.

Configuration:

  • Variable: ansible_winrm_proxy

read_timeout_sec

integer

The HTTP read timeout in seconds that the Ansible controller will wait for a response from the Windows host.

This value must be greater than operation_timeout_sec.

See connection_timeout for more information on how the operation and read timeouts interact.

This option is ignored if connection_timeout is set.

Default: 30

Configuration:

  • Variable: ansible_winrm_read_timeout_sec

remote_addr

string

Address of the windows machine

Default: "inventory_hostname"

Configuration:

  • Variable: inventory_hostname

  • 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

If transport is not defined, the authentication used will be kerberos if the user is in the UPN format user@domain, otherwise it will be basic

Configuration:

  • Keyword: remote_user

  • 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

send_cbt

boolean

Sends the Channel Binding Token (CBT) when authenticating with the ntlm or kerberos transports over https.

CBT binds the TLS channel to the authentication exchange to protect against man in the middle attacks.

This should only be disabled for debugging purposes.

Choices:

  • false

  • true ← (default)

Configuration:

  • Variable: ansible_winrm_send_cbt

server_cert_validation

string

The HTTPS server certificate validation behaviour.

validate will validate the server certificate against the CA trust store and check that the certificate matches the hostname requested.

ignore will skip all certificate validation checks. This is not recommended outside of testing as it disables the server identity verification checks.

ca_trust_path can be used to specify a custom CA trust store to use for the validation.

Choices:

  • "validate" ← (default)

  • "ignore"

Configuration:

  • Variable: ansible_winrm_server_cert_validation

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. It will use kerberos if the username looks like a UPN user@domain, otherwise it will use basic.

basic is Basic authentication which only works for local accounts.

certificate is Certificate authentication which only works for local accounts and over HTTPS endpoints.

ntlm is NTLM authentication and works for both local and domain accounts. NTLM is an older protocol and should only be used over HTTPS endpoints.

kerberos is Kerberos authentication which only works for domain accounts. This is a secure protocol and is safe to use over HTTP.

credssp is CredSSP authentication which works for both local and domain accounts. It will delegate the user’s credentials to the remote server, only use if the target host is trusted.

plaintext is an alias for basic authentication over HTTP.

ssl is an alias for basic over HTTPS or certificate if cert_pem is set.

Choices:

  • "basic"

  • "certificate"

  • "ntlm"

  • "kerberos"

  • "credssp"

  • "plaintext"

  • "ssl"

Configuration:

  • Variable: ansible_winrm_transport

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

Authors

  • Ansible Core Team