Create PowerShell scripts for third-party updates
Beginning in Patch Manager 2.1.6, you can create PowerShell scripts that execute as part of an Update Management task—both before and after the task completes. Using Update Management or the Update Management Wizard, you can push updates with PowerShell scripts to your managed systems that perform the following tasks:
- Create a VM snapshot prior to an update task
- Revert to a snapshot if an issue occurs
- Stop services in a specific order
- Fail over machines
- Mute alerts from SolarWinds Platform nodes during update tasks
See the Microsoft Docs website at https://docs,microsoft.com for details about how to write and run scripts in the Windows PowerShell ISE.
The PowerShell script functionality applies to devices connected to WMI and does not apply to Patch Manager Agents. If a managed client is included in the target scope, the task for that agent will fail.
Review and evaluate how Windows PowerShell scripts are incorporated in your environment. This includes importing scripts from third parties, including content posted by customers in the THWACK online community. To prevent unauthorized access to computers in your network, SolarWinds recommends using a dedicated Windows account with low-level privileges to create and review PowerShell scripts.
About Windows PowerShell
Microsoft Windows PowerShell is a task automation and configuration management framework that consists of a command-line shell and associated scripting language.
PowerShell is built on top of the .NET Framework Common Language Runtime (CLR) and the .NET Framework, and accepts and returns .NET Framework objects. This means you can get the information you need almost instantly using PowerShell—if you know how to ask for it. PowerShell is included with .NET Framework 4.0 and later and can be accessed from within the Windows Server operating system.
PowerShell includes built-in commands with a consistent interface (as shown below), plus an Integrated Scripting Environment (ISE) host application.
(Screenshot property of © 2021 Microsoft Corporation)
To access the interface or the ISE host application, search for PowerShell in the Windows Server operating system.
PowerShell also includes default cmdlets — simple commands you can use to manipulate objects. Cmdlets have a unique format — a verb and noun separated by a dash (-), such as Get-Help. You can use them separately or combine them in scripts that perform complex tasks. You can also write your own cmdlets.
SolarWinds provides customer support for PowerShell scripts, but not for scripting languages or custom scripts. Visit THWACK for scripting support from the SolarWinds online IT community.
Security considerations
Depending on how you configure PowerShell in your environment, it can make any system vulnerable to unauthorized access. Be sure to review and assess how you incorporate PowerShell scripts into your environment. This includes importing scripts from third parties and the THWACK online community.
While PowerShell enhances Patch Manager functionality, be sure to consider the security risks inherent in using PowerShell scripts. To prevent unauthorized access to computers in your network, SolarWinds recommends using a dedicated Windows account with low-level privileges to create and review PowerShell scripts.
To avoid security risks such as malicious OS command injections, consider implementing the PowerShell built-in security. See the Microsoft PowerShell documentation located on the Microsoft Docs website at https://docs.microsoft.com for details.
Requirements
Below are the PowerShell requirements for a typical Patch Manager environment.
| Item | Requirements |
|---|---|
| PowerShell version |
PowerShell 2.0 or later is required on the Patch Manager server to execute remote scripts on your managed computers. PowerShell is installed by default with Microsoft Windows Server operating systems. See the Microsoft Docs website at http://docs.microsoft.com for the PowerShell system requirements. |
| Accounts and permissions |
Local Admin rights are required to run scripts on the Patch Manager server. To execute scripts on your managed systems, select a Windows credential with rights to log in to the Patch Manager server plus sufficient rights on the managed systems to execute tasks in the script. For example, if a script executes a task with WMI, the credentials also require WMI rights on the target system. |
| Microsoft .NET Framework |
Many PowerShell scripts require .NET 3.5.x, but the latest Patch Manager software includes a later version. If required, use the Add Roles and Features Wizard in Server Manager to add .NET Framework 3.5.x. |
Push scripts using the Update Management Wizard
You can create PowerShell scripts using Windows PowerShell Integrated Scripting Environment (ISE) or a text editor (such as Notepad). After you create your remote and local scripts, you can load them in Update Management or the Update Management Wizard by clicking Load remote script or Load local script—based on the type of script you create.
You can create remote or local scripts for your managed systems. Remote scripts are executed on each client machine using PowerShell Remoting (PSRemoting). These scripts use the client machine credentials stored in the Credential Ring to authenticate and execute the script. Local scripts are executed on the Application Server.
When you are ready to upload a script, click the appropriate button in the interface to load the remote or local script (for example, Load remote script). When completed, Patch Manager validates the script for syntax errors. If an error is detected, a dialog box displays with the error.
After Patch Manager validates the script, a Valid message displays under the script load button. If the script contains errors, Not Valid displays under the load button. If the script is validated, Valid displays under the load button.
If Not Valid displays, the Next button is deactivated in the wizard. When this occurs, rewrite the script and then reload. After the script is validated, the Next button is activated, and you can proceed.
Remote PowerShell scripts
Remote PowerShell scripts are executed on client machines that access your corporate network from a remote location. When an employee logs in and connects to the WSUS server, Patch Manager pushes the updates to their systems.
To access the remote systems, Patch Manager uses PowerShell Remoting and the client machine credentials stored in the Credential Ring to authenticate and execute the PowerShell script on each client machine listed in the target scope.
On each client machine targeted with PowerShell scripts, ensure that:
-
PowerShell Remoting (PSRemoting) is enabled. This allows your Patch Manager server and your managed clients to communicate with each other.
- Windows Remote Management (WinRM) is configured. This enables the managed system to receive PowerShell remote commands.
See the Microsoft Docs website at https://docs.microsoft.com for details on how to enable and configure these settings.
Script limitations
Remote PowerShell scripts have the following limitations:
- They do not support Patch Manager PowerShell variables.
- They only execute on client machines running WMI Providers and not a Patch Manager agent. If a Patch Manager agent is included in your target scope, the task for that agent will fail.
Pre-update remote script example
Pre-update scripts are executed on the targeted client machines listed in the target scope before the patch update runs. To run this script, locate the Patch Manager Pre-Update Script box in the Update Management Wizard and select the Run remote script checkbox. Click Load remote script to load the script and validate for errors.
If you want to execute the update task when the script fails, select the Continue if script failed checkbox. If Patch Manager cannot access the targeted computer, the script will not be executed.
if the script includes PowerShell commands that can temporarily break the connection between the Patch Manager server and the client machine, select Wait if connection lost and select an appropriate wait time.
The following script example creates a new folder on the client system at c:\Result, where the folder name is the current date and time. This script is executed before the patches are installed on the system.
function createFolder ($fname)
{
New-Item -ItemType directory -Path C:\Result\beforeClientFolder-$fname
}
$time = $((Get-Date).ToString('yyyy-MM-dd-hh-mm-ss'))
createFolder $time
Post-update remote script example
Pre-update scripts execute on the targeted client machines listed in the target scope after the patch updates run. To run this script, locate the Patch Manager Post-Update Script box in the Update Management Wizard and select the Run remote script checkbox. Click Load remote script and navigate to the script. If the script syntax is good, Valid displays in the box.
Optionally, you can select whether to execute the script if the Patch Manager update fails for any reason. if the script includes PowerShell commands that can temporarily break the connection between the Patch Manager server and the client machine, select Wait if connection lost and select an appropriate wait time.
The following script example creates a new folder on the client system at c:\Result, where the folder name is the current date and time. This script is executed after the patches are installed on the system.
function createFolder ($fname)
{
New-Item -ItemType directory -Path C:\Result\afterClientFolder-$fname
}
$time = $((Get-Date).ToString('yyyy-MM-dd-hh-mm-ss'))
createFolder $time
Local PowerShell scripts
Local PowerShell scripts are executed on client machines that access your corporate network locally—for example, from within your corporate headquarters. These scripts are executed on the Application Server from the Patch Manager Administrator Console. Users can access the Patch Manager PowerShell Variables from within the scripts. All local PowerShell scripts support PowerShell variables.
Pre-update local script example
Pre-update local scripts are executed by the Application Server on the targeted client machines before the patch update runs. To run this script, locate the Patch Manager Pre-Update Script box in the Update Management Wizard and select the Run local script checkbox. Click Load remote script and navigate to the script. If the script syntax is good, Valid displays in the box. Select the Continue if script failed checkbox if you want the update to continue in this situation.
The following script example creates a folder in the Patch Manager server with the first client machine name. This script will also set the registry key on each client machine with the current date and time and the user name.
function createFolder ($fname)
{
$path = "C:\Result\beforeFolderOnLocal-" + $fname
$time = $((Get-Date).ToString(yyyy-MM-dd-hh-mm-ss'))
New-Item -ItemType directory -Path $path+stime
}
createFolder $TargetMachineList.Values[0].NetbiosName
function Set-RemoteRegistryValue {
param(
$ComputerName,
$Path,
$Name,
$Value,
[ValidateNotNull()]
[System.Management.Automation.PSCredential]
[System.Management.Automation.Credential()]
$Credential = [System.Management.Automation.PSCredential]::Empty
)
$null = Invoke-Command -ComputerName $ComputerName -ScriptBlock {
Set-ItemProperty -Patch $using:Path -Name $using:Name -Value $using:Value
} -Credential $Credential
}
$m32 = $TargetMachinesList['mentonw7x32']
$m64 - $TargetMachinesList.Values[1]
$remoteKeyParams32 = @{
ComputerName = $m32.NetBiosName
Path = 'HELM:\SOFTWARE\Test'
Name = 'Cred'
Value = $m32.Credential.UserName + ' ' + $((Get-Date.ToString('yyyy-MM-dd-hh-mm-ss'))
}
$remoteKeyParams64 = @{
ComputerName = $m64.NetBiosName
Path = 'HELM:\SOFTWARE\Test'
Name = 'Cred'
Value = $m64.Credential.UserName + ' ' + $((Get-Date.ToString('yyyy-MM-dd-hh-mm-ss'))
}
Set-RemoteRegistryValue @remoteKeyParams32 -Credential $sm32.Credential
Set-RemoteRegistryValue @remoteKeyParams64 -Credential $sm64.Credential
Warning: SolarWinds strongly recommends that you back up the client registry before making any edits to their system registry. You should only edit the registry if you are experienced and confident in doing so. Editing the register incorrectly can cause serious issues with the client operating system, which could require you to reinstall their operating system to correct them. SolarWinds cannot guarantee resolutions to any damage resulting from making registry edits.
Post-update local script example
Post-update local scripts run on the client machines by the Application Server after the patch updates are installed. To run this script, locate the Patch Manager Post-Update Script box in the Update Management Wizard and select the Run local script checkbox. Click Load remote script and navigate to the script. If the script syntax is good, Valid displays in the box. Select the Execute if others failed checkbox if you want the script to execute if the update fails.
The following script example creates a new folder on the client system at c:\Result, where the folder name is the current date and time. This script is executed after the patches are installed on the system.
function createFolder ($fname)
{
$path = 'C:\Result\afterFolderOnLocal-" + $fname
$time = $((Get-Date).ToString('yyyy-MM-dd-hh-mm-ss'))
}
createFolder $TargetMachinesList.Valules[0].NetbiosName
Customize local scripts using Patch Manager PowerShell variables
To create more efficient local scripts, you can implement the Patch Manager PowerShell variables. You can use these variables in the same way as PowerShell variables by using the $ sign.
These variables cannot be used for remote scripts.
The following table lists the variables you can use in a Patch Manager PowerShell script.
| Class | Types |
|---|---|
| Class TargetMachine |
|
| Class TaskOperationsResult |
|
| Enum commonconstants. eOperationResultStatus |
|
| Class Rule |
|
PowerShell script output examples
The following table lists examples of output you can generate using Patch Manager PowerShell variables.
| Variable | Output |
|---|---|
SortedList<String, TargetMachine>
|
Contains a list of clients machines that is targeted by update task. |
SortedList<String, TargetMachine>
|
Contains a list of available WSUS servers. |
List<TaskOperationsResult> TaskResultsList
|
Contains executed task’s operations results list. Available only for Post-Task local scripts. |
List<Rule> RulesList
|
Contains list of rules used for task. |
Sting ApplicationServerName
|
Represents the name of Application server where the script is executing. |
PowerShell script execution and failures
The following table lists examples of script execution and the corresponding results.
| Script Execution | Result |
|---|---|
| Pre-Update remote local script is pushed to each end client listed in the target scope |
When the script fails, the update task is executed only if “Continue if script failed” is checked. If the client is not accessible, the script is not executed. Patch Manager PowerShell variables are not accessible in these scripts. |
| Pre-Update local script is pushed to the Application Server |
When the script fails, the update task is executed only if “Continue if script failed” is checked. Patch Manager PowerShell variables are accessible in these scripts. |
| Post-Update remote local script is pushed to each end client listed in the target scope. |
When each client operation fails, the script is executed only if “Continue if update failed” is checked. If client is not accessible, the script is not executed. Patch Manager PowerShell variables are not accessible in these scripts. |
| Post-Update local script is pushed to the Application Server. |
When the update fails, the script is executed only if "Execute if others failed" is checked. The script is not executed if any of the task operations fail, unless the checkbox is checked. Patch Manager PowerShell variables are accessible in these scripts. |
View the PowerShell script output
Patch Manager keeps track of the script output in Active Tasks, including the computer name, status, and details. Below is an example of the script output in the Patch Manager Administrator Console. To access this window, select
Access the script output
- Log in to Patch Manager as an administrator.
- In the Patch Manager menu, maximize Administration and Reporting and select Active Tasks.
- In the lower center menu, click the Output tab.
Check the script task history
- In the Patch Manager menu, maximize Administration and Reporting and select Task History.
- In the top center console, select a script task.
- In the bottom center console, click the Details tab.