Automating Windows targets
Here are some common use cases that you can accomplish with OpenBolt on Windows targets.
Run a PowerShell script that restarts a service
To show you how you can use OpenBolt to reuse your existing PowerShell scripts, this guide walks you through running a script with OpenBolt, and then converting the script to a task and running that.
Before you begin
- Ensure you’ve already installed OpenBolt on your Windows machine.
- Identify a remote Windows target to work with.
- Ensure you have Windows credentials for the target.
- Ensure you have configured Windows Remote Management on the target. OpenBolt connects over HTTPS on port 5986 and verifies the target’s certificate by default.
- Ensure the target’s PowerShell execution policy allows scripts to run, for example
RemoteSigned. Windows Server usesRemoteSignedby default, but Windows client editions such as Windows 11 useRestricted, and OpenBolt can’t run scripts or tasks on a target with that policy.
The example script, restart_service.ps1, performs a common task: restarting a
service on demand. The process involves these steps:
- Run your PowerShell script on a Windows target.
- Create an inventory file to store information about the target.
- Convert your script to a task.
- Execute your new task.
1. Run your PowerShell script on a Windows target
First, we’ll use OpenBolt to run the script as-is on a single target.
- Create a directory to work in, called
bolt-guide. -
In
bolt-guide, create a file namedrestart_service.ps1with the following content:[CmdletBinding()] param ( # Name or list of service names to stop [Parameter(Mandatory=$true)] [string[]] $service, # Stop the services without starting them again [Parameter(Mandatory=$false)] [switch] $norestart ) foreach ($name in $service) { try{ $serviceObject = Get-service -Name $name -ErrorAction SilentlyContinue if(-not $serviceObject){ Write-Output "Service not found: $name" continue } Write-output "Found Service: $name" Stop-Service -InputObject $serviceObject -ErrorAction Stop Write-Output "Stopped service: $name" if($norestart){continue} Start-Service -InputObject $serviceObject Write-Output "Started service: $name" } catch { Write-Output "Cannot stop service: $name" Write-Output "Dependent services: $($serviceObject.dependentservices)" exit 1 } } -
In the
bolt-guidedirectory, run therestart_service.ps1script:bolt script run .\restart_service.ps1 W32Time --targets winrm://<HOSTNAME> -u Administrator --password-promptThe output looks like this:
Started on winrm://win01.example.com... Finished on winrm://win01.example.com: Found Service: W32Time Stopped service: W32Time Started service: W32Time Successful on 1 target: winrm://win01.example.com Ran on 1 target in 6.62 secNote: The
--password-promptoption prompts you to enter a password.By running this command, you’ve brought your script under OpenBolt control and have run it on a remote target. When you ran your script with OpenBolt, the script was transferred into a temporary directory on the remote target, it ran on that target, and then it was deleted from the target.
2. Create an inventory file to store information about your targets
To run OpenBolt commands against multiple targets at once, you need to provide information about the environment by creating an inventory file. The inventory file is a YAML file that contains a list of targets and target specific data.
- Inside the
bolt-guidedirectory, use a text editor to create aninventory.yamlfile and abolt-project.yamlfile. Theinventory.yamlfile is where connection information is stored, whilebolt-project.yamltells OpenBolt that the directory is a project and that it should load the inventory file from the directory. -
Inside the new
inventory.yamlfile, add the following content, listing the fully qualified domain names of the targets you want to run the script on, and replacing the credentials in thewinrmsection with those appropriate for your target:groups: - name: windows targets: - <ADD WINDOWS SERVERS' FQDN> - <example.mycompany.com> config: transport: winrm winrm: user: Administrator password: <ADD PASSWORD> # cacert: <PATH TO CA CERTIFICATE> # ssl-verify: falseIf the target’s WinRM certificate is self-signed or signed by a private certificate authority, OpenBolt can’t verify it and fails to connect. Either uncomment
cacertand set it to the path of the CA certificate, or, for a test target, uncommentssl-verify: false. On the command line, the equivalent ofssl-verify: falseis--no-ssl-verify.Note: To have OpenBolt securely prompt for a password, use the
--password-promptcommand-line option without supplying any value. This prevents the password from appearing in a process listing or on the console. Alternatively you can use thepromptplugin to set configuration values via a prompt.You now have an inventory file where you can store information about your targets.
You can also configure a variety of options for OpenBolt in
bolt-project.yaml. For more information about configuration see Configuring OpenBolt. For more information about OpenBolt projects see OpenBolt projects.
3. Convert your script to a task
To convert the restart_service.ps1 script to a task, giving you the ability to
reuse and share it, create a task metadata file. Task
metadata files describe task parameters, validate input, and control how the
task runner executes the task.
Note: This guide shows you how to convert the script to a task by manually
creating the metadata file in a directory called tasks. If your task lives in
a module created with Jig, `jig new task