Настройка хоста 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 хост должен соответствовать этим требованиям:

• 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:

[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

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

После завершения потребуется удалить автоматический вход и установить политику выполнения обратно по умолчанию (Restricted `` for Windows clients, or ``RemoteSigned для серверов Windows). Вы можете сделать это с помощью следующих команд PowerShell:

# This isn't needed but is a good security practice to complete
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -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 установит исправление:

[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

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

Настройка WinRM

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

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

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

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$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.
• 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.
• При использовании аутентификации по паролю или сертификату убедитесь, что пользователь является локальным, а не доменным учетной записью. Доменные учетные записи не работают с аутентификацией по паролю и сертификату.

Ошибка 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. Microsoft предлагает способ установки Win32-OpenSSH через возможности Windows, но в настоящее время версия, установленная этим способом, слишком старая для работы с Ansible. Чтобы установить Win32-OpenSSH для использования с Ansible, выберите один из трех вариантов установки:

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

• Установите пакет 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 для копирования или извлечения файла