Package your app or add-on

Package your app or add-on

You can share your extensions to Splunk on Splunkbase and make them available to everyone in the Splunk community. You can show off anything you have done to make Splunk 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 you add or update your app.conf file, icon, and screenshot show off your extension in Launcher and package, tar, or zip your work and upload it.

Prepare your app or add-on

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/, e.g., $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, this 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.

• Important: Review the latest app.conf.spec documentation to ensure your app will upload correctly. Splunkbase now validates app.conf and other app files are correct, and will not allow you to upload if there are errors.

3. (Optional) 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.

4. Place any scripts in the $APP_HOME/bin directory and make sure $APP_HOME/bin/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.
• 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.
• Provide instructions to test your scripts outside of Splunk.
• 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

5. 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.

6. Verify permissions for each object in your app or add-on and change any permissions that aren't set correctly . You can set permissions via manager or by editing default.meta. If you are creating an add-on that is not Visible, you must make each object globally available. For an explanation of permissions, see Curate Splunk knowledge with Manager in the Knowledge Manager manual for instructions on setting 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.

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

8. 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. We recommend you document your app or add-on first and then cut and paste the documentation into the Splunkbase page.
• A PDF file in $APP_HOME/appbuilder/static/

9. 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.

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

11. Test your package.

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

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 idential to .tar.gz format (also known as a "tarball"). The only difference is the file extension.

Make sure you have placed all the app's 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. First you'll need to tar your app's folder, which creates a .tar file. Then you'll need to gzip the folder into a .tar.gz file. Finally, you'll need to rename the file extension from .tar.gz to .spl. Example commands are below:

$: tar cv appdirpath/ > appname.tar
$: gzip appname.tar
$: mv appname.tar.gz appname.spl

OS X users: You may need to set COPYFILE_DISABLE=true before using tar to avoid unwanted metadata files being added to your .spl file, which may cause your upload to fail.

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's 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. Congratulations, your package is ready for upload 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 Splunk's Program Files folders, since you won't want these files cluttering up your actual Splunk 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 Splunkbase!

• Was this topic useful?
• Post a comment