Splunk® Enterprise

Developing Views and Apps for Splunk Web

Acrobat logo Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Acrobat logo Download topic as PDF

Step 8: Package your app or add-on

You can share your extensions to Splunk Enterprise on Splunkbase and make them available to everyone in the Splunk community. You can show off anything you have done to make Splunk Enterprise easier or more universal -- not just views, dashboards, and saved searches, but also scripted inputs, field extractions, workflow actions, lookups, event types and more. All you have to do is place your work in a dedicated directory and make sure everything is clean and works outside your special environment. Then add or update your app.conf file, icon, and screenshot to show off your extension in Launcher. Use tar.gz or .tgz to package your work and upload it.

Prepare your app or add-on

Important: If you plan to list your app or add-on on Splunkbase, you must ensure that the name of your app and references trademarks in related materials (such as marketing literature and documentation) meet the requirements specified in "Naming conventions for content on Splunkbase" in the Working with Splunkbase manual.

Before you package your app or add-on, make sure you have all the components and that they work:

1. If you have not already done so, create a dedicated directory for your app or add-on under $SPLUNK_HOME/etc/apps/ (for example: $SPLUNK_HOME/etc/apps/<app_name>). If you created an app using app builder, this has been created for you. This directory is denoted by $APP_HOME for the rest of this topic.

2. Create or edit your $APP_HOME/default/app.conf file. If you created an app using app builder, app.conf has been created for you but you still need to add a stanza to have a description of your app show up in Launcher. If you are packaging an add-on, you need to create your app.conf file.

3. 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 defined in app.conf.
  • By default, Splunk Enterprise checks for updates to an app. If you do not want the software to check for updates, include the following in app.conf:
check_for_updates = 0
  • Splunkbase validates app.conf and other app files and does not allow you to upload if there are errors.

4. If you want an icon or screenshot on Splunkbase or in the Launcher, create an icon and put it in $APP_HOME/appserver/static. If you are packaging an app, you can create a screenshot and place it in the same location. See Files and directories for apps and add-ons for requirements.

5. Place any scripts in the $APP_HOME/bin directory and make sure $APP_HOME/default/inputs.conf is set up correctly. If your app or add-on includes scripted inputs, scripted searches, or scripted lookups, you should follow general best practices for writing and testing the scripts. For example:

  • Include any dependencies your app or add-on needs to run outside of your environment. You may want to test it on a different system to make sure it works out of the box.
  • Make sure fields, event types, or other information tags adhere to the Splunk Common Information Model Add-on. This ensures that your app works with other Splunk apps and instances.
  • Scripts that serve their own web page and need a new REST endpoint must be specified in restmap.conf.
  • On *nix platforms, you can use environment variables to set locations in any scripts within your app or add-on so that they only have to be set once. If you do so, make sure to include this information in your README.txt.
  • (Optional) Write a setup screen to allow your users to configure local settings.
  • 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 include an inputs.conf that can enable either one. You can enable both options by default (only one will run), write a setup script to allow the user which option to enable, or give the user manual instructions on how to enable the option they want. An example with both input types enabled:
interval = 60
sourcetype = my_sourcetype
disabled = 0

interval = 60
sourcetype = my_sourcetype
disabled = 0

6. Make sure you have the correct configuration files, views, and navigations for your app or add-on. Objects created prior to the development of the app or add-on may be in $SPLUNK_HOME/etc/apps/search/local or $SPLUNK_HOME/etc/system/local. For example, if you are packaging field extractions, they may be defined in stanzas in props.conf and/or transforms.conf in the Search app. Wherever you make use of a stanza in a .conf file, you need to:

(a) create a blank version of each relevant .conf file in your $APP_HOME/default directory.

(b) copy the stanza heading and the relevant lines from the original .conf file to the version in $APP_HOME/default. Do not copy lines or stanzas that are not directly relevant to your app.

Where it's hiding Move to
$SPLUNK_HOME/etc/system/local/   $APP_HOME/default/
$SPLUNK_HOME/etc/apps/search/local/   $APP_HOME/default/
$SPLUNK_HOME/etc/users/admin/<app_name>/ $APP_HOME/default/
$APP_HOME/metadata/local.meta $APP_HOME/metadata/default.meta

See Files and directories for apps and add-ons for the correct file structure you need to share an app.

See About configuration files for an overview of Splunk Enterprise configuration files, and a list and description of all configuration files.

7. Verify permissions for each object in your app or add-on and change any permissions that aren't set correctly. You can set permissions using Settings in Splunk Enterprise, or by editing default.meta. If you are creating an add-on that is not Visible, you must make each object globally available. For a general overview of setting permissions, see Manage knowledge object permissions in the Knowledge Manager manual. For instructions on setting app permissions, see Step 5: set permissions in the Developer manual. If you set permissions through Manager, make sure that the permissions end up in default.meta and not local.meta.

8. Validate the XML for your views and navigation by running validate_all.py. See Use XML Schemas in this manual for more information.

9. Document your app. You can distribute your documentation in any of the following ways:

  • A README.txt file in your $APP_HOME directory
  • Documentation directly on your Splunkbase page. Document your app or add-on in a local file first and then copy and paste the documentation into the Splunkbase page.
  • A PDF file in $APP_HOME/appserver/static/

10. 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 tarring the final version.

11. Tar and zip your app as described in the next section.

12. Test your package.

  • Extract your package in a clean Splunk Enterprise install in a different location and environment than the one where you built your app or add-on.
  • Log in as a different Splunk Enterprise user from the one you used to create the app.
  • You may also want to test it with earlier versions of Splunk Enterprise.

Packaging your app for Splunkbase

The final step before uploading your app to Splunkbase is packaging. This means taking your app's directory and turning it into a single compressed file which can be uploaded to Splunkbase.

Splunkbase uploads are required to have the .spl file extension, e.g. myapp.spl. SPL format is identical to .tar.gz format (also known as a "tarball"). The only difference is the file extension.

Make sure you have placed all the app components in the correct location, have moved all customizations from /local to /default, and have tested your app before you package it.

You can use your preferred file-compression utility to create the .tar.gz-format file, or you can follow the OS-specific instructions below.

Packaging on Unix/Linux/Mac

On Linux/Unix systems, creating a .tar.gz is straightforward because tools for creating .tar.gz archives are packaged with almost all *nix OS distributions.

  1. tar your app folder, which creates a .tar file.
  2. Use gzip to compress the folder into a .tar.gz file.
  3. Rename the file extension from .tar.gz to .spl.

For example, package the app in the folder named MyApp:

cd $SPLUNK_HOME/etc/apps
tar cv MyApp/ > MyApp.tar
gzip MyApp.tar
mv MyApp.tar.gz MyApp.spl

Packaging on Mac

On Mac OS X, use gnutar rather than the default tar packaged with the OS. The default tar utility generates a series of warnings that can be problematic when packaging your app.

For example, you can do the following:

alias tar='gnutar'

For Mac OS 10.5 and later, set the environment variable COPYFILE_DISABLE before using tar to avoid unwanted metadata files being added to your .spl file, which may cause your upload to fail. For earlier versions of OS X, set COPY_EXTENDED_ATTRIBUTES_DISABLED.

$ export COPYFILE_DISABLE=true

Packaging on Windows

Unlike ZIP files, which Windows handles natively, creating .tar.gz-format files requires using a third-party compression utility not packaged with the Windows OS.

Using WinACE

The following is an example procedure that uses WinACE, a shareware product. compression/decompression tool that supports all modern versions of Windows. To package your app using WinACE, follow these steps:

  1. Download and install WinACE from winace.com.
  2. Open WinACE.
  3. Navigate to your $SPLUNK_HOME\etc\apps directory.
  4. Highlight your app directory.
  5. Click the Create button in the upper toolbar.
  6. In the Add Files / Create Archive dialog, select the Options tab.
  7. Under Archive type select GZipTar.
  8. Click Add.
  9. Rename the package file extension from tar.gz to .spl.
  10. Congratulations, your package is ready for upload to splunkbase!

Using 7-Zip

Following is an example procedure that uses 7-Zip, a free compression/decompression tool that supports all modern versions of Windows. To package your app using 7-Zip, follow these steps:

  1. Install 7-Zip from http://www.7-zip.org/.
  2. Open 7-Zip.
  3. Navigate 7-Zip's file explorer to the parent directory of your app (for example c:\Program Files\Splunk\etc\apps).
  4. Select your app's folder in the left pane of 7-Zip.
  5. Click "Add" (the green plus sign) on 7-Zip's toolbar.
  6. An "Add to Archive" dialog box will come up.
  7. Choose "tar" from the "Archive Format" dropdown box. The filename shown in the "Archive" textbox should change to have a ".tar" file extension.
  8. Click the "..." button in the upper-right-corner to choose a location for your temporary tar file outside the Splunk Enterprise Program Files folders, because you won't want these files cluttering up your actual Splunk Enterprise install.
  9. Click OK to create the .tar file
  10. Now it's time to zip up the .tar file into a .tar.gz. Back in 7-Zip's main UI, select the .tar file you created in the previous step
  11. Click the "Add" button in the toolbar
  12. An "Add to Archive" dialog box will come up.
  13. Choose "GZip" from the "Archive Format" dropdown box. The filename shown in the "Archive" textbox should change to have a ".tar.gz" file extension.
  14. Click OK to create the new .tar.gz file
  15. To test your new package, double-click on the new .tar.gz file in 7-Zip to drill into it. You should see a single .tar file inside it. Double-click again, and you'll see a single folder which contains your app content.
  16. Finally, assuming you're satisfied that your app has been packaged properly, rename your package file from a .tar.gz extension to an .spl file extension.
  17. Congratulations, your package is ready for upload to Splunkbase!
Last modified on 18 August, 2016
Step 7: Configure a setup screen
About files and directories for apps and add-ons

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.3.14, 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.4.11

Was this documentation topic helpful?

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