Packaging Toolkit CLI

Developers use the Packaging Toolkit Command Line Interface (CLI) to package an app for distribution, regardless of physical placement. It is documented in the following sections.

Note: For more information about the Packaging Toolkit version 0.9.0, you can access the manual pages. To display the command overview page, type the following line:

man slim

To display the manual pages for specific commands, type the following line:

man slim-{config,describe,generate-manifest,package,partition,validate,update-installation} ...

slim

Executes a Splunk packaging toolkit command.

Syntax

slim [-v] [-h] [--debug] [--quiet] {config,describe,generate-manifest,package,partition,validate,update-installation} ...

Options

Option Description
-v, --version Print version number and exit.
-h, --help Print help message and exit.
--debug, --debug <command> Print debugging information.
--quiet Suppresses info and warnings, but not errors.

Commands

Command Description
generate‑manifest Generate a new or updated manifest for a Splunk app.
package Package the source of a Splunk app for distribution
describe Describe a Splunk app and its dependencies.
validate Verify the contents of the manifest of a Splunk app.
partition Create a set of deployment packages from a Splunk app source package.
config Get and set user or system options.
update-installation Perform a sequence of update actions on the app installation graph for a Splunk system.

slim generate‑manifest

Generates an app manifest for a Splunk app based on its configuration settings. By default the manifest will be written to standard out. This can be overwritten with the output option. Note that the manifest must be located at <app-root>/app.manifest for the package command to work.

The manifest includes these sections:

Section Derivation
schemaVersion Version reference for app manifest format.
info Partially derived from default/app.conf.
dependencies Manually added by developer, lists the app dependencies and version requirements.
inputGroups Manually added by the developer, lists the possible input groups with app-dependencies, and inputs that should be included.
tasks Manually added by the developer, lists the inputs that belong on the search head rather than forwarders (such as scheduled tasks rather than modular inputs).
incompatibleApps Manually added by the developer, lists the app IDs that cannot be installed on the system alongside this app.

Syntax

slim [--debug] generate‑manifest [-h] [--quiet] [--output=<filename>] [--update] <app-source>

Options

Option Description
-h, --help Print help message and exit.
<app-source> Location of app source directory.
--debug Print debugging information. Non-destructively updates the manifest, if it already exists. Hand-edits to inputGroups and those elements of the info section that aren't currently represented in app.conf are preserved.
--quiet Suppresses info and warnings, but not errors.
-o <filename>, --output=<filename> Save the app manifest to <filename>. This is useful when you wish to compare the original manifest with the newly-generated manifest before replacing the original.
--update Amend the current app manifest based on configuration settings.

Example

The following example demonstrates using the generate command to generate a manifest for an app called "fictional:"

$ slim --debug generate-manifest --output app.manifest fictional
generate-manifest: Parsing app configuration at 'fictional'...
generate-manifest: Generating app manifest to 'app.manifest'...
generate-manifest: Done! Please update [dependencies] and [inputGroups] sections as needed.

slim package

Packages the source of a Splunk app for distribution. Assumes the app.manifest file is located at the root of the app source directory. The manifest file must exist for the package command to run. The source package filename is derived from the app id.

<info.id.group>-<info.id.name>-<info.id.version>.tar.gz

The file is placed on the output directory, which defaults to the current directory.

Since you're likely to link your app directories to $SPLUNK_HOME/etc/apps to debug locally, the following standard set of ignore files has been generated, and you have the option to specify your own list in a .slimignore file. The standard ignore list includes the following files:

  • .DS_STORE
  • Thumbs.db
  • *.py[co]
  • default/indexes.conf
  • local/
  • metadata/local.meta

Syntax

slim [--debug] package [-h] [-r <repository>] [-u=<level>] [-o <output-dir>] <app-source>

Options

Option Description
-h, --help Print help message and exit.
<app-source> Location of app source directory.
--debug Print debugging information.
-u=<level>, --unreferenced-input-groups=<level> Report unreferenced input groups at a specific logging level (note, warn, or error). (Default: note).
-o <directory-name>, --output-dir=<directory-name> Save source package to <directory-name> (Default: current working directory).
-r <directory-name>, --repository=<directory-name> Look for dependent source packages in <directory-name> (Default: ~/.slim/repository).

Example

The following example demonstrates using the package command to package an app called "fictional:"

$ slim --debug package --unreferenced-input-groups=note --repository ~/.slim/repository fictional
package: Packaging app "fictional" to "~/slim"...
package: [NOTE] fictional: unreferenced input groups: dependency com.splunk.addon:microsoft_windows:4.7.5:
    Active Directory Domain Services
    DHCP Server
    Windows Event Log
    Windows Host Monitor
    Windows Network Monitor
    Windows Performance Monitor
    Windows Print Monitor
    Windows Registry
    Windows Update Monitor
package: Source package exported to "~/slim/com.splunk.addons-fictional-1.0.0.tar.gz"

slim describe

Describes various sections of the app manifest (info, dependencies, forwarder groups), or the complete graph of dependencies.

Syntax

slim [--debug] describe [-h] [--repository=<directory-name>] [-o <filename> <app-source>

Options

Option Description
-h, --help Print help message and exit.
<app-source> Location of app source directory or package.
--debug Print debugging information.
-r <directory-name>, --repository=<directory-name> Look for dependent source packages in <directory-name> (Default: ~/.slim/repository).
-o <file-name>, --output=<file-name> Destination of the describe output (default: stdout).

Example

The following example demonstrates using the describe command to describe an app called "fictional:"

$ slim --debug describe --repository ~/.slim/repository fictional
[info]
|-- SLIM fictional test app: A SLIM app for testing Splunk extension packaging, partitioning, and operations.
|  |-- by David Noble (dnoble@splunk.com) at Splunk, Inc.
|  |-- packaged as com.splunk.addons-fictional@1.0.0
[dependencies]
|-- Splunk Add-on for Microsoft Windows packaged as com.splunk.addon-microsoft_windows@4.7.5
|-- Splunk Add-on for *nix Operating Systems packaged as com.splunk.addon-star_nix@5.2.1
[input-groups]
|-- Microsoft Windows monitoring defines inputs [input_1, input_2, input_3] and requires no dependencies
|-- *nix monitoring defines inputs [input_4, input_5, input_6] and requires [Splunk Add-on for *nix Operating Systems]
[dependency-graph]
|-- com.splunk.addons:fictional@1.0.0
|   |-- com.splunk.addon:microsoft_windows@4.7.5 (accepting 4.7.5)
|      |-- com.splunk.addon:utilities@1.0.0 (accepting ~1.0.0)
|   |-- com.splunk.addon:star_nix@5.2.1 (accepting 5.2.1)

slim validate

Validates the app manifest and the app dependencies. Note that validating the app dependencies will require the manifest to be validated first.

Syntax

slim [--debug] validate [-h] [--repository=<directory-name>] [-u <level>] <app-source>

Options

Option Description
-h, --help Print help message and exit.
<app-source> Location of app source directory or package.
--debug Print debugging information.
-u=<level>, --unreferenced-input-groups=<level> Report unreferenced input groups at a specific logging level (note, warn, or error). (Default: note).
-r <directory-name>, --repository=<directory-name> Look for dependent source packages in <directory-name> (Default: ~/.slim/repository)

Example

The following example demonstrates using the validate command to validate an app called "fictional:"

$ slim --debug validate --repository ~/.slim/repository com.splunk.addons-fictional-1.0.0.tar.gz
validate: Validating app at "com.splunk.addons-fictional-1.0.0.tar.gz"...
validate: [ERROR] fictional: unreferenced forwarder groups: dependency com.splunk.addon:microsoft_windows:4.7.5:
    Active Directory Domain Services
    DHCP Server
    Windows Event Log
    Windows Host Monitor
    Windows Network Monitor
    Windows Performance Monitor
    Windows Print Monitor
    Windows Registry
    Windows Update Monitor

slim partition

Partitions an app source package into a set of targeted deployment packages based on user-defined deployment configurations. The user-defined deployment configurations can contain three different types of Splunk workloads: indexer (named as "_indexers"), search head (named as "_search_heads") and forwarder (named as "_forwarders") workloads. User can specify any combinations of these three workloads in the configurations.

Syntax

slim [--debug] partition [-h] [-r <repository>] [-i <filename>] [-o <output-dir>] [-d <specification> [<specification> ...]] [-f <forwarder-workloads>] [-c] [-p] <app-source>

Options

Option Description
-h, --help Print help message and exit.
<app-source> Location of app source package.
--debug Print debugging information.
-r <repository>, --repository <repository> Location of dependent source packages (default: ${SLIM_REPOSITORY:=~/.slim/repository}
-i <filename>, --installation=<filename> Location of the incoming installation graph (default: empty).
-o <directory-name>, --output-dir=<directory-name> Save deployment packages to <directory-name> (Default: current working directory).
-d <specification> [<specification> ...], --deployment-packages=<specification> [<specification> ...] Specify a set of logical deployment packages by name, workload, and input groups.
-c, --combine-search-head-indexer-workloads Combines the search head and indexer workloads into a single package. By default separate packages are created for each of these workloads.
--f <forwarder-workloads>, --forwarder-workloads <forwarder-workloads> Maps input groups to a set of server classes (default: ["_search_heads", "_indexers", "_forwarders"]).
-p, --partition-only Verify installation graph to ensure it is unchanged after partitioning. This is useful when you are partitiong an app for re-deployment.

Examples

A deployment package specification is represented by a JSON object:

    {
      "name": "<package-name>",
      "workload": [("searchHead" | "indexer" | "forwarder")(,("searchHead" | "indexer" | "forwarder") ...)](,
      "inputGroups": ["<group-name>"(, "<group-name>" ...)])
    }

    A forwarder workload is represented by a JSON array of objects:

    [
      "<server-class-name>": ["<input-group-name>"(, "<input-group-name>" ...)],
      "<server-class-name>": ["<input-group-name>"(, "<input-group-name>" ...)] ...
    ]

The following example CLI output demonstrates the usage of the partition command along with the --forwarder-workloads and --combine-search-head-and-indexer flags on an app called "fictional."

    $ slim partition --forwarder-workloads '{"Microsoft Windows monitoring":["server-class-1"], "*nix monitoring":["server-class-1", "server-class-2"]}' com.splunk.addons-fictional-1.0.0.tar.gz
    partition: [NOTE] fictional manifest lists these undefined inputs in forwarder group "Microsoft Windows monitoring": "input_1", "input_2", "input_3"
    partition: [NOTE] fictional manifest lists these undefined inputs in forwarder group "*nix monitoring": "input_4", "input_5", "input_6"
    partition: [NOTE] Deployment packages created:
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-server-class-1.tar.gz
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-server-class-2.tar.gz
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-splunk-search-head.tar.gz
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-splunk-indexer.tar.gz
 
    $ slim partition --combine-search-head-and-indexer --forwarder-workloads '{"Microsoft Windows monitoring":["server-class-1"], "*nix monitoring":["server-class-1", "server-class-2"]}' com.splunk.addons-fictional-1.0.0.tar.gz
    partition: [NOTE] fictional manifest lists these undefined inputs in forwarder group "Microsoft Windows monitoring": "input_1", "input_2", "input_3"
    partition: [NOTE] fictional manifest lists these undefined inputs in forwarder group "*nix monitoring": "input_4", "input_5", "input_6"
    partition: Deployment packages created:
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-server-class-1.tar.gz
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-server-class-2.tar.gz
        /Users/splunkuser/SplunkSource/python-site/splunk/slim/com.splunk.addons-fictional-1.0.0-splunk-server.tar.gz 

slim config

Gets and sets user or system options.

Syntax

slim [--debug] config [-h] [-l [system|user]] [-g [<name> [<name> ...]]] [-s <name> <value> <name> <value>] [-u [<name> [<name> ...]]] 

Options

Option Description
-h, --help Print help message and exit.
--debug Print debugging information.
-l [system|user], --location [system|user] When writing settings: write to the named configuration file (default: user). When reading settings: read only from the named configuration file rather than from system and user.
--g [<name> [<name> ...]], --get [<name> [<name> ...]] Gets the values for all settings (using '*'), all settings in a section (using '<section>[.*]'), or the named settings, where the name of each setting is its section and option name separated by a dot.
--s <name> <value> <name> <value>, --set <name> <value> <name> <value> Sets the value for the named setting, where the name of the setting is its section and option name separated by a dot ('<section>.<option>').
--u [<name> [<name> ...]], --unset [<name> [<name> ...]] Removes the named settings, where the name of each setting is its section and option name separated by a dot ('<section>.<option>').

slim update-installation

Performs a sequence of update actions on the app installation graph for a Splunk system.

Update actions are defined as a sequence of JSON objects:

    --actions '{
      "action": "add",
      "args": {
        "app_package": "<path>",
        "combine_search_head_indexer_workloads": <boolean>,
          "workloads": {
            "<input-group-name>": ["<server-class-name>"(, "<server-class-name>" ...)],
            "<input-group-name>": ["<server-class-name>"(, "<server-class-name>" ...)] ...
          }
        }
      }
    }' '{
      "action": "remove",
        "args": {
          "app_id": "<app_id>"
        }
      }
    }' '{
      "action": "set",
      "args": {
        "app_package": "<path>",
          "combine_search_head_indexer_workloads": <boolean>,
          "workloads": {
            "<input-group-name>": ["<server-class-name>"(, "<server-class-name>" ...)],
            "<input-group-name>": ["<server-class-name>"(, "<server-class-name>" ...)] ...
          }
        }
      }
    }' '{
      "action": "update"
      "args": {
        "app_package": "<path>"
      }
    }'

Syntax

slim [--debug] update-installation [-h] [-r <repository>] [-i <filename>] [-o <output-dir>] [-a <action> [<action> ...]] [--disable-automatic-resolution]

Options

Option Description
-h, --help Print help message and exit.
--debug Print debugging information.
-r <directory-name>, --repository=<directory-name> Look for dependent source packages in <directory-name> (Default: ~/.slim/repository).
--i <filename>, --installation <filename> Location of the incoming installation graph (Default: empty)
--o <output-dir>, --output-dir <output-dir> Destination of the installation graph and deployment packages (default: current directory)
--a <action> [<action> ...], --actions <action> [<action> ...] List of actions to be applied to the given installation graph: add, remove, set, or update.
--disable-automatic-resolution Do not automatically resolve dependency conflicts by updating installed versions.