ansible.builtin.winrm (v2.16.5) — connection

Install Ansible via pip

Install with pip install ansible-core==2.16.5

Description

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

Requirements

• pywinrm (python library)

Inputs

    
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