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

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

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

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

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

• Поддерживаемые Ansible версии Windows в целом соответствуют версиям, находящимся под текущей и расширенной поддержкой 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 или другие квоты Winrs не превышены.

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

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

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

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

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

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

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