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 slim version number and exit.
-h, --help
<command> -h, --help
Print slim (or command) help message and exit.
--debug <command> Print command debugging information.
--quiet <command> Suppresses command 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
validate Verify the contents of the manifest of a Splunk app.
describe Describe a Splunk app and its dependencies.
partition Create a set of deployment packages from a Splunk app source package.
update-installation Perform an update action on the app installation graph for a Splunk system.
config Get and set user or system options.

slim generate‑manifest

Generates or updates 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: The manifest must be located at <app-source>/app.manifest for other commands such as validate, package, and partition to work as expected.

The manifest includes these sections by default:

Section Derivation
schemaVersion Version reference for app manifest format.
info Describes app meta-data, partially derived from default/app.conf.
dependencies Lists the app dependencies and version requirements.
inputGroups Lists the logical input groups and what inputs should be included.
tasks Lists the inputs that belong on the search head rather than forwarders (such as scheduled tasks).
incompatibleApps Lists the apps that cannot be installed on the system alongside this app.
supportedDeployments Lists the deployment types this app is supported on.

For complete details on the manifest sections, refer to the app.manifest reference.

Note: All manifest sections are generated by default, but some must contain valid values before packaging. These sections were added in version 1.0.0; refer to the required manifest sections documentation for details.

Syntax

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

Options

Option Description
--update Amend the current app manifest after configuration setting changes (such as app.conf updates).
-o <filename>
--output=<filename>
Save the app manifest to <filename>. (Default: standard out)
<app-source> Location of app source directory.

Example

Here is an example of using the generate-manifest command on the splunk_app_for_nix, saving the manifest to the root of the app source:

$ slim generate-manifest splunk_app_for_nix --output splunk_app_for_nix/app.manifest
slim generate-manifest: Parsing app configuration at "splunk_app_for_nix"...
slim generate-manifest: [WARNING] Could not find alert_overlay.conf.spec
slim generate-manifest: [WARNING] Could not find unix_setup.conf.spec
slim generate-manifest: Generating app manifest to "splunk_app_for_nix/app.manifest"...
slim generate-manifest: [NOTE] App manifest saved to "splunk_app_for_nix/app.manifest"

slim package

Packages the source of a Splunk app for distribution. Assumes the app.manifest is located at the root of the app source directory. If the manifest does not exist, the package command will generate one.

The source package filename is derived from the app info:

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

The file is placed in the output directory, which defaults to the current directory. This can be overwritten by the --output option.

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 package [-h] [--debug] [--quiet] [-o <output-dir>] [-r <repository>] [-u <level>] <app-source>

Options

Option Description
-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).
<app-source> Location of app source directory.

Example

Here is an example of using the package command on the splunk_app_for_nix, where Splunk_TA_nix has been declared a dependency in the app.manifest:

$ slim package splunk_app_for_nix --repository $SLIM_REPOSITORY
slim package: Packaging app at "splunk_app_for_nix"
slim package: [NOTE] Generating app manifest for splunk-add-on-for-unix-and-linux_524.tgz...
slim package: [WARNING] Could not find eventgen.conf.spec
slim package: [WARNING] Could not find alert_overlay.conf.spec
slim package: [WARNING] Could not find unix_setup.conf.spec
slim package: [WARNING] Skipping validation for dynamic dependency "Splunk_TA_nix"
slim package: [NOTE] Source package exported to "splunk_app_for_nix-5.2.3.tar.gz"

If the dependency Splunk_TA_nix was declared dynamically, then it is skipped during packaging:

$ slim package splunk_app_for_nix
slim package: Packaging app at "splunk_app_for_nix"
slim package: [WARNING] Could not find alert_overlay.conf.spec
slim package: [WARNING] Could not find unix_setup.conf.spec
slim package: [WARNING] Skipping validation for dynamic dependency "Splunk_TA_nix"
slim package: [NOTE] Source package exported to "splunk_app_for_nix-5.2.3.tar.gz"

slim validate

Validates the app and app manifest (if it exists). This includes validating any statically declared dependencies. If a manifest does not exist, one will be generated.

Syntax

slim validate [-h] [--debug] [--quiet] [-r <directory-name>] [-u <level>] <app-source>

Options

Option Description
-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)
<app-source> Location of app source directory or package.

Example

Here is an example of using the validate command on the splunk_app_for_nix package created above:

$ slim validate splunk_app_for_nix-5.2.3.tar.gz
slim validate: Validating app at "splunk_app_for_nix-5.2.3.tar.gz"...
slim validate: [WARNING] Could not find alert_overlay.conf.spec
slim validate: [WARNING] Could not find unix_setup.conf.spec
slim validate: [WARNING] Skipping validation for dynamic dependency "Splunk_TA_nix"
slim validate: [NOTE] App validation complete

slim describe

Describes the app in a user-friendly way, taking information from the manifest (if it exists). This includes the dependency graph, for statically declared dependencies only. If a manifest does not exist, one will be generated.

Syntax

slim describe [-h] [--debug] [--quiet] [-r <directory-name>] [-o <filename>] <app-source>

Options

Option Description
-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: standard out).
<app-source> Location of app source directory or package.

slim partition

Partitions an app package into a set of targeted deployment packages based on user-defined deployment configurations. The deployment configurations can contain three different types of Splunk workloads: indexers (named as "indexer"), search heads (named as "searchHead") and forwarders (named as "forwarder"). Any combination of these workloads can appear in the deployment configurations.

If the app manifest has statically declared dependencies, those packages will be partitioned in the same way using the same deployment configurations. Each deployment package will have the app package and any dependency deployment packages.

The partition command will either update an installation graph if one is provided, or generate a new one. Any statically declared dependencies also partitioned will be added to the graph.

Note: Partitioning an app with dynamically declared dependencies is not supported, unless those dependencies are already included in the installation graph.

Syntax

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

Options

Option Description
<app-source> Location of app source package.
-r <repository>
--repository <repository>
Location of dependent source packages (default: ~/.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 user-defined server classes.
-p, --partition-only Use an existing installation graph for partitioning. This is useful when you are partitioning an app for re-deployment, and it does not need to be added again.
-t <os-name>
--target-os <os-name>
Specify the target OS to be used when evaluating the following OS-specific dependencies that are defined in the manifest: *, _mac, _windows, _linux_x86, _linux_x86_64. By default, all OS-specific dependencies will be installed (*). This option is ignored when the --partition-only is used, since the installation graph is not updated.

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>" ...)] ...
]

Here is an example of using the partition command on the splunk_app_for_nix package created above in a variety of scenarios. By default, a deployment package will be generated for search heads, indexers, and forwarders:

$ slim partition splunk_app_for_nix-5.2.3.tar.gz 
slim partition: Extracting source from "splunk_app_for_nix-5.2.3.tar.gz"...
slim partition: [NOTE] Generating app manifest for splunk-add-on-for-unix-and-linux_524.tgz...
...
slim partition: Adding splunk_app_for_nix:5.2.3 to installation graph...
slim partition: [NOTE] Saved updated installation graph to "installation-update.json"
slim partition: Partitioning splunk_app_for_nix:5.2.3...
slim partition: [NOTE] Generated deployment packages for splunk_app_for_nix:5.2.3:
  splunk_app_for_nix-5.2.3-_search_heads.tar.gz
  splunk_app_for_nix-5.2.3-_indexers.tar.gz
  splunk_app_for_nix-5.2.3-_forwarders.tar.gz

To combine search head and indexer packages, and still produce a separate forwarder package, use the --combine-search-head-indexer-workloads option:

$ slim partition splunk_app_for_nix-5.2.3.tar.gz --combine-search-head-indexer-workloads
slim partition: Extracting source from "splunk_app_for_nix-5.2.3.tar.gz"...
slim partition: [NOTE] Generating app manifest for splunk-add-on-for-unix-and-linux_524.tgz...
...
slim partition: Adding splunk_app_for_nix:5.2.3 to installation graph...
slim partition: [NOTE] Saved updated installation graph to "installation-update.json"
slim partition: Partitioning splunk_app_for_nix:5.2.3...
slim partition: [NOTE] Generated deployment packages for splunk_app_for_nix:5.2.3:
  splunk_app_for_nix-5.2.3-_search_head_indexers.tar.gz
  splunk_app_for_nix-5.2.3-_forwarders.tar.gz

To produce a deployment package with a custom workload grouping, such as for a heavy forwarder, use the --deployment-packages option:

$ slim partition splunk_app_for_nix-5.2.3.tar.gz --deployment-packages '{"name":"sh_idx","workload":["searchHead","indexer"]}' '{"name":"heavy_fwdr","workload":["indexer", "forwarder"]}' 
slim partition: Extracting source from "splunk_app_for_nix-5.2.3.tar.gz"...
slim partition: [NOTE] Generating app manifest for splunk-add-on-for-unix-and-linux_524.tgz...
...
slim partition: Adding splunk_app_for_nix:5.2.3 to installation graph...
slim partition: [NOTE] Saved updated installation graph to "installation-update.json"
slim partition: Partitioning splunk_app_for_nix:5.2.3...
slim partition: [NOTE] Generated deployment packages for splunk_app_for_nix:5.2.3:
  splunk_app_for_nix-5.2.3-sh_idx.tar.gz
  splunk_app_for_nix-5.2.3-heavy_fwdr.tar.gz

slim update-installation

Performs an update action on installation graph for a Splunk deployment. If you do not provide an input installation graph, the Packaging Toolkit generates a new one.

This command does not perform app package partitioning and does not produce any deployment packages. It only simulates partitioning so it can update the installation graph appropriately.

When making updates to the installation graph, all workloads must be in a continuously valid state. For example, you cannot add an app to the installation graph if the dependency requirements are not satisfied. Likewise, you cannot remove an app from the installation graph if it is required by another app.

Syntax

slim update-installation [-h] [--debug] [--quiet] [-r <repository>] [-i <filename>] [-o <output-dir>] [-a <action>] [--disable-automatic-resolution] [--id <app_id>] [-p <app_source>] [--combine-search-head-indexer-workloads] [-f <specification>] [-d <specification>] [-t <os-name>]

Options

Option Description
-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 updated installation graph and deployment packages (Default: current directory)
-a <action>
--actions <action>
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.
--id <app id> ID of the package in the remove operation.
-p <app-source>
--package <app-source>
Location of app source package.
-c, --combine-search-head-indexer-workloads Combine the workload of search head and indexers.
-f <specification>
--forwarder-workloads <specification>
Map input groups to a set of user-defined server classes.
-d <specification>
--deployment-packages <specification>
Specifies a set of logical deployment packages by name, workload, and input groups.
-t <os-name>
--target-os <os-name>
Specify the target OS to be used when evaluating the following OS-specific dependencies that are defined in the manifest: *, _mac, _windows, _linux_x86, _linux_x86_64. By default, all OS-specific dependencies will be installed (*).

Examples

The add action adds the app to any workload in the installation graph from which it is missing. Any existing workloads, even if they are not specified in the command, remain untouched.

slim update-installation --action add --package <path> --forwarder-workloads '{"<input-group-name>": ["<server-class-name>"(, "<server-class-name>" ...)], "<input-group-name>": ["<server-class-name>"(, "<server-class-name>" ...)] ...}'

The set action ensures only workloads referenced in the command have the app. This means for any other workload, the app will be removed.

slim update-installation --action set --package <path> --forwarder-workloads '{...}'

The remove action removes the app from all workloads, assuming no other apps reference it as a dependency.

slim update-installation --action remove --id <app_id>

The update action updates the app version (or dependencies) for all workloads that have this app installed.

slim update-installation --action update --package <path>

The following example uses the update-installation command on an installation graph after the splunk_app_for_nix is installed. Trying to remove the Splunk_TA_nix dependency from the installation graph fails, because the splunk_app_for_nix has declared it as a dependency:

$ slim update-installation --installation installation.json --action remove --id Splunk_TA_nix
slim update-installation: Updating installation graph at "installation.json"
...
slim update-installation: Performing remove action for "Splunk_TA_nix"
slim update-installation: [ERROR] Splunk_TA_nix cannot be uninstalled because it is still required by these apps:
    splunk_app_for_nix

slim config

Gets and sets user and system options used by all slim commands.

Syntax

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

Options

Option Description
-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.
Note: Writing to the system configuration may require elevated privileges.
-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>').

Examples

Here is an example of using the config command to get the list of currently set and available options:

$ slim config -g "*"
option.repository_path = ~/.slim/repository
option.temp_directory_path = /tmp

To configure the repository path (where dependency packages are located), set the option.repository_path option:

$ slim config -s option.repository_path .
$ slim config -g option.repository_path
option.repository_path = .