Create Your First App

Now that you have installed Splunk, create your first app:

  1. Start Splunk Enterprise, if it isn't already running.
  2. Open Splunk Web from a web browser by navigating to http://localhost:8000, which is the default URL.
  3. Log in to Splunk Enterprise. By default, your credentials are:
    • Username: admin
    • Password: changeme
  4. On the Splunk Web home page, click the Gears icon next to Apps.
  5. Click Create app.
  6. On the Add new page, fill out the properties of the new app, including the app's name, the name of the folder where it will be stored on disk, the version number your app will start at, the author name, and the description of your app. For Visible select Yes. Each settings creates a corresponding stanza in the app configuration file (app.conf) defining your app. We'll talk more about that more below.
  7. Under Template, select barebones. The barebones template creates:
    • An app with a basic directory structure.
    • Required configuration (.conf) files.
    • Some additional readme files.
  8. Click Save to create your app.
  9. Your app is now listed on the Apps page along with any other apps that are installed.

    Under the Actions for your app, you can click Launch app to navigate to the default home dashboard of your app.

    Click the Splunk logo in the upper left corner of the window to return to the default Splunk Web dashboard, and notice that your app appears in the list of apps on the left of the Splunk Web home page.

  10. Click your app to run it.

Recap

You've just created your first app using Splunk Web's interface. Congratulations! Let's take a step back and look at the files and folders Splunk Web just created for you.

Open a file browser and navigate to the apps folder under $SPLUNK_HOME. Depending on your operating system, the default paths are:

  • Mac: /Applications/Splunk/etc/apps
  • Windows: C:\Program Files\Splunk\etc\apps
  • Linux: /opt/Splunk

Splunk stores all installed apps under $SPLUNK_HOME/etc/apps and includes a folder for the app you just created. Splunk Enterprise should set the SPLUNK_HOME variable by default, but if you want to change it see Set $SPLUNK_HOME.

App folders and files

Here's a sample folder structure for your app:

Open the folder containing your app. The /bin folder is where you should store supporting code for your app. For example, Python code used for modular inputs should go in here.

    Notes

    • When you use the barebones template to create an app, a README file is generated that contains a quick statement about what belongs in this directory. You should remove this file before publishing your app.
    • If your app won't have any scripts or code, remove /bin directory because unnecessary files can make it difficult to determine an app's purpose.

Default and local configurations

The /default folder is where default and base configuration files (.conf), navigation components, and views (visualization components) are stored.

The /local folder is where user-customized configurations, navigation components, and views are stored.

Changes made to files in the /local folder are private to each user and is where Splunk Web saves most changes you make to an app through the web interface. The /local folder is used so that the default values are not mutated. You can always revert to the defaults of an app by deleting the local configurations for your user. The contents of the /local folder have higher precedence than the contents of the /default folder.

If the same stanza properties are defined in the same configuration files in both /default and /local, the values in /local are the ones Splunk Enterprise uses. For more about configuration precedence, see Configuration file precedence in the Admin Manual.

For instance, in the app you just created, the "version" field in /default/app.conf is set to 1.0. This value is overridden by the "version" field in /local/app.conf with 0.1, and this is the value displayed by Splunk Web as the version number for your app.

    Notes

    • Migrate configurations from the /local to the /default directory before you package and publish your app so that users don't inadvertently overwrite important configurations.
    • When users update their app, the /local directory won't be overwritten so that customizations users make to their app are preserved through updates.

The app configuration file

The app.conf file contains configuration settings about your app and how Splunk Enterprise should display it. In the image below, the default app.conf is on the left and the local app.conf is on the right:

If you compare these fields to the page you filled in earlier when creating your app, you can see where the values for "is_visible", "label", "author", "description", and "version" are stored. The "version" property was set in the /local directory--because settings in this directory have higher precedence than settings in /default, the version number is displayed as 0.1 in Splunk Web.

All .conf files contain a series of stanzas, indicated by square brackets, and attributes. Each attribute applies only to the stanza in which it is defined. You could have multiple description attributes in the same .conf file as long as they were contained in different stanzas. For more about .conf files in general, see Configuration file structure in the Admin Manual. For more about the app.conf file, see app.conf in the Admin Manual.

If you design your app to rely on other apps and add-ons and would like to declare dependencies, which will be automatically resolved, you'll need to provide an app.manifest file. For more information, see The app manifest in the Packaging Toolkit documentation.

The navigation file

The /default/data/ui/nav and /local/data/ui/nav folders contain settings for the navigation bar at the top of your app in the default.xml file.

The "default='true'" attribute determines which dashboard to display when your app first loads. The "name" attribute refers to the "label" value defined in the dashboard's .xml file for that navigation entry.

The navigation links in your first app are default links and are part of the Search app that is included with Splunk Web, which is why you do not see these dashboards stored in /default/data/ui/views.

The Search app's dashboards are stored in $SPLUNK_HOME/etc/apps/search/default/ui/views if you're curious.

Metadata

The /default/data/ui/views and /local/data/ui/views folders contain the .xml files that define dashboards in your app. Currently, there's just a README file stored in the /default version of this folder because we haven't defined any dashboards yet. As with the other README, this file just tells us what goes in this directory and can be removed. When you create a dashboard in Splunk Web, it appears in /local/data/ui/views. The metadata contains two files to store metadata and permissions for Splunk objects (searches, views, and so on). Unlike other configuration files, the default and local versions of the metadata are stored in the same /metadata folder.

The default.meta file contains stanzas describing which objects can be viewed by which users in the system. The empty [] stanza is used to allow access to the app. In the barebones app you created, default.meta allows all users of the Splunk Enterprise environment to access the app, but only admins and power users can change it.

The export statements in each stanza indicate that these Splunk objects should be available to all apps in the Splunk environment. You can export to system (all apps), none (no apps), or to specific apps. This setting makes the specified Splunk objects in the current app accessible to the other apps you specify.

The local.meta file has higher precedence than default.meta and as a result overwrites default.meta if you define the same stanza or attribute in both files. In your app, local.meta defines a version (corresponding to the version of Splunk on which you created the app) and modtime (corresponding to the last time the object referred to in that stanza was modified). For more information about permissions and scopes, see Configuration file structure in the Admin Manual.

Now that you know what happens when Splunk creates an app, you also know how to manually create an app without using Splunk Web. Create the same folder structure and .conf files inside of $SPLUNK_HOME/etc/apps and restart Splunk Enterprise.

See also

Your first AppInspect

Next step

Add data