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

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

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

  • Обновление PowerShell и .NET Framework
  • Исправление WinRM для памяти

• Настройка WinRM

  • Слушатель WinRM

    • Настройка слушателя WinRM
    • Удаление слушателя WinRM
  • Параметры службы WinRM

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

    • HTTP 401/Отклонены учетные данные
    • Ошибка HTTP 500
    • Ошибки таймаута
    • Ошибки «Соединение отклонено»
    • Ошибка загрузки встроенных модулей

• Настройка SSH для Windows

  • Установка Win32-OpenSSH
  • Настройка оболочки Win32-OpenSSH
  • Аутентификация Win32-OpenSSH
  • Настройка Ansible для SSH на Windows
  • Известные проблемы с SSH на Windows

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

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

• Ansible, как правило, может управлять версиями Windows, находящимися под текущей и продленной поддержкой Microsoft. Ansible может управлять настольными операционными системами, включая Windows 7, 8.1 и 10, и серверными операционными системами, включая Windows Server 2008, 2008 R2, 2012, 2012 R2, 2016 и 2019.
• 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

Дополнительную информацию см. в документе исправления от Microsoft.

Настройка 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
  

  Чтобы увидеть другие параметры с этим cmdlet 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.
• 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:https://server:5986/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.

Ошибка загрузки встроенных модулей

Если PowerShell завершается с сообщением об ошибке, подобным The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded., может быть проблема с доступом ко всем путям, указанным переменной среды PSModulePath. Распространённая причина этой проблемы — переменная среды PSModulePath содержит UNC-путь к файловому ресурсу, и из-за проблемы с двойным перепрыгиванием/делегированием учетных данных процесс Ansible не может получить доступ к этим папкам. Решение этой проблемы заключается в следующем:

• Удалите UNC-путь из переменной среды PSModulePath, или
• Используйте параметр аутентификации, поддерживающий делегирование учетных данных, например credssp или kerberos с включённым делегированием учетных данных

См. KB4076842 для получения дополнительной информации об этой проблеме.

Настройка SSH для Windows

Ansible 2.8 добавила экспериментальное подключение SSH для управляемых узлов Windows.

Установка Win32-OpenSSH

Первым шагом при использовании SSH с Windows является установка службы Win32-OpenSSH на узле Windows. Корпорация Майкрософт предлагает способ установки Win32-OpenSSH через возможности Windows, но в настоящее время версия, установленная этим методом, слишком старая для работы с Ansible. Чтобы установить Win32-OpenSSH для использования с Ansible, выберите один из трёх вариантов установки:

• Вручную установите службу, следуя инструкциям по установке от Майкрософт.

• Установите пакет openssh с помощью Chocolatey:

  choco install --package-parameters=/SSHServerFeature openssh
  

• Используйте win_chocolatey для установки службы:

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

• Используйте существующий рол Ansible Galaxy, например jborean93.win_openssh:

  # Make sure the role has been downloaded first
  ansible-galaxy install jborean93.win_openssh
  
  # main.yml
  - name: install Win32-OpenSSH service
    hosts: windows
    gather_facts: no
    roles:
    - role: jborean93.win_openssh
      opt_openssh_setup_service: True
  

Настройка оболочки Win32-OpenSSH

По умолчанию Win32-OpenSSH будет использовать cmd.exe в качестве оболочки. Чтобы настроить другую оболочку, используйте задачу Ansible для определения параметра реестра:

- 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

# Or revert the settings back to the default, cmd
- name: set the default shell to cmd
  win_regedit:
    path: HKLM:\SOFTWARE\OpenSSH
    name: DefaultShell
    state: absent

Аутентификация Win32-OpenSSH

Аутентификация Win32-OpenSSH с Windows аналогична аутентификации SSH на Unix/Linux узлах. Можно использовать аутентификацию по паролю в текстовом формате или с открытым ключом SSH, добавить открытые ключи в файл authorized_key в папке .ssh каталога профиля пользователя и настроить службу с помощью файла sshd_config, используемого службой SSH, как на Unix/Linux узле.

При использовании аутентификации по открытому ключу SSH с Ansible удалённая сессия не будет иметь доступа к учетным данным пользователя и завершится ошибкой при попытке получить доступ к сетевому ресурсу. Это также известно как проблема двойного перепрыгивания или делегирования учетных данных. Существует два способа решения этой проблемы:

• Использовать аутентификацию по паролю в текстовом формате, установив ansible_password.
• Использовать become в задаче с учетными данными пользователя, которому нужен доступ к удалённому ресурсу

Настройка Ansible для SSH на Windows

Чтобы настроить Ansible для использования SSH для узлов Windows, необходимо установить два параметра подключения:

• Установите ansible_connection в ssh.
• Установите ansible_shell_type в cmd или powershell.

Переменная ansible_shell_type должна отражать значение DefaultShell на узле Windows. Установите в cmd для оболочки по умолчанию или powershell, если DefaultShell изменено на PowerShell.

Известные проблемы с SSH на Windows

Использование SSH с Windows экспериментально, и мы ожидаем обнаружить больше проблем. Вот известные:

• Версии Win32-OpenSSH, более старые чем v7.9.0.0p1-Beta, не работают, когда powershell является типом оболочки
• Хотя SCP должен работать, SFTP — рекомендуемый механизм передачи файлов SSH для копирования или извлечения файла