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
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 |
|---|---|
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 bewteen the operation and the read timeout to 10 seconds alligns 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) 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: 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: 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:
Configuration:
|
|
port for winrm to connect on remote target The default is the https (5986) port, if using http it should be 5985 Default: Configuration:
|
|
Address of the windows machine Default: 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:
|