Monitor Windows data with PowerShell scripts
PowerShell is a scripting language that comes with many versions of Windows. It lets you handle Windows operations from a command-line interface. You can create scripts with the language and output the results of those scripts as objects to other scripts.
The Splunk platform supports monitoring events received through PowerShell scripts. You can use the PowerShell input to run a single PowerShell command or reference a PowerShell script. The Splunk platform then indexes the output of these commands or scripts as events.
If you use Splunk Cloud Platform and want to monitor script output, use the universal forwarder to ingest the output from a Windows machine and forward it to your Splunk Cloud Platform deployment.
Requirements
- Splunk Cloud Platform must receive Windows data that comes from PowerShell scripts from a universal forwarder that is installed on a Windows machine.
- The Splunk platform instance must run on Windows. See Install on Windows in the Installation Manual.
- The Splunk platform instance must be configured to use the Local System user to run all PowerShell scripts.
- PowerShell version 3.0 or higher must be installed on the machine. Microsoft .NET version 4.5 or higher must be installed on the machine.
- There might be additional requirements to run PowerShell scripts depending on the version of Windows and PowerShell. See the Microsoft documentation on PowerShell for details.
Configure inputs with configuration files
- Write a PowerShell command or script to capture the information you want.
- On the Splunk platform instance that will run the script, open a PowerShell window.
- Create an inputs.conf configuration file in the %SPLUNK_HOME%\etc\system\local directory.
- Open the inputs.conf file and edit it to enable a Windows PowerShell input.
- In the input, specify the command or the full path to your script with the
script
setting. - (Optional) Specify a schedule on which the command or script will run with the
schedule
setting. - Save the inputs.conf file.
- Restart the Splunk platform to enable the input.
PowerShell input configuration values
The Splunk platform uses the following stanzas in the inputs.conf file to monitor data gathered by PowerShell.
Setting | Description | Default |
---|---|---|
script
|
The PowerShell command or script file to run.
|
n/a
|
schedule
|
How often the command or script runs.
|
Script runs once |
disabled
|
Whether or not to enable the input.
|
0 (enabled) |
For information on writing PowerShell scripts, see Write scripts for the PowerShell input later in this topic.
Single command configuration example
This example runs the Get-Process
cmdlet and pipes that output to the Select-Object
cmdlet using the host name that Splunk software is installed on as an argument. It runs the command every 5 minutes.
[powershell://Processes-EX1] script = Get-Process | Select-Object Handles, NPM, PM, WS, VM, Id, ProcessName, @{n="SplunkHost";e={$Env:SPLUNK_SERVER_NAME}} schedule = */5 * * * * sourcetype = Windows:Process
Script configuration example
This example runs the getprocesses.ps1
script located in the %SPLUNK_HOME\etc\apps\My-App directory. It sets the source type for these events to Windows:Process
. The script runs every 20 minutes from 9:00 AM to 4:40 PM on Mondays to Fridays.
[powershell://Processes-EX2] script = . "$SplunkHome\etc\apps\My-App\bin\getprocesses.ps1" schedule = */20 * 9-16 * 1-5 sourcetype = Windows:Process
Configure inputs with Splunk Web
If you use Splunk Enterprise, you can configure inputs with Splunk Web. To configure the PowerShell input on universal forwarders, see Configure inputs with configuration files earlier in this topic.
Follow these steps to configure inputs with Splunk Web:
- In Splunk Web, select Settings > Data inputs.
- Select PowerShell v3 modular input.
- Click New.
- Enter an input name in the Name field.
- Enter a command or path to a script in the Command or Script Path field.
- Enter an interval or cron schedule in the Cron Schedule field.
- Click the More Settings checkbox to select the source type, host, and default index.
- Click Next.
Write scripts for the PowerShell input
The Splunk platform provides one modular PowerShell input handler. The PowerShell handler supports Microsoft PowerShell version 3 and higher.
The PowerShell modular input provides a single-instance, multi-threaded script host that provides a supporting schema, XML configuration through the stdin
input/output data stream, and XML streaming output. See Create custom data inputs for Splunk Cloud Platform or Splunk Enterprise on the Splunk Developer Portal.
You can define many PowerShell stanzas in an input configuration file and run them simultaneously. You can schedule each stanza using the cron
syntax. Because all scripts run within the same process, scripts share environment variables such as the current working directory.
The input doesn't set a host variable in your PowerShell environment. When you write a script for the input, do not refer to $host
or use the Write-Host
or Out-Host
PowerShell cmdlets. Instead, use either the Write-Output
or Write-Error
cmdlets.
The input converts all output to key/value pairs based on public properties that are defined in the schema.
The Splunk platform also includes a PowerShell module called LocalStorage
, which exposes three cmdlets:
Get-LocalStoragePath
Export-LocalStorage
Import-LocalStorage
These cmdlets use the Splunk platform checkpoint directory and let you maintain key/value pairs of data between scheduled runs of your script. Normally, data does not persist from one invocation to the next.
Specify paths
The input sets the SplunkHome
PowerShell variable so you can address scripts in add-ons by writing paths like this:
[powershell://MSExchange_Health] script=. $SplunkHome/etc/apps/TA-Exchange-2010/powershell/health.ps1
Besides $SplunkHome
, there are several other read-only constant variables:
Variable | Description |
---|---|
SplunkServerName
|
The name configured for this machine to use in events |
SplunkServerUri
|
The Splunk platform REST API address |
SplunkSessionKey
|
The session key or authentication token needed for accessing the Splunk platform REST API |
SplunkCheckpointPath
|
The path for storing persistent state |
SplunkServerHost
|
The name of the Splunk platform instance that you want to communicate with |
SplunkStanzaName
|
The name of the inputs.conf stanza that defined this script |
Handle output of PowerShell scripts
The Splunk platform takes each object that your script produces as an output and turns it into an event, wrapped in <event>
and <data>
tags. The Splunk platform converts the properties of each object into key/value pairs. However, the value can only be a quoted string, converted by calling the .ToString()
method. Thus, the output must be simple, and you must flatten any complex nested objects in your script before the script outputs them.
The following special property names have significance for the Splunk platform modular inputs and let you override the defaults in the inputs.conf stanza:
Property | Description |
---|---|
SplunkIndex
|
Overrides the index that the output is stored in. |
SplunkSource
|
Overrides the source for the output.
|
SplunkHost
|
Overrides the host name for the output.
|
SplunkSourceType
|
Overrides the sourcetype for the output.
|
SplunkTime
|
Overrides the time . If you do not specify this, all objects that your script generates in a single execution get roughly the same timestamp. This is because the script holds the objects for output until it finishes executing, and then marks the objects with the output time. You must specify this value in epoch or POSIX time, which is a positive integer that represents the seconds that elapsed since 0:00 UTC on Thursday, January 1, 1970.
|
These properties never appear as objects in the key/value output.
If you want to set these properties and override the defaults, use a calculated expression with the Select-Object
cmdlet or use the Add-Member
cmdlet to add a NoteProperty
property.
Caveats for handling PowerShell script output
The input currently requires that any PowerShell scripts it executes produce output objects that do not have any script properties. Pipe output through the Select-Object
cmdlet to ensure proper formatting.
The input currently doesn't process the output of scripts until your pipeline and runspace are finished. This means the input does not process ScriptProperty
values. It also means that all of your output essentially has the same timestamp, unless you override it using the SplunkTime
variable.
When writing your scripts, avoid long-running scripts. Do not write scripts that wait for things to happen unless the scripts exit every time there is output.
Monitor Windows performance | Monitor Windows host information |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release), 9.2.2406
Feedback submitted, thanks!