Get data from APIs and other remote data interfaces through scripted inputs
The Splunk platform, through a universal or heavy forwarder, can accept events from scripts that you provide.
Scripted input is useful combined with some Windows and *nix command-line tools, such as ipconfig
, iostat
, netstat
, top
, and so on. You can use scripted input to get data from APIs, other remote data interfaces, and message queues. You can then use commands like vmstat
and iostat
on that data to generate metrics and status data. On Windows platforms, you can enable text-based scripts, such those in Perl and Python, with an intermediary Windows batch (.bat) or PowerShell (.ps1) file.
You can configure scripted inputs from the Settings menu in Splunk Web on Splunk Enterprise, or by editing the inputs.conf configuration file on a universal or heavy forwarder.
When a scripted input launches a script, that script inherits the Splunk Enterprise or universal forwarder environment. The only environment variable that might cause problems with scripts and script output generation is the library path, most commonly known as LD_LIBRARY_PATH
on Linux, Solaris, and FreeBSD. When you use scripted inputs on a Splunk platform instance, clear any environment variables that can affect the operation of a script.
Splunk Enterprise and the universal forwarder log any messages that scripted inputs send to the stderr
I/O channel to splunkd.log
.
Prerequisites
To add a scripted input, you must first write an input. To learn how to write scripted inputs, see Scripted input examples for Splunk Cloud Platform or Splunk Enterprise on the Splunk developer portal.
Add a scripted input in Splunk Web
On a Splunk Enterprise or heavy forward instance, follow these high-level steps to add a scripted input in Splunk Web:
- Go to the Add New page.
- Select the input source.
- (Optional) Specify input settings.
- Review your choices.
Go to the Add Data page
To get to the Add Data page using Settings, follow these steps:
- In Splunk Web, click Settings.
- Click Data Inputs.
- Click Scripts.
- Click New to add an input.
To get to the Add Data page using the Splunk Web homepage, follow these steps:
- In Splunk Web, click the Add Data.
- Click Monitor to monitor a script on the local machine, or click Forward to forward data from a script on a remote machine.
Splunk Web displays the Add Data - Select Source page. - In the left pane, select Scripts.
Forwarding data from scripted inputs requires additional setup.
Select the input source
- In the Script Path drop-down list, select the path where the script resides.
Splunk Web updates the page to include the Script Name drop-down list. - In the Script Name drop-down list, select the script that you want to run.
Splunk Web updates the page to populate the Command field with the script name. - In the Command field, add any arguments needed to invoke the script.
- In the Interval field, enter the amount of time, in seconds, that Splunk Enterprise waits before invoking the script.
- (Optional) In the Source Name Override field, enter a new source name to override the default source value, if necessary.
- Click Next.
Specify input settings
You can specify the application context, default host value, and index on the Input Settings page. All of these parameters are optional. For more about setting the host value, see About hosts.
Setting the Host on this page sets the host field only in the resulting events. It does not direct Splunk Enterprise to look on a specific host on your network.
- Select the source type for the script. Click Select to pick from the list of available source types on the local machine, or click Manual to enter the name of a source type.
- Select the appropriate Application context for this input.
- Set the Host name. You have several choices for this setting.
- Set the Index that Splunk Enterprise will send data to. Unless you defined multiple indexes to handle different types of events, leave the value as default. In addition to indexes for user data, Splunk Enterprise has multiple utility indexes, which also appear in this drop-down list.
- Click Review.
Review your choices
After specifying all your input settings, review your selections. Splunk Web lists all options you selected, including the type of monitor, the source, the source type, the application context, and the index.
- Review the settings.
- If they do not match what you want, click the left angle bracket ( < ) to go back to the previous step in the wizard. Otherwise, click Submit.
Splunk Web displays the Success page.
Add a scripted input with the inputs.conf configuration file
You add a scripted input in the inputs.conf file by adding a [script]
stanza within that file. You can do this on Splunk Enterprise or the universal forwarder, and then forward that information to Splunk Cloud Platform.
Syntax
The syntax for the [script]
stanza appears as follows, where $SCRIPT
is the full path to the location of the script:
[script://$SCRIPT] <attrbute1> = <val1> <attrbute2> = <val2> ...
$SCRIPT
can also be a file path that ends in the .path
suffix. This special suffix lets you use the stanza to point to another command or script that exists anywhere on the host file system. See Use the .path suffix to reference external scripts. The file that you refer to in the stanza must follow the location restrictions described in the following section, Where to place the scripts for scripted inputs.
Where to place the scripts for scripted inputs
The script that you refer to in $SCRIPT
can reside in only one of the following places on the host file system:
- $SPLUNK_HOME/etc/system/bin
- $SPLUNK_HOME/etc/apps/<your_app>/bin
- $SPLUNK_HOME/bin/scripts
As a best practice, put your script in the bin/
directory that is nearest to the inputs.conf file that calls your script on the host file system. For example, if you configure $SPLUNK_HOME/etc/system/local/inputs.conf, place your script in $SPLUNK_HOME/etc/system/bin/. If you work on an application in $SPLUNK_HOME/etc/apps/$APPLICATION/, put your script in $SPLUNK_HOME/etc/apps/$APPLICATION/bin/.
Attributes
All attributes are optional. Here is the list of available attributes:
Attribute | Description | Default |
---|---|---|
interval = <number>|<cron schedule>
|
How often to run the specified command. Specify either an integer value representing seconds or a valid cron schedule.
When you specify a Splunk Enterprise keeps one invocation of a script per instance. Intervals are based on when the script completes. If you configure a script to run every 10 minutes and the script takes 20 minutes to complete, the next run occurs 30 minutes after the first run. For constant data streams, enter 1 or a value smaller than the script interval. For one-shot data streams, enter -1. Setting |
60 seconds |
index = <string>
|
The index where events from this input are stored. Splunk Enterprise prepends the For more information about the index field, see How indexing works in the Managing Indexers and Clusters of Indexers manual. |
main , or whatever you have set as your default index.
|
sourcetype = <string>
|
Sets the Explicitly declares the source type for this data, as opposed to letting it be determined automatically. This is important both for searchability and for applying the relevant formatting for this type of data during parsing and indexing. Sets the |
There is no hard-coded default. Splunk Enterprise picks a source type based on various aspects of the data. |
source = <string>
|
Sets the Do not override the Splunk Enterprise prepends |
The input file path |
disabled = <true | false>
|
Whether or not the input will run. Set to true if you want to disable the input. | false
|
Run scripts continuously
If you want the script to run continuously, write the script to never exit and set it on a short interval. This helps to ensure that if a problem occurs, the script restarts. Splunk Enterprise keeps track of scripts it spawned and shuts them down on exit.
Use a wrapper script
As a best practice, write a wrapper script for scripted inputs that use commands with arguments. In some cases, the command can contain special characters that the scripted input escapes when it validates text that you enter in Splunk Web. Updates to a previously configured input will then fail to save.
When validating text, Splunk Enterprise escapes characters that can't be in paths, such as the equal sign (=) and semicolon (;). For example, the following scripted input is not correctly saved when you edit it in Splunk Web because the scripted input escapes the equal (=) sign in the parameter to the myUtil.py utility:
[script://$SPLUNK_HOME/etc/apps/myApp/bin/myUtil.py file=my_datacsv] disabled = false
To avoid this problem, write a wrapper script that contains the scripted input, or use the special .path
argument for the scripted input stanza name. For information on writing wrapper scripts, see Create custom data inputs for Splunk Cloud Platform or Splunk Enterprise in the Splunk Developer Guide.
When you update scripted inputs by editing inputs.conf directly, this validation does not occur.
Use the .path suffix to reference external scripts
As an alternative to writing a wrapper script, you can configure the scripted input to reference a script or executable that is anywhere on the host file system.
The script that you refer to can have a single line that calls the script or executable that you want. You can use this file to call a runtime environment that is outside of the Splunk Enterprise environment. For example, if you have both Splunk Enterprise, which comes with Python, and a second installation of Python on the same host, you can use the .path
method to refer to the second Python installation.
Follow these steps to refer to external scripts with the .path suffix:
- Use Splunk Web or edit inputs.conf and specify a scripted input stanza with a script name that ends in
.path
. For example:
[script://myfile.path] disabled = 0
- Place the file that you reference in the stanza in the appropriate directory, as described in Where to place the scripts for scripted inputs.
- Edit the file to specify the script or executable you want. For example:
/path/to/myscript -arg1 arg -arg2 arg
Examples of scripted inputs with inputs.conf
The following examples configure various scripted inputs with inputs.conf.
Unix top command
This example shows the use of the UNIX top
command as a data input source:
- Create a new application directory. This example uses
scripts/
.
$ mkdir $SPLUNK_HOME/etc/apps/scripts
- Create a
bin/
directory. All scripts must be run out of abin/
directory inside your application directory.
$ mkdir $SPLUNK_HOME/etc/apps/scripts/bin
- Create a script within the
bin/
directory. This example uses a small shell scripttop.sh
.
$ #!/bin/sh top -bn 1 # linux only - different OSes have different parameters
- Make the script executable.
chmod +x $SPLUNK_HOME/etc/apps/scripts/bin/top.sh
- Test that the script works by running it with the shell.
The script sends one$SPLUNK_HOME/etc/apps/scripts/bin/top.sh
top
output. - Add the script entry to inputs.conf in $SPLUNK_HOME/etc/apps/scripts/local/.
[script:///opt/splunk/etc/apps/scripts/bin/top.sh] interval = 5 # run every 5 seconds sourcetype = top # set sourcetype to top source = script://./bin/top.sh # set source to name of script
- By default, Splunk Enterprise breaks the single
top
entry into multiple events, so you might need to modify props.conf to fix this issue. If necessary, edit props.conf and configure the server to break only before something that doesn't exist in the output.
For example, adding the following to $SPLUNK_HOME/etc/apps/scripts/default/props.conf forces all lines into a single event:[top] BREAK_ONLY_BEFORE = <stuff>
Since there is no timestamp in the
top
output, you must tell Splunk Enterprise to use the current time. Set the following parameter in props.conf:
DATETIME_CONFIG = CURRENT
Reference an external script with the .path stanza
The following example uses the special .path stanza setting to reference an external build of Python to run a script on your host.
- Edit inputs.conf.
[script://loglogs.path] disabled = 0
- Place or create loglogs.path in $SPLUNK_HOME/etc/system/bin.
- Edit loglogs.path to reference the external version of Python.
/usr/bin/python logit.py --source /opt/files/my_files --target /opt/files/my_files/processed --logfile /opt/src/my_sources/logfiles
Set interval attribute to cron schedule
In the previous example, you can also set the interval
attribute to a cron schedule by specifying strings.
For example, the following string means the script runs once an hour at the top of the hour:
0 * * * *
The following string means the script runs every 15 minutes from 9 AM until 5 PM, Monday to Friday.
*/15 9-17 * * 1-5
The following string means the script runs at 15, 35, and 55 minutes after the hour between midnight and 7 AM and again between 8 PM and midnight, on the first of every even-numbered month, such as February, April, June, and so on.
15,35,55 0-6,20-23 1 */2 *
For more information about setting cron schedules, see CRONTAB(5) in https://crontab.org on the Crontab website.
Monitor changes to your file system | Overview of event processing |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.11, 8.1.13, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.1.7, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.2.4, 9.3.0, 9.3.1, 9.3.2, 9.4.0, 8.1.10, 8.1.12, 8.1.14, 8.1.2
Feedback submitted, thanks!