Отладка сценариев PowerShell, выполняемых с помощью расширения пользовательского скрипта или команды run

Область применения: ✔️ Виртуальные машины Windows

В этой статье описывается, как проверить и исправить сбой в скрипте PowerShell, использующего расширение пользовательского скрипта или функцию запуска команды.

Предварительные требования

• Azure PowerShell
• Средство PsExec

Обзор

Предположим, что вы использовали расширение пользовательского скрипта или функцию запуска команды для запуска скрипта PowerShell. Что делать, если скрипт завершается сбоем? Существует несколько доступных методов для определения причины сбоя.

PowerShell имеет несколько выходных потоков. Журналы для расширения пользовательских скриптов и скриптов запуска команд отправляют поток успешности StdOut в подстатус и поток ошибок в StdErr подстатус. Эти подстатики относятся к расширению, которое использовалось для запуска скрипта расширения пользовательского скрипта или скрипта запуска команды.

StdErr Подстатики StdOut находятся в представлении экземпляра точки регистрации сертификатов (CRP) для виртуальной машины. Эти подстатики отображаются в нескольких расположениях в следующей таблице.

Интерфейс	Просмотр подстатуса
Портал Azure	Найдите и щелкните Виртуальные машины. Выберите нужную виртуальную машину из списка. На странице обзора виртуальной машины выберите расширения и расширения приложений>. Выберите расширение, которое использовалось для выполнения команды. (Оно будет называться либо CustomScriptExtension или RunCommand.) Выберите "Просмотреть подробное состояние".
Azure PowerShell	Введите командлет Get-AzVM, чтобы получить свойства виртуальной машины Azure следующим образом: Get-AzVM -ResourceGroupName <resource-group-name> -Name <vm-name> -Status
Azure CLI	Введите команду az vm get-instance-view, чтобы получить сведения об экземпляре виртуальной машины Azure следующим образом: az vm get-instance-view --resource-group <resource-group-name> --name <vm-name> --query instanceView.extensions

Ошибка, которая обычно приводит к сбою скрипта в StdErr подстате. Однако скрипты также могут завершиться ошибкой без ведения журнала неустранимая запись ошибки в этом подстате.

Тестирование скрипта вручную и с помощью PsExec

Вручную убедитесь, что скрипт успешно выполняется из административной консоли PowerShell на виртуальной машине.

Если скрипт работает вручную, используйте PsExec для запуска скрипта с помощью локальной системной учетной записи. Для расширения пользовательских скриптов и команды запуска скриптов выполняются с помощью этой учетной записи. Введя psexec -sскрипт, вы можете протестировать скрипт с помощью локальной системной учетной записи, но без использования расширения пользовательского скрипта или команды запуска. Если сбой воспроизводится с помощью psexec -s, расширение пользовательского скрипта и команда запуска не являются причиной проблемы.

Тестирование с помощью PsExec

Вы можете использовать PsExec для удаленного запуска тестового скрипта PowerShell. Откройте окно командной строки администратора и введите следующую команду PsExec. Замените заполнитель полным именем скрипта PowerShell:

psexec -accepteula -nobanner -s powershell.exe -NoLogo -NoProfile -File <C:\path\script-name.ps1>

Кроме того, вы можете использовать PsExec в интерактивном режиме. В следующем примере введите команду whoami , чтобы показать, что PowerShell выполняется в учетной записи локальной системы (NT AUTHORITY\SYSTEM).

C:\>psexec -accepteula -nobanner -s powershell.exe -NoLogo -NoProfile

PS C:\Windows\system32> whoami
nt authority\system 

Включение ведения журнала выполнения скрипта PowerShell

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

Чтобы включить различные типы ведения журнала, выполните действия, описанные в следующих нескольких разделах.

Предупреждение

Некоторые инструкции включают изменение реестра Windows. При неправильном изменении реестра с использованием редактора реестра или другого способа могут случиться серьезные проблемы. Для решения этих проблем может потребоваться переустановка операционной системы. Корпорация Майкрософт не может гарантировать, что эти проблемы удастся решить. Сначала создайте резервную копию существующих записей реестра, а затем измените реестр с собственным риском.

Увеличьте максимальный размер журналов событий

Большое количество событий можно создать как в журнале безопасности, так и в журнале событий Microsoft-Windows-PowerShell/Operations. Чтобы предотвратить потерю этих зарегистрированных событий, увеличьте максимальный размер журналов. Но если любой из этих журналов имеет максимальный размер 100 МБ или больше ( maxSize значение 104 857 600 или более), оставьте максимальный размер как есть.

Чтобы проверить максимальный размер журнала, используйте команду wevtutil и get-log параметр для получения сведений о журналах событий:

wevtutil get-log "Security"
wevtutil get-log "Microsoft-Windows-PowerShell/Operational"

Вы увидите выходные данные, похожие на следующий текст. В таких случаях максимальный размер журнала гораздо меньше 100 МБ.

name: Security
enabled: true
type: Admin
owningPublisher:
isolation: Custom
channelAccess: O:BAG:SYD:(A;;CCLCSDRCWDWO;;;SY)(A;;CCLC;;;BA)(A;;CC;;;ER)(A;;CC;;;NS)
logging:
  logFileName: %SystemRoot%\System32\Winevt\Logs\Security.evtx
  retention: false
  autoBackup: false
  maxSize: 20971520
publishing:
  fileMax: 1

name: Microsoft-Windows-PowerShell/Operational
enabled: true
type: Operational
owningPublisher: Microsoft-Windows-PowerShell
isolation: Application
channelAccess: O:BAG:SYD:(A;;0x2;;;S-1-15-2-1)(A;;0x2;;;S-1-15-3-1024-3153509613-960666767-3724611135-2725662640-12138253-543910227-1950414635-4190290187)(A;;0xf0007;;;SY)(A;;0x7;;;BA)(A;;0x7;;;SO)(A;;0x3;;;IU)(A;;0x3;;;SU)(A;;0x3;;;S-1-5-3)(A;;0x3;;;S-1-5-33)(A;;0x1;;;S-1-5-32-573)
logging:
  logFileName: %SystemRoot%\System32\Winevt\Logs\Microsoft-Windows-PowerShell%4Operational.evtx
  retention: false
  autoBackup: false
  maxSize: 15728640
publishing:
  fileMax: 1

Чтобы увеличить максимальный размер журнала безопасности или журнала событий Microsoft-Windows-PowerShell/Operations, до 100 МБ, выполните команду wevtutil вместе с параметром set-log :

wevtutil set-log "Security" /ms:104857600
wevtutil set-log "Microsoft-Windows-PowerShell/Operational" /ms:104857600

Включение аудита создания процесса

Используйте следующую команду, чтобы включить аудит создания процесса:

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\Audit" /v "ProcessCreationIncludeCmdLine_Enabled" /t REG_DWORD /d 1 /f

Включение транскрибирования PowerShell

reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\Transcription" /v "EnableTranscripting" /t REG_DWORD /d 1 /f
reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\Transcription" /v "EnableInvocationHeader" /t REG_DWORD /d 1 /f
reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\Transcription" /v "OutputDirectory" /t REG_SZ /d C:\Transcripts /f

Включение ведения журнала модулей PowerShell

reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\ModuleLogging" /v "EnableModuleLogging" /t REG_DWORD /d 1 /f
reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\ModuleLogging\ModuleNames" /v "*" /t REG_SZ /d *

Включение ведения журнала блоков скриптов PowerShell

reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\ScriptBlockLogging" /v "EnableScriptBlockLogging" /t REG_DWORD /d 1 /f

Основные сведения о выходных данных

Аудит создания процесса записывает идентификатор события 4688 и идентификатор события 4689 в журнал событий безопасности. Идентификатор события 4688 предназначен для создания процесса и включает командную строку процесса. Идентификатор события 4689 предназначен для завершения процесса.

Транскрибирование создает текстовый файл в каталоге C:\Transcripts\<output-date> . Каталог будет создан автоматически, если он еще не существует.

Например:

C:\transcripts\20201211\PowerShell_transcript.<имя> виртуальной машины.a+BWp8CT.20201211034929.txt

Ведение журнала модулей регистрирует идентификатор события 4103 в журнал событий Microsoft-Windows-PowerShell/Operations. Событие "4103" включает имя и выходные данные командлета.

При выполнении Write-Host $Env:ComputerNameв верхней части идентификатора события 4013 отображается следующий текст, где value="<vm-name>" указывается, что выходные данные команды были именем виртуальной машины:

CommandInvocation(Write-Host): "Write-Host"
ParameterBinding(Write-Host): name="Object"; value="<vm-name>"

Ведение журнала блоков скриптов будет записывать идентификатор события 4104 в журнал событий Microsoft-Windows-PowerShell/Operations . События "4104" содержат содержимое скрипта. Скрипты, превышающие максимальный размер сообщения события, регистрируются как несколько событий "4104".

После включения ведения журнала и воспроизведения сбоя скрипта выполните следующий скрипт, чтобы экспортировать соответствующие события в CSV-файл с разделием запятыми. Следующий запрос проверяет предыдущие 24 часа (86 400 000 миллисекундах) данных. Введите значение 3600000, чтобы получить только последний час. Значение 604800000 будет извлекать самую последнюю неделю.

$path = "PSEvents_$($env:COMPUTERNAME)_$(Get-Date ((Get-Date).ToUniversalTime()) -Format yyyyMMddHHmmss).csv"

$hours = 1 # Increase this to have it query more than just the last 1 hour
$now = Get-Date
$startTimeUtc = Get-Date ($now.AddHours(-$hours).ToUniversalTime()) -Format 'yyyy-MM-ddTHH:mm:ssZ'
$endTimeUtc = Get-Date ($now.ToUniversalTime()) -Format 'yyyy-MM-ddTHH:mm:ssZ'

$filterXML = @"
<QueryList>
    <Query Id="0" Path="Security">
        <Select Path="Security">
            Event
            [
                System
                [
                    (EventID = '4688' or EventID = '4689')
                    and
                    TimeCreated
                    [
                        @SystemTime &gt;= '$startTimeUtc'
                        and
                        @SystemTime &lt;= '$endTimeUtc'
                    ]
                ]
                and
                EventData
                [
                    Data[@Name="SubjectUserSid"] = "S-1-5-18"
                ]
            ]
        </Select>
    </Query>
    <Query Id="1" Path="Microsoft-Windows-PowerShell/Operational">
        <Select Path="Microsoft-Windows-PowerShell/Operational">
            Event
            [
                System
                [
                    (EventID ='4103' or EventID ='4104')
                    and
                    Security
                    [
                        @UserID ='S-1-5-18'
                    ]
                    and
                    TimeCreated
                    [
                        @SystemTime &gt;= '$startTimeUtc'
                        and
                        @SystemTime &lt;= '$endTimeUtc'
                    ]
                ]
            ]
        </Select>
    </Query>
</QueryList>
"@

$events = Get-WinEvent -FilterXml $filterXML | Sort-Object -Property RecordId
$events = $events | Select-Object -Property RecordId,
    TimeCreated, Id, MachineName, LogName, TaskDisplayName, Message
$events | Export-Csv -Path $path -NoTypeInformation

Отключение ведения журнала выполнения скрипта PowerShell

Чтобы отменить внесенные изменения, чтобы включить ведение журнала сценариев PowerShell на виртуальной машине, сделайте следующее:

1. Если вы ранее увеличили максимальный размер журнала безопасности или журнала Microsoft-Windows-PowerShell/Operations, отверните эти значения до максимальных размеров по умолчанию:

   wevtutil set-log "Security" /ms:20971520
   wevtutil set-log "Microsoft-Windows-PowerShell/Operational" /ms:15728640
   

2. Отключить аудит создания процесса:

   reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\Audit" /v "ProcessCreationIncludeCmdLine_Enabled" /t REG_DWORD /d 0 /f
   

3. Отключите транскрибирование:

   reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\PowerShell\Transcription" /v "EnableTranscripting" /t REG_DWORD /d 0 /f
   reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\PowerShell\Transcription" /v "EnableInvocationHeader" /t REG_DWORD /d 0 /f
   reg delete "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\PowerShell\Transcription" /v "OutputDirectory"
   

4. Отключение ведения журнала модулей:

   reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\ModuleLogging" /v "EnableModuleLogging" /t REG_DWORD /d 0 /f
   reg delete "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\PowerShell\ModuleLogging\ModuleNames" /v "*"
   

5. Отключение ведения журнала блоков скриптов:

   reg add "HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\PowerShell\ScriptBlockLogging" /v "EnableScriptBlockLogging" /t REG_DWORD /d 0 /f
   

6. Удалите папку транскрибирования:

   Remove-Item -Path 'C:\Transcripts' -Force -Recurse
   

7. Резервное копирование и очистка журнала безопасности и журнала Microsoft-Windows-PowerShell/Operations:

   wevtutil clear-log Security /bu:Security.evtx
   wevtutil clear-log Microsoft-Windows-PowerShell/Operational /bu:Microsoft-Windows-PowerShell_Operational.evtx
   

   Или снимите журнал безопасности и операционный журнал Microsoft-Windows-PowerShell или операционный журнал без их резервного копирования:

   wevtutil clear-log Security
   wevtutil clear-log Microsoft-Windows-PowerShell/Operational
   

Тестирование ведения журнала команд запуска на виртуальной машине

Скачайте тестовый скрипт Test-CustomScriptExtension.ps1 в текущий локальный каталог. Затем запустите сценарий на виртуальной машине с помощью командлета Invoke-AzVMRunCommand . Используйте свойства виртуальной машины, чтобы заменить заполнители для имени группы ресурсов и имени виртуальной машины.

$scriptUri = 'https://raw.githubusercontent.com/Azure/azure-support-scripts/blob/users/GitHubPolicyService/6294a303-e34d-4bad-b6cd-5ed54245f020/Images_Extensions/PowerShell/Test-CustomScriptExtension.ps1'
$localFileLocation = "$PWD\Test-CustomScriptExtension.ps1"
(New-Object System.Net.WebClient).DownloadFile($scriptUri, $localFileLocation)

$commandSettings = @{
    ResourceGroupName = '<resource-group-name>'
    VMName = '<vm-name>'
    CommandId = 'RunPowerShellScript'
    ScriptPath = $localFileLocation
}
Invoke-AzVMRunCommand @commandSettings

Проверка ведения журнала расширения пользовательских скриптов на виртуальной машине

Запустите тестовый скрипт Test-CustomScriptExtension.ps1 на виртуальной машине с помощью командлета Set-AzVMCustomScriptExtension . Используйте свойства виртуальной машины для замены заполнителей для имени группы ресурсов, имени виртуальной машины и расположения.

$commandSettings = @{
    ResourceGroupName = '<resource-group-name>'
    VMName = '<vm-name>'
    Name = 'CustomScriptExtension'
    FileUri = 'https://raw.githubusercontent.com/Azure/azure-support-scripts/blob/users/GitHubPolicyService/6294a303-e34d-4bad-b6cd-5ed54245f020/Images_Extensions/PowerShell/Test-CustomScriptExtension.ps1'
    Run = 'Test-CustomScriptExtension.ps1'
    Location = '<azure-region-name-or-code>'
    ForceRerun = (Get-Date).Ticks
}
Set-AzVMCustomScriptExtension @commandSettings

Кроме того, можно запустить этот тестовый скрипт на виртуальной машине с помощью командлета Set-AzVMExtension . Необходимо указать ExtensionType параметр CustomScriptExtension вместе с несколькими другими изменениями параметров. Используйте свойства виртуальной машины для замены заполнителей для имени группы ресурсов, имени виртуальной машины и расположения.

$publicConfigSettings = @{
    'fileUris' = @('https://raw.githubusercontent.com/Azure/azure-support-scripts/blob/users/GitHubPolicyService/6294a303-e34d-4bad-b6cd-5ed54245f020/Images_Extensions/PowerShell/Test-CustomScriptExtension.ps1')
    'commandToExecute' = 'powershell -File Test-CustomScriptExtension.ps1 -ExecutionPolicy Unrestricted'
}
$commandSettings = @{
    Publisher = 'Microsoft.Compute'
    ExtensionType = 'CustomScriptExtension'
    Settings = $publicConfigSettings
    ResourceGroupName = '<resource-group-name>'
    VMName = '<vm-name>'
    Name = 'CustomScriptExtension'
    TypeHandlerVersion = '1.10'
    Location = '<azure-region-name-or-code>'
}
Set-AzVMExtension @commandSettings

Распространенные ошибки в тестовом скрипте пользовательского расширения скрипта

• Код выхода nonzero: после запуска скрипта Test-CustomScriptExtension.ps1 ожидается следующее сообщение об ошибке:

  Long running operation failed with status 'Failed'.
  Дополнительные сведения: виртуальная машина сообщила о сбое при обработке расширения CustomScriptExtension.
  Сообщение об ошибке: "Выполнение команды завершено, но завершилось сбоем, так как он вернул ненулевой код выхода: "2"

  Тестовый скрипт выполняет Exit 2 команду, и расширение пользовательского скрипта, как ожидается, завершится ошибкой, если скрипт возвращает ненулевой код выхода. (В этом примере 2 — ненулевой код выхода.) В этом примере показано, как отображается сбой в дополнительном ведении журнала PowerShell, которое вы включили.

• Изменение конфликтует: эта ошибка указывает, что виртуальная машина уже установлена в качестве имени ресурса Microsoft.Compute.CustomScriptExtension, но вы указываете другое имя ресурса CustomScriptExtension для текущего выполнения:

  Не удается обновить обработчикVersion или autoUpgradeMinorVersion для расширения виртуальной машины CustomScriptExtension.
  Изменение конфликтует с другими расширениями в обработчике Microsoft.Compute.CustomScriptExtension с typeHandler версии 1.10 и autoUpgradeMinorVersion "True".
  ErrorCode: OperationNotAllowed
  ErrorMessage: не удается обновить обработчикVersion или autoUpgradeMinorVersion для расширения виртуальной машины CustomScriptExtension.
  Изменение конфликтует с другими расширениями в обработчике Microsoft.Compute.CustomScriptExtension с typeHandler версии 1.10 и autoUpgradeMinorVersion "True".
  ErrorTarget:
  StatusCode: 409
  ReasonPhrase: конфликт

  Можно указать любое имя ресурса. Однако если у вас уже установлено расширение пользовательского скрипта, необходимо выполнить одно из следующих действий:

  • Используйте то же имя для последующих выполнений.
  • Сначала удалите этот ресурс расширения перед использованием другого имени ресурса.

• Недопустимая конфигурация URI файла: эта ошибка означает, что расширение пользовательского скрипта изначально установлено вместе с URI файлов, указанными в защищенных параметрах, но теперь указаны в общедоступных параметрах (или наоборот):

  Long running operation failed with status 'Failed'.
  Дополнительные сведения: виртуальная машина сообщила о сбое при обработке расширения CustomScriptExtension.
  Сообщение об ошибке: "Недопустимая конфигурация — FileUris присутствует как в защищенных, так и в общедоступных разделах конфигурации; он должен быть указан только в одном разделе".

Решения распространенных ошибок в скрипте тестирования расширения пользовательского скрипта

• Чтобы устранить ошибку "Изменение в конфликте", попробуйте выполнить повторно Set-AzVMCustomScriptExtension или Set-AzVMExtensionзадать -Name параметр в качестве имени ресурса ресурса ресурса расширения пользовательского скрипта, который уже установлен на виртуальной машине. Для примера ошибки при удалении расширения укажите -Name параметр Microsoft.Compute.CustomScriptExtension. Но параметр -Name должен быть любым именем ресурса для ресурса расширения, который уже установлен на виртуальной машине.

  Имя, используемое для -Name использования, будет именем ресурса в этой части ошибки: "Изменение конфликтует с другими расширениями в обработчике "<имя ресурса>".

  Вы также можете проверить правильное имя ресурса, используемое, получив его из состояния виртуальной машины. Введите командлет Get-AzVM следующим образом:

  $status = Get-AzVM -ResourceGroupName <resource-group> -Name <vm-name> -Status
  $status.Extensions |
  Where-Object Type -EQ 'Microsoft.Compute.CustomScriptExtension' |
  Select-Object Name
  

• Чтобы устранить ошибку "Изменение в конфликте" и ошибку FileUris, можно удалить существующее расширение пользовательского скрипта, введя командлет Remove-AzVMCustomScriptExtension :

  $params = @{
      ResourceGroupName = '<resourceGroupName>'
      VMName = '<vm-name>'
      Name = '<extension-resource-name>'
      Force = $True
  }
  Remove-AzVMCustomScriptExtension @params
  

  Если указать неверное имя ресурса, возвращаемое StatusCode значение равно NoContent:

  RequestId IsSuccessStatusCode StatusCode ReasonPhrase
  --------- ------------------- ---------- ------------
                           True  NoContent No Content
  

  Если указать правильное имя ресурса, возвращаемое StatusCode значение равно OK:

  RequestId IsSuccessStatusCode StatusCode ReasonPhrase
  --------- ------------------- ---------- ------------
                           True         OK OK
  

Ссылки

• Troubleshooting Azure Windows VM extension failures
• Трассировка скриптов и ведение журнала
• Известные идентификаторы безопасности в операционных системах Windows
• Ведение журнала Windows
• Событие создания процесса успешного аудита
• Конфигурация Windows — настройка системы жертвы

Свяжитесь с нами для получения помощи

Если у вас есть вопросы или вам нужна помощь, создайте запрос в службу поддержки или обратитесь за поддержкой сообщества Azure. Вы также можете отправить отзыв о продукте в сообщество отзывов Azure.

Заявление об отказе от ответственности за контактные данные сторонней организации

Корпорация Майкрософт предоставляет контактные данные сторонних производителей в целях получения дополнительных сведений по данной теме. Эти данные могут быть изменены без предварительного уведомления. Корпорация Майкрософт не гарантирует точность контактных данных сторонних производителей.