Add licensing requirements to a Splunk app

You can add licensing requirements to apps that you develop for Splunk Enterprise and Splunk Cloud. You can create a license requirement for an entire app or for specific functions within the app.

You must generate app licenses from a template. Each template is assigned to an individual product and one or more versions of that product. The license templates contain customizable parameters so that you can provide a user experience specific to each product and version or versions.

Splunk uses a cloud-based licensing service for app license verification. Apps cannot be enabled without access to the app licensing service. A connection to the app licensing service needs to be maintained for apps to continue to run.

This topic contains the following sections:

Splunk Application Licensing Service Overview

To use a licensed app, Splunk Enterprise or Splunk Cloud must have consistent access to the Splunk Application Licensing Service. This access is required for installed licensed applications to function and remain enabled.

The Splunk Application Licensing Service receives app licensing requests from Splunk Enterprise and Splunk Cloud and responds over SSL to the requesting instance. All communications are provided over TCP port 443.

App licensing also provides API services that you can use to create products, access license templates, and generate licenses.

Splunk License Validation

To use license validation In Splunk Enterprise, you first need to enable it. Application developers can set license validation operations that use REST APIs internal to Splunk to happen automatically, and they can also specifically initiate license validation operations.

Configuring App Licensing for Splunk Enterprise

Splunk App Licensing is disabled by default. To enable the service, complete the following steps:

  1. Find the app license stanza in the server.conf file.
  2. Change the appLicenseHostPort value to match the following example. This change points the app license functionality to version 0.5 of the app licensing API.
    appLicenseServerPath = /splunklicensevalidation/0.5/api/licenses/validations
    
  3. Change the disabled value from true to false. This change enables app licensing.
    disabled = false
  4. Verify that the app license stanza now matches the following version:
    [applicense]
    appLicenseHostPort =  apps-api.splunk.com:443
    appLicenseServerPath = /splunklicensevalidation/0.5/api/licenses/validations
    caCertFile = $SPLUNK_HOME/etc/auth/appsLicenseCA.pem
    cipherSuite = TLSv1.2+HIGH:@STRENGTH
    sslVersions = tls1.2
    sslVerifyServerCert = true
    sslCommonNameToCheck = apps-api.splunk.com
    sslAltNameToCheck = apps-api.splunk.com
    disabled = false
    
  5. Schedule a restart of the Splunk instances in which you made changes.

Troubleshooting your configuration

If you modify other portions of the app license stanza, your apps might not function correctly, or they might become disabled. If your app license stanza is configured incorrectly, then you can find an error message in the splunkd.log file. You can try to re-configure the stanza, or you can revert it to the following unedited version:

[applicense]
appLicenseHostPort =  apps-api.splunk.com:443
appLicenseServerPath = /splunklicensevalidation/api/licenses/validations
caCertFile = $SPLUNK_HOME/etc/auth/appsLicenseCA.pem
cipherSuite = TLSv1.2+HIGH:@STRENGTH
sslVersions = tls1.2
sslVerifyServerCert = true
sslCommonNameToCheck = apps-api.splunk.com
sslAltNameToCheck = apps-api.splunk.com
disabled = true

Automatic license validation

Automatic license validation in Splunk Enterprise and Splunk Cloud happens in the following situations:

  • Anytime 24 hours has passed since the last validation.
  • Whenever Splunk Enterprise restarts.
  • When an admin initiates a REST API request to re-check the status of a license.
  • When an admin enables a licensed app that was disabled because the license was no longer valid. See Disabled Apps for more information.

Developer-initiated license validation

App developers can initiate license validation checks in Splunk Enterprise and Splunk Cloud in the following situations, among others:

  • When a user wants to access additional functionality within an app.
  • Anytime an app developer needs to check the status and capabilities of a license on demand.

To check the status of a license, initiate a CURL request to the licensing service with the application ID:

curl  -k https://<Licensing service URI>/services/applicense/applicenses/<application ID>

On successful license validation, license service will return a JSON payload similar to the following example:

{
"links": {
"_reload": "/services/applicense/applicenses/_reload", "_acl": "/services/applicense/applicenses/_acl"
},
"origin": "https://<Licensing service URI>/services/applicense/applicenses",
"updated": "2017-01-18T13:44:25-08:00",
"generator": {
"build": "45ce86991a0b7e52903683675b091502a3c3efc66", "version": "201612213"
},
"entry": [{
"name": "<Licensing service URI>",
"id": "https://<Licensing service URI>/services/applicense/applicenses/<application ID>", "updated": "2017-01-18T13:44:25-08:00",
"links": {
"alternate": "/services/applicense/applicenses/<application ID>",
"list": "/services/applicense/applicenses/<application ID>", "_reload": "/services/applicense/applicenses/<application ID>/_reload"
},
"author": "system",
"acl": {
"app": "",
"can_list": false,
"can_write": false,
"modifiable": false,
2
"owner": "system",
"perms": {
"read": ["*"],
"write": ["admin", "splunk-system-role"]
},
"removable": false,
"sharing": "system"
},
"content": {
"appId": " <Licensing service URI>",
"appLicenseId": "3581DECE-D4C5-4950-848B-6AB0E6FAC99E", "eai:acl": null,
"lastCheckTime": "Wed Jan 18 13:42:15 2017",
"licenseStatus": "outOfCompliance"
}
}],
"paging": {
"total": 1,
"perPage": 30,
"offset": 0
},
"messages": []
}

Enabling Disabled Apps

Licensed apps are disabled when their specific app license passes the expiration date and, if it exists, the grace period. Admins are warned before their apps are disabled due to expiration. License checks occur automatically when an admin re-enables a licensed app, but only if the app was disabled because the license was no longer valid.

Admins can complete the following steps to view their app license status and re-enable a disabled app:

  1. Select Settings > Licensing.
  2. Scan for the apps and associated license expiration date.
  3. If an app is past its license expiration date, re-purchase or renew app license.
  4. Re-enable the app by selecting Enable for that app under Apps > Manage Apps.

App Licensing Logs

You can access the logs for app licensing in the audit.log file and the splunkd.log file. The Audit log entries exist for each licensed app that is installed.

At minimum, an audit marker exists in the process-return-license code path that indicates if the license is in compliable, out of compliance, or in the grace period if one exists. The following scenarios are also associated with audit markers:

  • Licensed apps do not have a URL to contact the licensing service.
  • A transaction to the licensing service fails.

User Messages

App licensing uses the Splunk Enterprise and Splunk Cloud messaging framework. In the following scenarios, Splunk software generates a user message:

  • An app license will expire soon
  • An app license has expired
  • The app licensing service is unavailable

Viewing user messages

Admins can complete the following steps to view the user messages:

  1. Select Messages in a Splunk installation.
  2. Select a message to read and acknowledge it.

After an admin has acknowledged a message, it does not reappear unless the status that the message is reporting changes. For example, if the message indicates a countdown until the app license expires and the app is disabled, the message appears again on the next day to display the modified countdown.

Core error messages use cases

The following core error messages are also available in the Splunk audit logs.

Use Case 1: Expired license

The following message displays in the UI and is written to the splunkd.log file after the licenses for an app expire and the grace period ends.

APP_LICENSE_EXPIRED__S
message = The following Application licenses have expired and have been disabled: %s.
action = Repurchase application license from Splunkbase.
severity = ERROR

Use Case 2: License in grace period

The following message displays after the licenses for an app expires, but before the grace period ends. At this time, the app remains enabled, and app developers can choose to take additional actions within the app.

APP_LICENSE_GRACE_PERIOD__S
message = The following Application licenses have expired but are running in a grace period: %s.
action = Repurchase application license from Splunkbase. 
severity = WARN

Use Case 3: No license detected

The following message displays if the app is installed, but either no license is installed or the license is deleted from the Splunk installation.

APP_LICENSE_NOT_FOUND__S
message = The following Application licenses cannot be found and have been disabled: %s
action = Contact Splunk support if you believe there has been an error.
severity = ERROR

Use Case 4: Connection to the license server disrupted due to .conf file change

The following message displays if a license is installed for an app, but the connection to the license server is broken due to modification of .conf files. At this time, the app remains enabled, and app developers can choose to take additional actions within the app.

APP_LICENSE_SERVER_UNDEFINED__S
message = The appLicenseHostPort setting in server.conf is undefined. Unless the connection is restored, all licensed applications will be disabled in %s day(s).
severity = ERROR

Use Case 5: Failure to connect to the license server

The following message displays if the connection to the cloud licensing server has been severed locally or through the Internet. At this time, all apps remain enabled, and app developers can choose to take additional actions within the apps.

APP_LICENSE_SERVER_UNREACHABLE__S
message = The application license server cannot be reached. Unless the connection is restored, all licensed applications will be disabled in %s day(s).
severity = ERROR

Use Case 6: Extended failure to connect to the license server

The following message displays if the connection to the cloud licensing server has been severed locally or through the Internet for more than 30 days. All licensed apps are disabled.

APP_LICENSE_ALL_DISABLED
message = The application license server was unreachable for 30 days or more. All licensed applications have been disabled.
severity = ERROR

Use Case 7: License Master not configured for Splunk App Licensing

The following message displays in the splunkd.log file if you have not configured the connection to License Master to support Splunk App Licensing. The disabled flag in the app license stanza in the server.conf file is set to true.

APP_LICENSE_ALL_DISABLED
message = App license disabled by conf setting.
severity = INFO