Splunk® Enterprise

Getting Data In

Download manual as PDF

Download topic as PDF

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.

Splunk Enterprise supports the monitoring of events received through PowerShell scripts. You can use the PowerShell input to run a single PowerShell command or reference a PowerShell script. Splunk Enterprise then indexes the output of these commands or scripts as events.

If you have Splunk Cloud and want to monitor script output, use the universal forwarder to consume the output and forward it to your Splunk Cloud deployment.

What do you need to monitor data with PowerShell scripts?

Activity Required permissions
Monitor data with PowerShell scripts Splunk Enterprise must run on Windows.
Splunk Enterprise must run as the Local System user to run all PowerShell scripts.
PowerShell v3.0 or later must be installed on the host.
Microsoft .NET version 4.5 or later must be installed on the host.

Configure inputs with configuration files

  1. Write a PowerShell command or script to capture the information you want.
  2. On the Splunk instance that is to run the script, open a PowerShell window.
  3. Copy inputs.conf from %SPLUNK_HOME%\etc\system\default to etc\system\local.
  4. Open the inputs.conf and edit it to enable a Windows PowerShell input.
  5. In the input, specify the command or the full path to your script in the script setting.
  6. (Optional) Specify a schedule on which the command or script should run with the schedule setting.
  7. Save inputs.conf.
  8. Restart Splunk Enterprise to enable the input.

PowerShell input configuration values

Splunk uses the following stanzas in inputs.conf to monitor data gathered by PowerShell.

Attribute Description Default
script The PowerShell command or script file to execute.

When you specify a script file (.ps1), prepend the script name with a period and a space (". ").

n/a
schedule How often the command or script should execute.

You can specify either a number to indicate the interval, in seconds, or a valid cron schedule format.

Script runs once
disabled Whether or not to enable the input.

Set to 1 to disable and 0 to enable

0 (enabled)

Following are some examples of how to configure the input:

Single command example: This example runs the Get-Process cmdlet and pipes that output to the Select-Object cmdlet using the host name that Splunk software has been 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 = 0 */5 * * *
    sourcetype = Windows:Process

Script example: This example runs the getprocesses.ps1 script located in %SPLUNK_HOME\etc\apps\My-App. It sets the source type for these events to Windows:Process. The script runs every 20 minutes from 9:00am to 4:40pm on Mondays to Fridays.

    [powershell://Processes-EX2]
    script = . "$SplunkHome\etc\apps\My-App\bin\getprocesses.ps1"
    schedule = 0 */20 9-16 * 1-5
    sourcetype = Windows:Process

For information on writing PowerShell scripts, see Write scripts for the PowerShell input.

Configure inputs with Splunk Web

  1. Select Settings > Data inputs from the system bar.
  2. Select PowerShell v3 modular input.
  3. Click New.
  4. Enter an input name in the Name field.
  5. Enter a command or path to a script in the Command or Script Path field.
  6. Enter an interval or cron schedule in the Cron Schedule field.
  7. Click the More Settings checkbox to select the source type, host, and default index.
  8. Click Next.

Write scripts for the PowerShell input

Architecture

Splunk Enterprise provides one modular PowerShell input handler. The PowerShell handler supports Microsoft PowerShell version 3 and later.

The PowerShell modular input provides a single-instance, multi-threaded script host that provides a supporting schema, XML configuration through the stdin stream, and XML streaming output.

You can define many PowerShell stanzas and run them simultaneously. You can schedule each stanza through the cron syntax. Because all scripts run within the same process, scripts share environment variables such as the current working directory.

Note: The input does not 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.

Splunk Enterprise also includes a PowerShell module called LocalStorage, which exposes three cmdlets:

  • Get-LocalStoragePath
  • Export-LocalStorage
  • Import-LocalStorage

These cmdlets use the Splunk Enterprise 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 variable so you can easily 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 Enterprise REST API address.
SplunkSessionKey The session key (authentication token) needed for accessing the Splunk Enterprise REST API.
SplunkCheckpointPath The path for storing persistent state
SplunkServerHost The name of the Splunk Enterprise instance that you want to communicate with.
SplunkStanzaName The name of the inputs.conf stanza that defined this script.

Handle output of PowerShell scripts

Splunk Enterprise takes each object that your script produces as an output and turns it into an event, wrapped in <event> and tags. Splunk Enterprise 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 should flatten any complex nested objects in your script before the script outputs them.

There are a few special property names which have significance for Splunk Enterprise modular inputs and let you override the defaults in the inputs.conf stanza. They are:

Property Description
SplunkIndex Overrides the index that the output will be stored in.
SplunkSource Overrides the "source" for the ouput.
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 will get roughly the same timestamp. This is because the script holds the objects for output until it has finished 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 have 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 does not 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.

PREVIOUS
Monitor Windows performance
  NEXT
Monitor Windows host information

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.1.0, 7.1.1, 7.1.2


Comments

Hi Martinho,

Thanks for your input. To address your concerns:

1. The dot-source examples shown in this document are examples that were provided by the engineers who built the input. While your suggestion to use the & call operator is technically valid, I would need to confer with them before I could make such a change.

2. This input is the direct descendant of the Splunk Add-on for Microsoft Powershell, and does actually use the Quartz implementation of cron, rather than the unix cron standard. I will update the page to include this information up front in an effort to reduce any confusion.

Malmoore, Splunker
October 31, 2016

I think you should be using the & call operator instead of the . dot source operator when specifying a script file. See https://technet.microsoft.com/en-us/library/hh847732.aspx for the difference details but in essence any script variables will be added to the current scope when using the dot source operator. This can lead to subtle bugs as the variables will persist between subsequent invocations of the script.

Martinho
October 26, 2016

This page references the Quartz.net implementation of cron triggers (which includes seconds and can have 6 segments).
This is not valid and I suspect comes from copying the documentation of an earlier implementation. I suggest you reference the http://docs.splunk.com/Documentation/Splunk/latest/Alert/Definescheduledalerts#Using_cron_expressions documentation or https://en.wikipedia.org/wiki/Cron#CRON_expression instead.

Martinho
October 26, 2016

Hi Machiel,

I fixed the typo in the script example.

The input should accept a positive integer for the "schedule" attribute. If it doesn't, it's a bug, and should be reported. Please open a support case so that we can get a case number assigned to it and have some engineering resources look at it. Thanks!

Malmoore, Splunker
April 13, 2016

"You can specify a number to indicate the interval in seconds" did not work for me.
Also, please be aware that
script=$SplunkHome/etc/apps/TA-Exchange-2010/powershell/health.ps1
should be
script= . "$SplunkHome/etc/apps/TA-Exchange-2010/powershell/health.ps1"

Machiel
April 13, 2016

Hi,

I updated the page to give a better explanation on what 'epoch time' is.

Malmoore, Splunker
January 29, 2016

Note: SplunkTime must be in epoch time

Johnberwick
January 28, 2016

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters