ansible / ansible.builtin / v2.16.5 / connection / winrm Run tasks over Microsoft's WinRM | "added in version" 2.0 of ansible.builtin" Authors: Ansible Core Teamansible.builtin.winrm (v2.16.5) — connection
pip
Install with pip install ansible-core==2.16.5
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_<option>).
path: default: /wsman description: URI path to connect to type: str vars: - name: ansible_winrm_path port: default: 5986 description: - port for winrm to connect on remote target - The default is the https (5986) port, if using http it should be 5985 keyword: - name: port type: integer vars: - name: ansible_port - name: ansible_winrm_port scheme: choices: - http - https description: - URI scheme to use - If not set, then will default to V(https) or V(http) if O(port) is V(5985). type: str vars: - name: ansible_winrm_scheme transport: description: - 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 elements: string type: list vars: - name: ansible_winrm_transport kinit_args: description: - 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. type: str vars: - name: ansible_winrm_kinit_args version_added: '2.11' version_added_collection: ansible.builtin pipelining: default: false description: - 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. env: - name: ANSIBLE_PIPELINING ini: - key: pipelining section: defaults - key: pipelining section: connection type: boolean vars: - name: ansible_pipelining remote_addr: default: inventory_hostname description: - Address of the windows machine type: str vars: - name: inventory_hostname - name: ansible_host - name: ansible_winrm_host remote_user: description: - The user to log in as to the Windows machine keyword: - name: remote_user type: str vars: - name: ansible_user - name: ansible_winrm_user kerberos_mode: choices: - managed - manual description: - 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 V(manual) and obtain it outside Ansible or install C(pexpect) through pip and try again. type: str vars: - name: ansible_winrm_kinit_mode kinit_env_vars: default: [] description: - 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. elements: str ini: - key: kinit_env_vars section: winrm type: list vars: - name: ansible_winrm_kinit_env_vars version_added: '2.12' version_added_collection: ansible.builtin remote_password: aliases: - password description: Authentication password for the O(remote_user). Can be supplied as CLI option. type: str vars: - name: ansible_password - name: ansible_winrm_pass - name: ansible_winrm_password kerberos_command: default: kinit description: kerberos command to use to request a authentication ticket type: str vars: - name: ansible_winrm_kinit_cmd connection_timeout: description: - 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 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. type: int vars: - name: ansible_winrm_connection_timeout