About files and directories for apps and add-ons
You can share any extension to Splunk - not just the views and navigation you find in an app, but saved searches, scripted inputs, and Splunk knowledge. To do this, place the necessary files in a directory for distribution to the recipient's
$SPLUNK_HOME/etc/apps directory. You can share an extension even if it doesn't have a UI environment of its own.
Apps vs. add-ons
You can add views and navigation along with other extensions to make a separate app, but this is not necessary. Extensions such as field extractions or scripted inputs may not necessarily benefit from a separate UI with a distinct URL and a collection of views and dashboards. You can provide the benefits without creating a full-blown app that shows up on the App menu. In this case, you package the extension as an add-on. An add-on is essentially an app that has no UI of its own and exists only as a container for other things (such as saved searches or scripted inputs) that are shared globally.
What can an app or add-on do?
Apps and add-ons can both include:
- scripted inputs or other input types
- field extractions for a specific source type (often implemented with an input method)
- scripted lookups or searches
- saved searches that can be accessed from the Search app
- views and navigation
- event types
- workflow actions
What is the difference?
- apps are set to Visible and must have a navigation file. Apps have a separate URL and appear on the App menu. Apps are not restricted to dashboards and searches, although in practice, they are often view-intensive.
- add-ons are set to Not Visible. They do not have a separate URL and do not show up on the App menu. An add-on can have views, but they show up under an existing app (for example, the Search app). Every object in an add-on -- views, saved searches, navigations, etc. -- must be globally available in order to be accessible. See App architecture and object ownership in the Admin manual.
Apps vs. add-ons are something of a marketing distinction. From the point of view of the code, apps and add-ons are created and administered as apps. All apps and add-on have a separate folder in
$SPLUNK_HOME/etc/apps/ and an
app.conf file. The following table summarizes the difference between apps and add-ons:
|navigation file required (see Build navigation for your app)||navigation file optional|
|appears on App menu||does not appear on App menu|
|has dedicated URL||does not have dedicated URL|
|objects accessed using app||objects accessed using other apps; must be globally available|
For another view of apps and add-ons, see What are apps and add-ons? in the Admin manual.
The visibility setting determines whether an extension can be considered an app and appear on the App menu. To set visibility:
1. Create a directory under
%SPLUNK_HOME%\etc\apps on Windows), for example
$SPLUNK_HOME/etc/apps/<addon_name>. This is called
$APP_HOME for the rest of this topic.
2. Restart Splunk
3. Go to Manager > Apps and navigate to the configuration screen for your app or add-on by clicking on the name of your directory.
4. Select whether you want to make the extension Visible.
Note: You can also set app visibility using the
app.conf file in the
$APP_HOME/default/ directory. To do this, open or create
app.conf in a text editor and edit or create the ui stanza. For example, to set an add-on to be not Visible:
[ui] is_visible = false
Files and directories for apps and add-ons
If you are sharing your app or add-on, make sure you have all the files you need in the correct location under the home directory for your app ($APP_HOME). To allow users to make their own customizations without being clobbered by later updates of your app, you move all the files in
$APP_HOME/default/. Also check for files and stanzas that may be scattered around the system outside of the app's directory. Depending on the functionality you have implemented, the followings file may show up:
|file or directory||app||add-on||comments|
|$SPLUNK_HOME/etc/apps/<app_directory> ($APP_HOME)||required||required||dedicated directory under $SPLUNK_HOME/etc/apps/|
|$APP_HOME/appserver/static/||Directory for web resources - such as images, CSS, or HTML - used by your app or add-on|
|$APP_HOME/appserver/static/appIcon.png||recommended||recommended||Icon for app or add-on displayed in Launcher and Splunkbase. Icon should be in PNG format and 36px x 36px in size.|
|$APP_HOME/appserver/static/screenshot.png||recommended||not required||Screenshot or splash screen for app or add-on displayed in Launcher. Image must be in PNG format. Display dimensions are 623px x 350px - will be extended with white if smaller, scaled if larger. For best results, make sure the image size is in the 98:55 ratio and do not include browser chrome in your image.|
|$APP_HOME/appserver/static/documentation.pdf||optional||optional||Downloadable PDF documentation for your app or add-on.|
|$APP_HOME/bin/||Directory for custom scripts for searches or scripted inputs.|
|$APP_HOME/bin/*.sh, *.bat, *.py, *.pl, etc.||optional||optional|
|$APP_HOME/default/||Directory for configuration files specific to your app or add-on|
|$APP_HOME/default/app.conf||required||required||File that sets app name, author, description; app visibility (app vs. add-on); and any custom configuration file settings for the app. See configure app.conf in the Developer manual and app.conf in the Admin manual for more information.|
||Visibility setting in app.conf that determines whether package has a separate UI (app) or not (add-on).|
|$APP_HOME/default/*.conf||optional||optional||Additional configuration files required by your app or add-on. Pretty much any .conf can show up here, except for those files that define global settings. See Step 3: add configurations in the Developer manual and About configuration files in the Admin manual for more information about configuration files.|
|$APP_HOME/default/setup.xml||optional||optional||File for custom setup window for your app or add-on.|
|$APP_HOME/default/data/ui/||Directory for navigation and views|
|$APP_HOME/default/data/ui/nav/default.xml||optional||optional||Navigation specific to your app or add-on. See build navigation for your app in the Developer manual for more information.|
|$APP_HOME/default/data/ui/views/*.xml||required||optional||Views specific to your app or add-on; an app must have one or more views. See Build a dashboard using advanced XML, Build a form search using advanced XML and advanced views in the Developer manual for more information.|
|$APP_HOME/local/||Directory for user-generated configuration files|
|required||required|| Include an empty |
|$APP_HOME/lookups/||Directory for lookup tables|
|$APP_HOME/lookups/*.csv||optional||optional||CSV file for lookups|
|$APP_HOME/metadata/||Directory for permissions|
|$APP_HOME/metadata/default.meta||required||optional||File that sets default permissions for the app or add-on; when file is missing, permissions are private. Users set permission overrides in $APP_HOME/metadata/local.meta. See Step 5 Set permissions in the Developer manual for more information.|
|$APP_HOME/README.txt||recommended||recommended||Readme that contains instructions on installing and configuring your app or add-on, as well as any hints for troubleshooting.|
Set up app.conf
When you use app builder to create an app, it automatically creates an app.conf file and enables a UI context for your app. You still need to define the launcher stanza before you share your app on Splunkbase. If you have built an add-on directly, you may need to create your own app.conf using a text editor.
To instrument the difference between an app and an add-on, set the Visible setting for the app in Manager. You can also set the
is_visible setting in the
[ui] stanza in the
Example app.conf for an add-on
Example app.conf for an app with updated images
Step 8: Package your app or add-on
Setup screen example
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18