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
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 |
---|---|
Sets the operation and read timeout settings for the WinRM connection. Corresponds to the The default value is whatever is set in the installed version of pywinrm. Configuration:
|
|
kerberos command to use to request a authentication ticket Default: “kinit” Configuration:
|
|
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 Choices:
Configuration:
|
|
Extra arguments to pass to By default no extra arguments are passed into If set, the args will overwrite any existing defaults for Configuration:
|
|
A list of environment variables to pass through to By default no environment variables are passed through and The environment variable Default: [] Configuration:
|
|
URI path to connect to Default: “/wsman” Configuration:
|
|
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:
Default: “ANSIBLE_PIPELINING” Configuration:
|
|
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:
|
|
Address of the windows machine Default: “inventory_hostname” Configuration:
|
|
Authentication password for the Configuration:
|
|
The user to log in as to the Windows machine Configuration:
|
|
URI scheme to use If not set, then will default to Choices:
Configuration:
|
|
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:
|
Authors
Ansible Core Team
Hint
Configuration entries for each entry type 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.