winrm¶
Collection Note
This module is part of the ansible.builtin collection. To install the collection, use:
Added in version2.0.
You need further requirements to be able to use this module, see the Requirements section for details.
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 C(ansible_winrm_
Requirements¶
The following Python packages are needed on the host that executes this module:
Parameters¶
| Parameter | Defaults / Choices | Comments |
|---|---|---|
| connection_timeout int |
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) Corresponds to the C(operation_timeout_sec) and C(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. |
|
| kerberos_command str |
Default: kinit |
kerberos command to use to request a authentication ticket |
| kerberos_mode str |
Choices: managed, manual | 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. |
| kinit_args str |
Extra arguments to pass to C(kinit) when getting the Kerberos authentication ticket. By default no extra arguments are passed into C(kinit) unless I(ansible_winrm_kerberos_delegation) is also set. In that case C(-f) is added to the C(kinit) args so a forwardable ticket is retrieved. If set, the args will overwrite any existing defaults for C(kinit), including C(-f) for a delegated ticket. Version Added: 2.11 |
|
| kinit_env_vars list / elements=str |
A list of environment variables to pass through to C(kinit) when getting the Kerberos authentication ticket. By default no environment variables are passed through and C(kinit) is run with a blank slate. The environment variable C(KRB5CCNAME) cannot be specified here as it's used to store the temp Kerberos ticket used by WinRM. Version Added: 2.12 |
|
| path str |
Default: /wsman |
URI path to connect to |
| 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 (C(become)). For example, when using sudo operations you must first disable C(requiretty) in the sudoers file for the target hosts, which is why this feature is disabled by default. Env: ANSIBLE_PIPELINING |
|
| port integer |
Default: 5986 |
port for winrm to connect on remote target The default is the https (5986) port, if using http it should be 5985 |
| remote_addr str |
Default: inventory_hostname |
Address of the windows machine |
| remote_password str |
Authentication password for the O(remote_user). Can be supplied as CLI option. | |
| remote_user str |
The user to log in as to the Windows machine If O(transport) is not defined, the authentication used will be V(kerberos) if the user is in the UPN format V(user@domain), otherwise it will be V(basic) |
|
| scheme str |
Choices: http, https | URI scheme to use If not set, then will default to V(https) or V(http) if O(port) is V(5985). |
| 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 V(kerberos) if the username looks like a UPN V(user@domain), otherwise it will use V(basic). The choices available depend on your version of pywinrm |
Authors¶
- Ansible Core Team