Setting up a Windows Host — Ansible Community Documentation (2024)

Upgrading PowerShell and .NET Framework

Ansible requires PowerShell version 5.1 and .NET Framework 4.6 or newer to function. The base image for older unsupported OS’ does not meet theserequirements. You can use the Upgrade-PowerShell.ps1 script to update these.

This is an example of how to run this script from PowerShell:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12$url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Upgrade-PowerShell.ps1"$file = "$env:temp\Upgrade-PowerShell.ps1"$username = "Administrator"$password = "Password"(New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file)Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force&$file -Version 5.1 -Username $username -Password $password -Verbose

In the script, the file value can be the PowerShell version 3.0, 4.0, or 5.1.

Once completed, you need to run the following PowerShell commands:

1. As an optional but good security practice, you can set the execution policy back to the default.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force

Use the RemoteSigned value for Windows servers, or Restricted for Windows clients.

2. Remove the auto logon.

$reg_winlogon_path = "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon"Set-ItemProperty -Path $reg_winlogon_path -Name AutoAdminLogon -Value 0Remove-ItemProperty -Path $reg_winlogon_path -Name DefaultUserName -ErrorAction SilentlyContinueRemove-ItemProperty -Path $reg_winlogon_path -Name DefaultPassword -ErrorAction SilentlyContinue

The script determines what programs you need to install (such as .NET Framework 4.5.2) and what PowerShell version needs to be present. If a reboot is needed and the username and password parameters are set, the script will automatically reboot the machine and then logon. If the username and password parameters are not set, the script will prompt the user to manually reboot and logon when required. When the user is next logged in, the script will continue where it left off and the process continues until no moreactions are required.

WinRM Memory Hotfix

On PowerShell v3.0, there is a bug that limits the amount of memory available to the WinRM service. Use the Install-WMF3Hotfix.ps1 script to install a hotfix on affected hosts as part of the system bootstrapping or imaging process. Without this hotfix, Ansible fails to execute certain commands on the Windows host.

To install the hotfix:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12$url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Install-WMF3Hotfix.ps1"$file = "$env:temp\Install-WMF3Hotfix.ps1"(New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file)powershell.exe -ExecutionPolicy ByPass -File $file -Verbose

For more details, refer to the “Out of memory” error on a computer that has a customized MaxMemoryPerShellMB quota set and has WMF 3.0 installed article.

WinRM Listener

The WinRM services listen for requests on one or more ports. Each of these ports must have a listener created and configured.

To view the current listeners that are running on the WinRM service:

winrm enumerate winrm/config/Listener

This will output something like:

Listener Address = * Transport = HTTP Port = 5985 Hostname Enabled = true URLPrefix = wsman CertificateThumbprint ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80::ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7Listener Address = * Transport = HTTPS Port = 5986 Hostname = SERVER2016 Enabled = true URLPrefix = wsman CertificateThumbprint = E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80::ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7

In the example above there are two listeners activated. One is listening on port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of the key options that are useful to understand are:

• Transport: Whether the listener is run over HTTP or HTTPS. We recommend you use a listener over HTTPS because the data is encrypted without any further changes required.

• Port: The port the listener runs on. By default, it is 5985 for HTTP and 5986 for HTTPS. This port can be changed to whatever is required and corresponds to the host var ansible_port.

• URLPrefix: The URL prefix to listen on. By default, it is wsman. If you change this option, you need to set the host var ansible_winrm_path to the same value.

• CertificateThumbprint: If you use an HTTPS listener, this is the thumbprint of the certificate in the Windows Certificate Store that is used in the connection. To get the details of the certificate itself, run this command with the relevant certificate thumbprint in PowerShell:

$thumbprint = "E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE"Get-ChildItem -Path cert:\LocalMachine\My -Recurse | Where-Object { $_.Thumbprint -eq $thumbprint } | Select-Object *

Remove-Item -Path WSMan:\localhost\Listener\* -Recurse -Force

Get-ChildItem -Path WSMan:\localhost\Listener | Where-Object { $_.Keys -contains "Transport=HTTPS" } | Remove-Item -Recurse -Force

WinRM Service Options

You can control the behavior of the WinRM service component, including authentication options and memory settings.

To get an output of the current service configuration options, run the following command:

winrm get winrm/config/Servicewinrm get winrm/config/Winrs

This will output something like:

Service RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD) MaxConcurrentOperations = 4294967295 MaxConcurrentOperationsPerUser = 1500 EnumerationTimeoutms = 240000 MaxConnections = 300 MaxPacketRetrievalTimeSeconds = 120 AllowUnencrypted = false Auth Basic = true Kerberos = true Negotiate = true Certificate = true CredSSP = true CbtHardeningLevel = Relaxed DefaultPorts HTTP = 5985 HTTPS = 5986 IPv4Filter = * IPv6Filter = * EnableCompatibilityHttpListener = false EnableCompatibilityHttpsListener = false CertificateThumbprint AllowRemoteAccess = trueWinrs AllowRemoteShellAccess = true IdleTimeout = 7200000 MaxConcurrentUsers = 2147483647 MaxShellRunTime = 2147483647 MaxProcessesPerShell = 2147483647 MaxMemoryPerShellMB = 2147483647 MaxShellsPerUser = 2147483647

You do not need to change the majority of these options. However, some of the important ones to know about are:

• Service\AllowUnencrypted - specifies whether WinRM will allow HTTP traffic without message encryption. Message level encryption is only possible when the ansible_winrm_transport variable is ntlm, kerberos or credssp. By default, this is false and you should only set it to true when debugging WinRM messages.

• Service\Auth\* - defines what authentication options you can use with the WinRM service. By default, Negotiate (NTLM) and Kerberos are enabled.

• Service\Auth\CbtHardeningLevel - specifies whether channel binding tokens are not verified (None), verified but not required (Relaxed), or verified and required (Strict). CBT is only used when connecting with NT LAN Manager (NTLM) or Kerberos over HTTPS.

• Service\CertificateThumbprint - thumbprint of the certificate for encrypting the TLS channel used with CredSSP authentication. By default, this is empty. A self-signed certificate is generated when the WinRM service starts and is used in the TLS process.

  See Also

  Ansible for the Windows admin

• Winrs\MaxShellRunTime - maximum time, in milliseconds, that a remote command is allowed to execute.

• Winrs\MaxMemoryPerShellMB - maximum amount of memory allocated per shell, including its child processes.

To modify a setting under the Service key in PowerShell, you need to provide a path to the option after winrm/config/Service:

Set-Item -Path WSMan:\localhost\Service\{path} -Value {some_value}

For example, to change Service\Auth\CbtHardeningLevel:

Set-Item -Path WSMan:\localhost\Service\Auth\CbtHardeningLevel -Value Strict

To modify a setting under the Winrs key in PowerShell, you need to provide a path to the option after winrm/config/Winrs:

Set-Item -Path WSMan:\localhost\Shell\{path} -Value {some_value}

For example, to change Winrs\MaxShellRunTime:

Set-Item -Path WSMan:\localhost\Shell\MaxShellRunTime -Value 2147483647

Common WinRM Issues

WinRM has a wide range of configuration options, which makes its configuration complex. As a result, errors that Ansible displays could in fact be problems with the host setup instead.

To identify a host issue, run the following command from another Windows host to connect to the target Windows host.

• To test HTTP:

winrs -r:http://server:5985/wsman -u:Username -p:Password ipconfig

• To test HTTPS:

winrs -r:https://server:5986/wsman -u:Username -p:Password -ssl ipconfig

The command will fail if the certificate is not verifiable.

• To test HTTPS ignoring certificate verification:

$username = "Username"$password = ConvertTo-SecureString -String "Password" -AsPlainText -Force$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $password$session_option = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheckInvoke-Command -ComputerName server -UseSSL -ScriptBlock { ipconfig } -Credential $cred -SessionOption $session_option

If any of the above commands fail, the issue is probably related to the WinRM setup.

The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded.

Installing OpenSSH using Windows Settings

You can use OpenSSH to connect Windows 10 clients to Windows Server 2019. OpenSSH Client is available to install on Windows 10 build 1809 and later. OpenSSH Server is available to install on Windows Server 2019 and later.

For more information, refer to Get started with OpenSSH for Windows.

Installing Win32-OpenSSH

To install the Win32-OpenSSH service for use withAnsible, select one of these installation options:

• Manually install Win32-OpenSSH, following the install instructions from Microsoft.

• Use Chocolatey:

choco install --package-parameters=/SSHServerFeature openssh

• Use the win_chocolatey Ansible module:

- name: install the Win32-OpenSSH service win_chocolatey: name: openssh package_params: /SSHServerFeature state: present

• Install an Ansible Galaxy role for example jborean93.win_openssh:

ansible-galaxy install jborean93.win_openssh

• Use the role in your playbook:

- name: install Win32-OpenSSH service hosts: windows gather_facts: false roles: - role: jborean93.win_openssh opt_openssh_setup_service: True

Configuring the Win32-OpenSSH shell

By default, Win32-OpenSSH uses cmd.exe as a shell.

• To configure a different shell, use an Ansible playbook with a task to define the registry setting:

- name: set the default shell to PowerShell win_regedit: path: HKLM:\SOFTWARE\OpenSSH name: DefaultShell data: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe type: string state: present

• To revert the settings to the default shell:

- name: set the default shell to cmd win_regedit: path: HKLM:\SOFTWARE\OpenSSH name: DefaultShell state: absent

Win32-OpenSSH Authentication

Win32-OpenSSH authentication with Windows is similar to SSH authentication on Unix/Linux hosts. You can use a plaintext password or SSH public key authentication.

For the key-based authentication:

• Add your public keys to an authorized_key file in the .ssh folder of the user’s profile directory.

• Configure the SSH service using the sshd_config file.

When using SSH key authentication with Ansible, the remote session will not have access to user credentials and will fail when attempting to access a network resource. This is also known as the double-hop or credential delegation issue. To work around this problem:

• Use plaintext password authentication by setting the ansible_password variable.

• Use the become directive on the task with the credentials of the user that needs access to the remote resource.

Configuring Ansible for SSH on Windows

To configure Ansible to use SSH for Windows hosts, you must set two connection variables:

• set ansible_connection to ssh

• set ansible_shell_type to cmd or powershell

The ansible_shell_type variable should reflect the DefaultShell configured on the Windows host. Set ansible_shell_type to cmd for the default shell. Alternatively, set ansible_shell_type to powershell if you changed DefaultShell to PowerShell.

Known issues with SSH on Windows

Using SSH with Windows is experimental. Currently, existing issues are:

• Win32-OpenSSH versions older than v7.9.0.0p1-Beta do not work when powershell is the shell type.

• While Secure Copy Protocol (SCP) should work, SSH File Transfer Protocol (SFTP) is the recommended mechanism to use when copying or fetching a file.