Package and publish a Splunk app

An easy way to deploy your Splunk app to other computers is to install the app from a package. A packaged app is is a compressed tar archive (a .tar.gz tarball) with the .spl file extension that includes the dashboards, reports, scripted and modular inputs, field extractions, workflow actions, lookups, event types, and other objects in your app. Users can install your packaged app directly using Splunk Web or the command line, and organizations can use deployment tools to distribute apps to their users.

    Note  This section also applies to Splunk add-ons.

You can share your app with the world by submitting it to Splunkbase. You'll need to meet certain requirements before you can upload your app package. For details, see the Working with Splunkbase manual, which describes the approval criteria and the submission process.

The general process is as follows:

  1. Prepare your app for packaging
  2. Package your app
  3. Install and test the package
  4. Submit the package to Splunkbase

 

Prepare your app for packaging

This section provides details about preparing your app for packaging and submission to Splunkbase by verifying the following areas:

App name and settings

Be sure to follow the naming conventions when choosing a name for your app. For details, see Naming conventions for apps and add-ons on Splunkbase in the Working with Splunkbase manual, which describes the requirements for the name of your app and the correct way to reference Splunk and third-party trademarks.

App settings are located in the $APP_HOME/default/app.conf file, which is created for you when using Splunk Web. Review the app.conf.spec documentation to ensure your app can be uploaded to Splunkbase:

  • Splunkbase requires an app ID, version string, and a description.
  • By default, Splunk Enterprise checks for updates to an app. To disable this feature, include the following stanza in the app.conf file:
  •     [package]
        check_for_updates = 0
        

Files and directories

An app requires a dedicated directory under $SPLUNK_HOME/etc/apps/, for example $SPLUNK_HOME/etc/apps/your_app_name. This directory is created for you when you use Splunk Web to create an app. This dedicated directory is denoted by $APP_HOME below.

The packaging process creates a snapshot of your app's directory structure and files, so before you submit your app to Splunkbase you must make sure the files for your app are in the correct locations and contain the correct information. Splunkbase validates all app files and does not allow you to upload the package if there are errors. For details, see Splunkbase file standards reference table in the Working with Splunkbase manual, which lists the standards that are used to evaluate your app when you submit it to Splunkbase.

Make sure any temporary local files are either moved to the proper location or are removed:

  • The $APP_HOME/default directory contains original versions of Splunk configuration files and dashboard source files, while the $APP_HOME/local directory contains user-modified versions of these files. While developing the app, files you modified might have been saved to the $APP_HOME/local directory. Move any modified Simple XML and HTML dashboards you want to keep in your app from the $APP_HOME/local/data/ui directory to the $APP_HOME/default/data/ui directory. When you have finished, remove local files including the app's $APP_HOME/local directory.
  • If your app needs user-supplied information (for example, an app that requires a Twitter account to analyze Twitter data), make sure to remove the information for your test account before packaging the app.

Scripts

Place any scripts for your app in the $APP_HOME/bin directory and make sure the inputs configuration file, $APP_HOME/default/inputs.conf, is set up correctly to run your scripts. See the inputs.conf.spec for details). If your app includes scripted inputs, scripted searches, or scripted lookups, follow the general best practices for writing and testing the scripts, including:

  • Include any dependencies that your app needs to run outside of your environment. Try testing your app on different systems and configurations.
  • Make sure fields, event types, and other information tags adhere to the Splunk Common Information Model to ensure that your app works with other Splunk apps.
  • Specify any scripts that serve their own web page and need a new REST endpoint in a RESTmap configuration file, $APP_HOME/default/restmap.conf. For details, see restmap.conf.spec.
  • On *nix platforms, you can use environment variables to set locations in any scripts within your app so that they only have to be set once. If you do so, make sure to include this information in your README file.
  • Provide instructions to test your scripts outside of Splunk Enterprise.
  • If your app is intended to run cross-platform, include both .sh and .bat files for scripted inputs and make sure the inputs configuration file, $APP_HOME/default/inputs.conf, can enable either one. You can enable both options by default (only one will run), write a setup script to allow the user to choose which option to enable, or provide users with instructions about how to enable the option they want. For example, the following excerpt from an inputs.conf file shows how to enable both input types:
  •     [script://./bin/my_input.sh]
        interval = 60
        sourcetype = my_sourcetype
        disabled = 0
    
        [script://.\bin\my_input.bat]
        interval = 60
        sourcetype = my_sourcetype
        disabled = 0
        

Configuration files

Make sure you have all of the correct configuration (.conf) files needed for your app. Some objects might be defined in Splunk Enterprise folders. For example, if you are packaging field extractions with your app, they might be defined in stanzas in the props.conf and transforms.conf configuration files for the Search app rather than in your app.

When you need to use a stanza from a configuration file:

  1. Create a blank version of the configuration file in the $APP_HOME/default directory.
  2. Check the following locations for relevant configuration settings, then copy the stanza heading and the relevant lines from the original configuration file to the version in $APP_HOME/default. Do not copy lines or stanzas that are not directly relevant to your app.
    • $SPLUNK_HOME/etc/system/local/
    • $SPLUNK_HOME/etc/apps/search/local/
    • $SPLUNK_HOME/etc/users/admin/app_name/

For an overview of Splunk Enterprise configuration files, and a list and description of all configuration files, see About configuration files in the Admin Manual.

Icons

If you want to display an icon for your app in Splunk Web, put the icon files in $APP_HOME/static. Icons are used in the following order of precedence such that the first icon found is the one that is used as the app icon on Splunkbase:

  • appIcon_2x.png
  • appIcon.png
  • appIconAlt_2x.png
  • appIconAlt.png

For more about app icons, see Configure app properties.

Dependencies

Include any dependencies your app needs to run outside of your environment. Try testing your app on different systems and configurations.

Make sure fields, event types, and other information tags adhere to the Splunk Common Information Model to ensure that your app works with other Splunk apps.

Setup page

If you need users to configure local settings when your app first runs, create and include a setup page.

For more, see Create a setup page for a Splunk app.

Permissions

Verify permissions for each object in your app and change any permissions that aren't set correctly.

You can set permissions by going to Settings > Access controls in Splunk Enterprise, or by editing the $APP_HOME/metadata/default.meta file directly. If you set permissions through Splunk Web, make sure the permissions are saved to default.meta rather than to local.meta. To do this, copy the relevant settings from the $APP_HOME/metadata/local.meta file to $APP_HOME/metadata/default.meta.

If you are packaging an add-on that is not set to Visible, you must make each object globally available.

XML validation

Validate the XML for your dashboards and navigation by running the validation script validate_all.py, located at $SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/schema/. This script validates all of the XML files that are located in $SPLUNK_HOME/etc/.

This example shows how to navigate to navigate to and run the script:

cd $SPLUNK_HOME/share/splunk/search_mrsparkle/exposed/schema/
$SPLUNK_HOME/bin/splunk cmd python validate_all.py

App documentation

Add documentation for your app, which you can distribute in various ways:

  • Update the README file in your app directory.
  • Provide documentation on the app's Splunkbase page.
  • Include a PDF file in $APP_HOME/appserver/static/.

 

Package your app

Before uploading your app to Splunkbase, you must package it, which means compressing the app directory into a single file. Splunkbase package uploads are required to use the SPL format, which is identical to the tar archive format (a "tarball"), except the SPL format uses the .spl extension rather than .tar.gz.

To package an app

  1. Open a command prompt and navigate to $SPLUNK_HOME/bin/.
  2. Enter the following at the command prompt, where your_app_name is the name of your app:

    On Mac, enter:

    ./splunk package app your_app_name

    On Windows, enter:

    splunk package app your_app_name
  3. Enter your Splunk username and password if you are prompted.
  4. The package file, your_app_name.spl, is created in $SPLUNK_HOME/etc/system/static/app-packages/.

 

Install and test the package

Before you submit your packaged app to Splunkbase for use on other computers, you should install and test it yourself:

  • Install your packaged app in a clean Splunk Enterprise installation in a different location and environment than the one where you built your app.
  • Log in as a different Splunk user from the one you used to create the app.
  • Try your app with earlier versions of Splunk Enterprise.
To install a packaged app from Splunk Web
  1. Click the Settings gear icon next to Apps.
  2. Click Install app from file.

 

Submit the package to Splunkbase

When you are ready to submit your app to Splunkbase, refer to Submit content to Splunkbase in the Working with Splunkbase manual for directions.