ansible.builtin.psrp (v2.9.0) — connection

Install Ansible via pip

Install with pip install ansible==2.9.0

Description

Run commands or put/fetch on a target via PSRP (WinRM plugin)

This is similar to the I(winrm) connection plugin which uses the same underlying transport but instead runs in a PowerShell interpreter.

Requirements

• pypsrp (Python library)

Inputs

    
auth:
    choices:
    - basic
    - certificate
    - negotiate
    - kerberos
    - ntlm
    - credssp
    default: negotiate
    description:
    - The authentication protocol to use when authenticating the remote user.
    - The default, C(negotiate), will attempt to use C(Kerberos) if it is available and
      fall back to C(NTLM) if it isn't.
    vars:
    - name: ansible_psrp_auth

path:
    default: wsman
    description:
    - The URI path to connect to.
    vars:
    - name: ansible_psrp_path

port:
    description:
    - The port for PSRP to connect on the remote target.
    - Default is C(5986) if I(protocol) is not defined or is C(https), otherwise the port
      is C(5985).
    vars:
    - name: ansible_port
    - name: ansible_psrp_port

proxy:
    description:
    - Set the proxy URL to use when connecting to the remote host.
    vars:
    - name: ansible_psrp_proxy

ca_cert:
    aliases:
    - cert_trust_path
    description:
    - The path to a PEM certificate chain to use when validating the server's certificate.
    - This value is ignored if I(cert_validation) is set to C(ignore).
    vars:
    - name: ansible_psrp_cert_trust_path
    - name: ansible_psrp_ca_cert

protocol:
    choices:
    - http
    - https
    description:
    - Set the protocol to use for the connection.
    - Default is C(https) if I(port) is not defined or I(port) is not C(5985).
    vars:
    - name: ansible_psrp_protocol

remote_addr:
    default: inventory_hostname
    description:
    - The hostname or IP address of the remote host.
    vars:
    - name: ansible_host
    - name: ansible_psrp_host

remote_user:
    description:
    - The user to log in as.
    vars:
    - name: ansible_user
    - name: ansible_psrp_user

ignore_proxy:
    default: 'no'
    description:
    - Will disable any environment proxy settings and connect directly to the remote host.
    - This option is ignored if C(proxy) is set.
    type: bool
    vars:
    - name: ansible_psrp_ignore_proxy

read_timeout:
    default: 30
    description:
    - The read timeout for receiving data from the remote host.
    - This value must always be greater than I(operation_timeout).
    - This option requires pypsrp >= 0.3.
    - This is measured in seconds.
    vars:
    - name: ansible_psrp_read_timeout
    version_added: '2.8'
    version_added_collection: ansible.builtin

cert_validation:
    choices:
    - validate
    - ignore
    default: validate
    description:
    - Whether to validate the remote server's certificate or not.
    - Set to C(ignore) to not validate any certificates.
    - I(ca_cert) can be set to the path of a PEM certificate chain to use in the validation.
    vars:
    - name: ansible_psrp_cert_validation

certificate_pem:
    description:
    - The local path to an X509 certificate to use with certificate auth.
    vars:
    - name: ansible_psrp_certificate_pem

max_envelope_size:
    default: 153600
    description:
    - Sets the maximum size of each WSMan message sent to the remote host.
    - This is measured in bytes.
    - Defaults to C(150KiB) for compatibility with older hosts.
    vars:
    - name: ansible_psrp_max_envelope_size

negotiate_service:
    default: WSMAN
    description:
    - Override the service part of the SPN used during Kerberos authentication.
    - Only valid when Kerberos was the negotiated auth or was explicitly set as the authentication.
    - Ignored when NTLM was the negotiated auth.
    vars:
    - name: ansible_psrp_negotiate_service

operation_timeout:
    default: 20
    description:
    - Sets the WSMan timeout for each operation.
    - This is measured in seconds.
    - This should not exceed the value for C(connection_timeout).
    vars:
    - name: ansible_psrp_operation_timeout

configuration_name:
    default: Microsoft.PowerShell
    description:
    - The name of the PowerShell configuration endpoint to connect to.
    vars:
    - name: ansible_psrp_configuration_name

connection_timeout:
    default: 30
    description:
    - The connection timeout for making the request to the remote host.
    - This is measured in seconds.
    vars:
    - name: ansible_psrp_connection_timeout

message_encryption:
    choices:
    - auto
    - always
    - never
    default: auto
    description:
    - Controls the message encryption settings, this is different from TLS encryption
      when I(ansible_psrp_protocol) is C(https).
    - Only the auth protocols C(negotiate), C(kerberos), C(ntlm), and C(credssp) can do
      message encryption. The other authentication protocols only support encryption when
      C(protocol) is set to C(https).
    - C(auto) means means message encryption is only used when not using TLS/HTTPS.
    - C(always) is the same as C(auto) but message encryption is always used even when
      running over TLS/HTTPS.
    - C(never) disables any encryption checks that are in place when running over HTTP
      and disables any authentication encryption processes.
    vars:
    - name: ansible_psrp_message_encryption

negotiate_delegate:
    description:
    - Allow the remote user the ability to delegate it's credentials to another server,
      i.e. credential delegation.
    - Only valid when Kerberos was the negotiated auth or was explicitly set as the authentication.
    - Ignored when NTLM was the negotiated auth.
    vars:
    - name: ansible_psrp_negotiate_delegate

negotiate_send_cbt:
    default: true
    description:
    - Send the Channel Binding Token (CBT) structure when authenticating.
    - CBT is used to provide extra protection against Man in the Middle C(MitM) attacks
      by binding the outer transport channel to the auth channel.
    - CBT is not used when using just C(HTTP), only C(HTTPS).
    type: bool
    vars:
    - name: ansible_psrp_negotiate_send_cbt

certificate_key_pem:
    description:
    - The local path to an X509 certificate key to use with certificate auth.
    vars:
    - name: ansible_psrp_certificate_key_pem

reconnection_backoff:
    default: 2
    description:
    - The backoff time to use in between reconnection attempts. (First sleeps X, then
      sleeps 2*X, then sleeps 4*X, ...)
    - This is measured in seconds.
    - The C(ansible_psrp_reconnection_backoff) variable was added in Ansible 2.9.
    vars:
    - name: ansible_psrp_connection_backoff
    - name: ansible_psrp_reconnection_backoff
    version_added: '2.8'
    version_added_collection: ansible.builtin

reconnection_retries:
    default: 0
    description:
    - The number of retries on connection errors.
    vars:
    - name: ansible_psrp_reconnection_retries
    version_added: '2.8'
    version_added_collection: ansible.builtin

credssp_auth_mechanism:
    choices:
    - auto
    - kerberos
    - ntlm
    default: auto
    description:
    - The sub authentication mechanism to use with CredSSP auth.
    - When C(auto), both Kerberos and NTLM is attempted with kerberos being preferred.
    vars:
    - name: ansible_psrp_credssp_auth_mechanism

credssp_disable_tlsv1_2:
    default: false
    description:
    - Disables the use of TLSv1.2 on the CredSSP authentication channel.
    - This should not be set to C(yes) unless dealing with a host that does not have TLSv1.2.
    type: bool
    vars:
    - name: ansible_psrp_credssp_disable_tlsv1_2

credssp_minimum_version:
    default: 2
    description:
    - The minimum CredSSP server authentication version that will be accepted.
    - Set to C(5) to ensure the server has been patched and is not vulnerable to CVE 2018-0886.
    type: int
    vars:
    - name: ansible_psrp_credssp_minimum_version

negotiate_hostname_override:
    description:
    - Override the remote hostname when searching for the host in the Kerberos lookup.
    - This allows Ansible to connect over IP but authenticate with the remote server using
      it's DNS name.
    - Only valid when Kerberos was the negotiated auth or was explicitly set as the authentication.
    - Ignored when NTLM was the negotiated auth.
    vars:
    - name: ansible_psrp_negotiate_hostname_override