Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Security and Apps

Splunk Apps, Add-ons and Splunkbase: Structure and Packaging

Learn how Splunk apps and technology add-ons differ, the app directory layout, app.conf, default versus local, installing from Splunkbase, building your own app and deploying it.

An app is a directory of configuration, searches, dashboards, lookups and scripts that adds a feature set to Splunk. Everything you have built so far (reports, alerts, dashboards, data models) can be packaged as an app and installed on another instance. Apps are how Splunk Enterprise Security, the Splunk App for AWS and thousands of community tools are delivered, and they are how serious administrators keep configuration organized and reviewable.

Apps versus add-ons

Kind Purpose Has a UI?
App A user-facing solution: dashboards, navigation, reports Yes (appears in the app menu)
Technology Add-on (TA) Collect and parse data for one product: inputs, props.conf, transforms.conf, field extractions, CIM tags No (visible = false)
Supporting Add-on (SA) Shared knowledge for several apps, such as lookups or CIM definitions No
Domain Add-on (DA) Extractions and dashboards for a domain such as email Sometimes

For example, the Splunk Add-on for Microsoft Windows parses Windows events and maps them to the CIM; the app that uses them is separate. Good practice is to keep data collection and parsing in an add-on and dashboards and searches in an app, because the add-on must run on forwarders and indexers, while the app belongs on search heads.

Directory layout

An app lives in $SPLUNK_HOME/etc/apps/<app_name>/:

Text
myapp/
  default/            shipped settings (do not edit after install)
    app.conf
    props.conf
    transforms.conf
    savedsearches.conf
    macros.conf
    data/ui/nav/default.xml
    data/ui/views/overview.xml
  local/              settings created on the instance (win over default)
  lookups/            CSV lookup files
  bin/                scripts and modular inputs
  static/             icons and images (appIcon.png)
  appserver/static/   custom JS and CSS for dashboards
  metadata/
    default.meta      default sharing and permissions
    local.meta        sharing changed in the UI
  README/             .spec files for custom configuration

The most important rule: local overrides default. Upgrades replace default and keep local, so customers' changes survive. As an app developer you put everything in default; as an administrator you put every change in local (the UI already does this).

app.conf identifies the app:

INI
[install]
state = enabled
build = 12

[ui]
is_visible = true
label = Web Operations

[launcher]
author = Platform Team
version = 1.4.0
description = Dashboards and alerts for the web tier

[package]
id = web_ops

metadata/default.meta controls sharing and who may read or write the app's objects:

INI
[]
access = read : [ * ], write : [ admin, power ]
export = system

export = system makes the app's objects available globally; without it, they are used in the app only.

Try it: validate an app layout (stand-in)

A checker like the one below (it is a stand-in for Splunk's AppInspect) catches common packaging mistakes: missing app.conf, settings in local, and an invalid id.

Python Stand-in: a tiny app packaging checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Installing apps

  • From Splunkbase (splunkbase.splunk.com): in Splunk Web choose Apps > Find More Apps, search, click Install, and sign in with a Splunk.com account. This needs internet access from the instance.
  • From a file: download the .spl or .tgz package, then Apps > Manage Apps > Install app from file. Choose Upgrade app when it already exists.
  • From the command line: splunk install app /tmp/myapp.tgz -auth admin:password, or unpack the package into etc/apps and restart.
  • At scale: the deployment server pushes apps to forwarders (Forwarder Management), the cluster manager pushes to indexers (etc/manager-apps, then splunk apply cluster-bundle), and the deployer pushes to search head cluster members (etc/shcluster/apps). Never edit files by hand on cluster members; they are overwritten.

After installing, many add-ons need setup: credentials for an API, an input to enable, and a CIM index constraint. Read the app's Details and Installation pages on Splunkbase. Always test an app on a non-production instance first, because an add-on with wide props.conf settings can change how existing data is parsed.

Building your own app

  1. Apps > Manage Apps > Create app (or Settings > Apps), enter a name, folder name, version and a template (barebones or sample_app).
  2. Build your knowledge objects in the new app (set the app as the current app when you save reports and dashboards), so everything lands in etc/apps/<app>/local.
  3. Move finished settings from local to default, add README/ and metadata/default.meta, and set permissions.
  4. Package it: tar -czf myapp.spl myapp (without local/ and .pyc files), and keep the source in Git.
  5. Validate with AppInspect (splunk-appinspect inspect myapp.spl), which Splunk requires for Splunkbase and Splunk Cloud apps, and fix failures.
  6. Deploy through the deployment server, deployer or cluster manager, not by hand.

The Splunk Add-on Builder is a free app with a wizard for creating add-ons that call REST APIs or scripts and map fields to the CIM. It handles checkpointing and validation. For a modular input with the Splunk SDKs, see REST API, HEC and SDKs.

Treat apps as code: put them in Git, review changes, run AppInspect in CI, and bump version in app.conf on every release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which directory holds settings that override the app's shipped defaults?

    local takes precedence over default, and upgrades replace default while keeping local.
  2. 2. What is a technology add-on (TA) mainly for?

    TAs hold inputs, props, transforms and extractions; they normally have no user interface.
  3. 3. How are apps distributed to forwarders at scale?

    The deployment server manages forwarders. The deployer is for search head clusters and the cluster manager for indexers.
  4. 4. What does AppInspect do?

    AppInspect validates apps and is required for Splunkbase and Splunk Cloud submissions.

Summary

  • Apps add user-facing features; add-ons (TAs/SAs) collect, parse and normalize data.
  • Apps live in etc/apps/<name>; local overrides default; metadata controls sharing.
  • Install from Splunkbase or a package; at scale use the deployment server, deployer or cluster manager.
  • Build apps in a dedicated app context, keep them in Git and validate with AppInspect.

Next: REST API, HEC and SDKs