Splunk® Add-on Builder

Splunk Add-on Builder User Guide

Download manual as PDF

Download topic as PDF

Configure data collection using a shell command

In Configure Data Collection, configure the data inputs and setup page for your add-on. This page displays a list of data inputs that you have configured for your add-on. Data inputs determine how you will get data into your add-on:

AOB2.2 chooseinputmethod.jpg

Once you have configured data inputs for your add-on, you can manage them from the Configure Data Collection page in Add-on Builder. Data inputs you configure for your add-on also appear on the Inputs page of the add-on.

  • Data inputs must be enabled so that Splunk Enterprise can start indexing the data from them. You'll need indexed data if you want to perform field extractions and data model mappings. Data inputs you configure are enabled by default.

Users of your add-on should create data inputs from your configuration within the add-on. Do not direct users to use the Settings > Data inputs page in Splunk Enterprise. When users open your add-on, the Inputs page provides the option to create a new input.

Add a data input using shell commands

Get data into your add-on by using a script of shell commands.

  1. On your add-on homepage, click the Configure Data Collection icon.
  2. On the Configure Data Collection page, click Add Data.
    The Create Data Input wizard starts.
  3. On the Choose Input Method page, select Modular input using shell commands.
  4. On the Data Input Properties tab:
    • Enter a name for the source type to create for this data input.
    • Enter an input display name, internal name, and description.
    • Specify a collection interval indicating how often to retrieve data using this input, in seconds.
  5. Optionally, click the Data Input Parameters tab to define any parameters that are required for users to configure your data input.
    For each parameter, drag a field from the Component Library to the center panel, then specify its properties in the Property Editor.
  6. Optionally, click the Add-on Setup Parameters tab to define any parameters that are required for users to configure your add-on.
    • Select predefined options to prompt for account, proxy, or logging settings.
    • Add custom inputs by dragging fields from the Component Library to the center panel panel. Select an input to specify its properties in the Property Editor.
    • For more about setup pages, see Create a setup page.

  7. Click Next.
  8. On the Data Input Definition tab:
    • Under Command settings, enter the shell commands.
    • Under Data input parameters, enter a sample value for each data input parameter for testing purposes.
      To use a value from a data input parameter in the REST URL, use the format ${internal_name}, using the internal name defined for the parameter in the previous step. For more about passing parameter values to a REST call, see Pass values from data input parameters and Pass values from setup parameters.
  9. If you created a setup page, click the Add-on Setup Parameters tab to enter sample values for setup parameters for testing purposes.
  10. Click the Data Input Definition tab, then click Test to run the shell commands and test the data input configuration.
    The Output section indicates whether the shell commands succeeded (sample data is displayed) or failed (the error message is displayed).
  11. Click Save to save the data input, then click Finish.


The Add-on Builder displays a summary of the new data input, along with suggested next steps.

Pass values from data input parameters

You can pass parameter values to a variable in a REST URL, a REST header, a REST body, and in a shell command. Following the Mako syntax, use the format ${varname} for the variable. Then, define a modular input variable for varname.

For example, let's say you want to use a URL such as http://localhost:5111/api/task/<taskID>, where <taskID> is a variable value.

When you define the REST API input, on the Inputs & Parameters step, click the Data Input Parameters tab and add an input variable for Task ID with the internal name "taskid":

AOB2.2 inputparameters1.jpg

Next, on the Define & Test step when you specify the REST URL, use "http://localhost:5111/api/${taskid}". To test it, use an initial value, such as "t123". The resulting REST URL is "http://localhost:5111/api/task/t123".

AddonBuilder2.1 InputVariableDefn.png

When users open your add-on, they can create instances of this data input on the Inputs page. The form displays the Task ID field as one of the data input parameters you configured:

AddonBuilder2.1 TaskInput.png

Pass values from setup parameters

When referring to setup parameters, you must include a namespace string before the parameter name to get the value from the parameter. The following shows an example, where param_name is the parameter name:

${__settings__.additional_parameters.param_name}

For example, let's say you have a text input on your setup page that prompts the user for an API token, with the internal name "api_token". To pass the value of the API token to the REST call, use the following format:

api-key=${__settings__.additional_parameters.api_token}

We recommend you do not set account, proxy, or logging fields directly. You can access the global account values as follows:

${global_account.username}
{{global_account.username}}

${global_account.password}
{{global_account.password}}

Learn more

For more information, see the following Splunk Enterprise documentation:

PREVIOUS
Configure data collection using a REST API call
  NEXT
Configure data collection using your Python code

This documentation applies to the following versions of Splunk® Add-on Builder: 2.2.0


Comments

Thanks! What kind of shell scripts are expected? How would be the output to be ingested? I tried with minor samples like "lsof", echo's, other complex scripts and despite trying many options I do not get events ingested. Check this question to get more info:

https://answers.splunk.com/answers/560566/add-data-from-script-or-python-program.html

Changux
August 4, 2017

Hi Changux,
Thanks for your comment. Could you share more info on what script you were using that caused a problem? Was there an error produced? Thanks!

Jrevell splunk, Splunker
August 4, 2017

Can you please share an example of code that works? I'm doing tests with no luck. Same for Python code. Thanks!

Changux
August 3, 2017

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