Настройка хоста Windows

В этом документе обсуждается настройка, необходимая перед тем, как Ansible сможет взаимодействовать с хостом Microsoft Windows.

• Требования к хосту
  • Обновление PowerShell и .NET Framework
  • Исправление памяти WinRM
• Настройка WinRM
  • Слушатель WinRM
    • Настройка слушателя WinRM
    • Удаление слушателя WinRM
  • Параметры службы WinRM
  • Общие проблемы с WinRM
    • HTTP 401/Отклонены учетные данные
    • Ошибка HTTP 500
    • Ошибки таймаута
    • Ошибки «Подключение отклонено»

Требования к хосту

Для взаимодействия Ansible с хостом Windows и использования модулей Windows, хост Windows должен соответствовать следующим требованиям:

• Поддерживаемые версии Windows Ansible, как правило, соответствуют версиям с текущей и расширенной поддержкой от Microsoft. Поддерживаемые настольные ОС включают Windows 7, 8.1 и 10, а поддерживаемые серверные ОС — Windows Server 2008, 2008 R2, 2012, 2012 R2 и 2016.
• Ansible требует PowerShell 3.0 или более поздней версии и по меньшей мере .NET 4.0, установленных на хосте Windows.
• Должен быть создан и активирован слушатель WinRM. Более подробные сведения об этом можно найти ниже.

Обновление PowerShell и .NET Framework

Ansible требует PowerShell версии 3.0 и .NET Framework 4.0 или более поздней версии для работы на более старых операционных системах, таких как Server 2008 и Windows 7. Базовый образ не удовлетворяет этому требованию. Вы можете использовать скрипт Upgrade-PowerShell.ps1 для обновления этих компонентов.

Вот пример того, как запустить этот скрипт из PowerShell:

$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

# version can be 3.0, 4.0 or 5.1
&$file -Version 5.1 -Username $username -Password $password -Verbose

После завершения вам нужно будет удалить автоматический вход и установить политику выполнения обратно по умолчанию в Restricted. Вы можете сделать это с помощью следующих команд PowerShell:

# this isn't needed but is a good security practice to complete
Set-ExecutionPolicy -ExecutionPolicy Restricted -Force

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

Скрипт работает, проверяя, какие программы необходимо установить (например, .NET Framework 4.5.2) и какая версия PowerShell требуется. Если требуется перезагрузка, и параметры username и password установлены, скрипт автоматически перезагрузится и выполнит вход при перезапуске. Скрипт будет продолжен, пока не потребуются больше действий, и версия PowerShell не будет соответствовать целевой версии. Если параметры username и password не установлены, скрипт попросит пользователя вручную перезагрузиться и выполнить вход при необходимости. При следующем входе пользователя скрипт продолжит с того места, где остановился, и процесс будет продолжаться до тех пор, пока не потребуются больше действий.

Исправление памяти WinRM

При работе с PowerShell v3.0 существует ошибка в службе WinRM, которая ограничивает объем памяти, доступный для WinRM. Без установки этого исправления Ansible не сможет выполнить определенные команды на хосте Windows. Эти исправления должны быть установлены как часть процесса загрузки или создания образов системы. Скрипт Install-WMF3Hotfix.ps1 можно использовать для установки исправления на затронутые хосты.

Следующая команда PowerShell установит исправление:

$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

Настройка WinRM

После обновления Powershell до версии 3.0 или выше, последним шагом является настройка службы WinRM таким образом, чтобы Ansible мог к ней подключиться. Существует две основные компоненты службы WinRM, которые определяют, как Ansible может взаимодействовать с хостом Windows: listener и service параметры конфигурации.

Подробности о каждом компоненте можно найти ниже, но скрипт ConfigureRemotingForAnsible.ps1 можно использовать для базовой настройки. Этот скрипт настраивает слушатели HTTP и HTTPS с самозаверяющим сертификатом и включает опцию аутентификации Basic для службы.

Для использования этого скрипта выполните следующее в PowerShell:

$url = "https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
$file = "$env:temp\ConfigureRemotingForAnsible.ps1"

(New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file)

powershell.exe -ExecutionPolicy ByPass -File $file

Существуют различные переключатели и параметры (например, -EnableCredSSP и -ForceNewSSLCert) которые могут быть установлены вместе с этим скриптом. Документация по этим параметрам расположена в самом начале скрипта.

Слушатель WinRM

Службы WinRM прослушивают запросы на одном или нескольких портах. Для каждого из этих портов необходимо создать и настроить слушателя.

Чтобы просмотреть текущие слушатели, работающие на службе WinRM, выполните следующую команду:

winrm enumerate winrm/config/Listener

Выход будет примерно таким:

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%7

Listener
    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

В примере выше активированы два слушателя: один прослушивает порт 5985 по протоколу HTTP, а другой — порт 5986 по протоколу HTTPS. Некоторые важные параметры:

• Transport: Протокол (HTTP или HTTPS). Рекомендуется использовать HTTPS, так как данные шифруются без дополнительных изменений.
• Port: Порт, на котором работает слушатель. По умолчанию это 5985 для HTTP и 5986 для HTTPS. Этот порт можно изменить на требуемый, который соответствует переменной хоста ansible_port.
• URLPrefix: Префикс URL для прослушивания. По умолчанию это wsman. Если он изменен, переменная хоста ansible_winrm_path должна быть установлена на то же значение.

• CertificateThumbprint: При работе с HTTPS слушателем, это отпечаток сертификата из хранилища сертификатов Windows, используемого при подключении. Чтобы получить подробности о самом сертификате, выполните эту команду в PowerShell, указав соответствующий отпечаток сертификата:

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

Настройка слушателя WinRM

Существует три способа настройки слушателя WinRM:

• Использование winrm quickconfig для HTTP или winrm quickconfig -transport:https для HTTPS. Это самый простой способ, когда хост не находится в домене и требуется простой слушатель. В отличие от других вариантов, этот процесс также имеет преимущество открытия брандмауэра для необходимых портов и запуска службы WinRM.
• Использование объектов групповой политики. Это лучший способ создания слушателя, когда хост является членом домена, так как настройка выполняется автоматически без какого-либо вмешательства пользователя. Для получения дополнительной информации об объектах групповой политики, см. документацию по объектам групповой политики.

• Использование PowerShell для создания слушателя со специфической конфигурацией. Это можно сделать, выполнив следующие команды PowerShell:

  $selector_set = @{
      Address = "*"
      Transport = "HTTPS"
  }
  $value_set = @{
      CertificateThumbprint = "E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE"
  }
  
  New-WSManInstance -ResourceURI "winrm/config/Listener" -SelectorSet $selector_set -ValueSet $value_set
  

  Для просмотра других параметров с этим командлетом PowerShell см. New-WSManInstance.

Удаление слушателя WinRM

Чтобы удалить слушатель WinRM:

# remove all listeners
Remove-Item -Path WSMan:\localhost\Listener\* -Recurse -Force

# only remove listeners that are run over HTTPS
Get-ChildItem -Path WSMan:\localhost\Listener | Where-Object { $_.Keys -contains "Transport=HTTPS" } | Remove-Item -Recurse -Force

Параметры службы WinRM

Существует ряд параметров, которые можно установить для управления поведением службы WinRM, включая параметры аутентификации и параметры памяти.

Чтобы получить вывод текущих параметров конфигурации службы, выполните следующую команду:

winrm get winrm/config/Service
winrm get winrm/config/Winrs

Вывод будет примерно таким:

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 = true

Winrs
    AllowRemoteShellAccess = true
    IdleTimeout = 7200000
    MaxConcurrentUsers = 2147483647
    MaxShellRunTime = 2147483647
    MaxProcessesPerShell = 2147483647
    MaxMemoryPerShellMB = 2147483647
    MaxShellsPerUser = 2147483647

Хотя многие из этих параметров редко изменяются, некоторые из них могут легко повлиять на операции с WinRM и полезны для понимания. Некоторые важные параметры:

• Service\AllowUnencrypted: Этот параметр определяет, будет ли WinRM разрешать трафик по HTTP без шифрования сообщений. Шифрование на уровне сообщений поддерживается только тогда, когда ansible_winrm_transport установлено в ntlm, kerberos или credssp. По умолчанию это false, и его следует устанавливать в true только при отладке сообщений WinRM.
• Service\Auth\*: Эти флаги определяют разрешенные варианты аутентификации с помощью службы WinRM. По умолчанию включены Negotiate (NTLM) и Kerberos.
• Service\Auth\CbtHardeningLevel: Указывает, проверяются ли токены привязки канала (None), проверяются, но не требуются (Relaxed), или проверяются и требуются (Strict). CBT используется только при подключении с NTLM или Kerberos по HTTPS. Нижние библиотеки, которые в настоящее время использует Ansible, поддерживают передачу CBT только с аутентификацией NTLM. Использование Kerberos с CbtHardeningLevel = Strict приведет к ошибке 404.
• Service\CertificateThumbprint: Это отпечаток сертификата, используемого для шифрования канала TLS, используемого с аутентификацией CredSSP. По умолчанию он пустой; самозаверяющий сертификат генерируется при запуске службы WinRM и используется в процессе TLS.
• Winrs\MaxShellRunTime: Максимальное время (в миллисекундах), которое разрешается для выполнения удаленной команды.
• Winrs\MaxMemoryPerShellMB: Максимальный объем памяти, выделяемый на каждый командный интерпретатор, включая дочерние процессы этого интерпретатора.

Для изменения параметра под ключом Service в PowerShell можно использовать следующую команду:

# substitute {path} with the path to the option after winrm/config/Service
Set-Item -Path WSMan:\localhost\Service\{path} -Value "value here"

# for example, to change Service\Auth\CbtHardeningLevel run
Set-Item -Path WSMan:\localhost\Service\Auth\CbtHardeningLevel -Value Strict

Для изменения параметра под ключом Winrs в PowerShell можно использовать следующую команду:

# substitute {path} with the path to the option after winrm/config/Winrs
Set-Item -Path WSMan:\localhost\Shell\{path} -Value "value here"

# for example, to change Winrs\MaxShellRunTime run
Set-Item -Path WSMan:\localhost\Shell\MaxShellRunTime -Value 2147483647

Общие проблемы WinRM

Из-за широкого диапазона параметров конфигурации WinRM его настройка и конфигурация могут быть сложными. Из-за этой сложности проблемы, отображаемые Ansible, на самом деле могут быть проблемами с настройкой узла.

Один из простых способов определить, является ли проблема проблемой узла, — это запустить следующую команду с другого Windows-узла для подключения к целевому Windows-узлу:

# test out HTTP
winrs -r:http://server:5985/wsman -u:Username -p:Password ipconfig

# test out HTTPS (will fail if the cert is not verifiable)
winrs -r:http://server:5985/wsman -u:Username -p:Password -ssl ipconfig

# test out 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 -SkipRevocationCheck
Invoke-Command -ComputerName server -UseSSL -ScriptBlock { ipconfig } -Credential $cred -SessionOption $session_option

Если это не удалось, проблема, вероятно, связана с настройкой WinRM. Если это сработало, проблема может быть не связана с настройкой WinRM; пожалуйста, продолжайте читать для получения дополнительных рекомендаций по устранению неполадок.

HTTP 401/Отклонены учетные данные

Ошибка HTTP 401 указывает на то, что процесс аутентификации не удался во время первоначального подключения. Следует проверить:

• Убедитесь, что учетные данные правильные и правильно заданы в вашем инвентаре с помощью ansible_user и ansible_password
• Убедитесь, что пользователь является членом локальной группы администраторов или ему был явно предоставлен доступ (можно использовать тест подключения с командой winrs, чтобы исключить эту возможность).
• Убедитесь, что параметр аутентификации, заданный ansible_winrm_transport включен в Service\Auth\*
• Если выполняется по HTTP, а не по HTTPS, используйте ntlm, kerberos или credssp с ansible_winrm_message_encryption: auto для включения шифрования сообщений. Если используется другой вариант аутентификации или если установленная версия pywinrm не может быть обновлена, можно установить Service\AllowUnencrypted в true, но это рекомендуется только для устранения неполадок.
• Убедитесь, что пакеты pywinrm, requests-ntlm, requests-kerberos, и/или requests-credssp обновлены с помощью pip.
• Если используется аутентификация Kerberos, убедитесь, что Service\Auth\CbtHardeningLevel не установлено в Strict.
• При использовании аутентификации Basic или сертификата убедитесь, что пользователь является локальным пользователем, а не доменным. Доменные учетные записи не работают с аутентификацией Basic и сертификата.

Ошибка HTTP 500

Эти ошибки указывают на ошибку в службе WinRM. Следует проверить:

• Убедитесь, что количество открытых командных интерпретаторов не превышает WinRsMaxShellsPerUser или другие квоты WinRM не превышены.

Ошибки таймаута

Эти ошибки обычно указывают на ошибку сетевого соединения, где Ansible не может подключиться к узлу. Следует проверить:

• Убедитесь, что брандмауэр не блокирует настроенные порты слушателя WinRM
• Убедитесь, что на порту и пути, заданных переменными узла, включен слушатель WinRM
• Убедитесь, что служба winrm запущена на Windows-узле и настроена на автоматический запуск

Ошибки отказа в подключении

Эти ошибки обычно указывают на ошибку при попытке связи со службой WinRM на узле. Следует проверить:

• Убедитесь, что служба WinRM запущена на узле. Используйте (Get-Service -Name winrm).Status для получения статуса службы.
• Проверьте, что брандмауэр узла разрешает трафик по порту WinRM. По умолчанию это 5985 для HTTP и 5986 для HTTPS.

Иногда установщик может перезапустить службы WinRM или HTTP, что приведет к этой ошибке. Лучший способ справиться с этим — использовать win_psexec с другого Windows-узла.