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
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
- 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
[package] check_for_updates = 0
- Splunkbase validates
app.confand 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:
[script://./bin/my_input.sh] interval = 60 sourcetype = my_sourcetype disabled = 0 [script://.\bin\my_input.bat] 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/system/local. For example, if you are packaging field extractions, they may be defined in stanzas in
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
(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|
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
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
- 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
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.
- tar your app folder, which creates a
- Use gzip to compress the folder into a
- Rename the file extension from
For example, package the app in the folder named
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:
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
$ 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.
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:
- Download and install WinACE from winace.com.
- Open WinACE.
- Navigate to your
- Highlight your app directory.
- Click the Create button in the upper toolbar.
- In the Add Files / Create Archive dialog, select the Options tab.
- Under Archive type select GZipTar.
- Click Add.
- Rename the package file extension from tar.gz to .spl.
- Congratulations, your package is ready for upload to splunkbase!
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:
- Install 7-Zip from http://www.7-zip.org/.
- Open 7-Zip.
- Navigate 7-Zip's file explorer to the parent directory of your app (for example
- Select your app's folder in the left pane of 7-Zip.
- Click "Add" (the green plus sign) on 7-Zip's toolbar.
- An "Add to Archive" dialog box will come up.
- Choose "tar" from the "Archive Format" dropdown box. The filename shown in the "Archive" textbox should change to have a ".tar" file extension.
- 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.
- Click OK to create the .tar file
- 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
- Click the "Add" button in the toolbar
- An "Add to Archive" dialog box will come up.
- Choose "GZip" from the "Archive Format" dropdown box. The filename shown in the "Archive" textbox should change to have a ".tar.gz" file extension.
- Click OK to create the new .tar.gz file
- 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.
- 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.
- Congratulations, your package is ready for upload to Splunkbase!
Step 7: Configure a setup screen in setup.xml
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