Splunk® Enterprise

Developing Views and Apps for Splunk Web

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

About files and directories for apps and add-ons

You can share any extension to Splunk Enterprise - not just the views and navigation you find in an app, but saved searches, scripted inputs, and 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
  • tags
  • 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:

app add-on
visible not visible
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.

Set visibility

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 (or %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.

DevNotVisible.png

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/local/ to $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:


Path App Add-on Comments
$SPLUNK_HOME/etc/apps/<app_name> ($APP_HOME) required required dedicated directory under $SPLUNK_HOME/etc/apps/
$APP_HOME/static/ Directory for web resources - such as images, CSS, or HTML - used by your app or add-on
$APP_HOME/static/appIcon*.png
$APP_HOME/static/appLogo*.png
recommended recommended Icon for app or add-on that displays on Splunk Enterprise home page, Splunk Bar, and the Search Bar. See Add app icon images for details.
$APP_HOME/appserver/static/[UploadedIconFile].png n/a n/a When you upload icon files using Splunk Web, Splunk Web places the icons in the appserver directory. From the command line, move uploaded icons that appear in the appserver directory to $APP_HOME/static/.

Uploaded icons appear in the appserver directory because of legacy behavior. See Add app icon images for details.

$APP_HOME/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.
[ui]
is_visible=true
[ui]
is_visible=false
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 local directory when you distribute your app or add-on. If the user makes any configuration changes via Manager, they will be stored here. The developer of an app or add/on should never place any shipping configurations in local, as subsequent revisions would end up clobbering the user's customizations.
$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 Splunk Apps. 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 app.conf file.

Example app.conf for an add-on

DeveloperPackageAddonDir.png Here is a sample directory and app.conf file for a simple add-on that provides a scripted input:
[ui]
is_visible = false
label = My Add-on

[launcher]
author=me
description=My Add-on provides scripted inputs that allow you to index your Specific Third-party Application in Splunk 4.0 or later.  
version="1.0" 

Note: author and version do not actually show in the Launcher app, but it's a good idea to include them.

  • author lets you get credit for your work; it appears in the app details in Manager > Apps.
  • version allows users to check the current version of their app.
    If you are uploading your app to Splunk Apps, make sure that the version number in app.conf matches the version number on Splunk Apps.

Example app.conf for an app with updated images

DeveloperPackageAppDir.png This example shows an app with the following:
  • UI context enabled
  • a launcher description
  • a build specification to ensure static web assets (such as images, CSS and Javascript) are updated for users.
[ui]
is_visible = true
label = My App

[launcher]
author=me
description=My App provides pre-built data inputs, searches, reports, alerts, and dashboards. This update provides a new user interface with flashier, more exciting icons.  
version="2.1"

[install]
build = 3 
PREVIOUS
Step 8: Package your app or add-on
  NEXT
Setup screen example

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15


Comments

Thanks Scullion. I have updated the table in Files and Directories for Apps and Add-ons topic. It now contains an entry that explains, for legacy reasons, that when you use Splunk Web to add icon files, the files are placed in $APP_HOME/appserver/static/. You need to move these newly-added icon files to $APP_HOME/static/.

Vgenovese
July 2, 2014

The location of logos and icons (as shown in the table on this page) has changed for apps. The new location is $APP_HOME/static<br /><br />See: http://docs.splunk.com/Documentation/Splunk/6.1.1/AdvancedDev/AddConfigurations<br /><br />Also, it would be helpful to see some explanation of why there remain splunk appLogos (appLogo_allblack.png, appLogo_allwhite.png, appLogo_black.png, appLogo_white.png) in the appserver/static directory, yet now custom apps upload to that directory and are required to move them to $APP_HOME/static

Sscullion splunk
June 27, 2014

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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