ksconf unarchive

Install or overwrite an existing app in a git-friendly way. If the app already exists, steps will be taken to upgrade it safely.

The default folder can be redirected to another path (i.e., default.d/10-upstream or other desirable path if you’re using the ksconf combine tool to manage extra layers).

usage: ksconf unarchive [-h] [--dest DIR] [--app-name NAME]
                        [--default-dir DIR] [--exclude EXCLUDE] [--keep KEEP]
                        [--allow-local]
                        [--git-sanity-check {off,changed,untracked,ignored}]
                        [--git-mode {nochange,stage,commit}] [--no-edit]
                        [--git-commit-args GIT_COMMIT_ARGS]
                        SPL

Positional Arguments

SPL

The path to the archive to install.

Supports tarballs (.tar.gz, .spl), and less-common zip files (.zip)

Named Arguments

--dest

Set the destination path where the archive will be extracted. By default, the current directory is used. Sane values include: etc/apps, etc/deployment-apps, and so on.

Often this will be a git repository working tree where Splunk apps are stored.

--app-name

The app name to use when expanding the archive. By default, the app name is taken from the archive as the top-level path included in the archive (by convention).

Expanding archives that contain multiple (ITSI) or nested apps (NIX, ES) is not supported.

--default-dir Name of the directory where the default contents will be stored. This is a useful feature for apps that use a dynamic default directory that’s created and managed by the ‘combine’ mode.
--exclude, -e Add a file pattern to exclude from extraction. Splunk’s pseudo-glob patterns are supported here. * for any non-directory match, ... for ANY (including directories), and ? for a single character.
--keep, -k Specify a pattern for files to preserve during an upgrade. Repeat this argument to keep multiple patterns.
--allow-local

Allow local/* and local.meta files to be extracted from the archive.

Shipping local files is a Splunk app packaging violation so local files are blocked to prevent customizations from being overridden.

--git-sanity-check
 

By default, git status is run on the destination folder to detect working tree or index modifications before the unarchive process starts, but this is configurable. Sanity check choices go from least restrictive to most thorough:

  • Use off to prevent any ‘git status’ safety checks.
  • Use changed to abort only upon local modifications to files tracked by git.
  • Use untracked (the default) to look for changed and untracked files before considering the tree clean.
  • Use ignored to enable the most intense safety check which will abort if local changes, untracked, or ignored files are found.
--git-mode

Possible choices: nochange, stage, commit

Set the desired level of git integration. The default mode is stage, where new, updated, or removed files are automatically handled for you.

To prevent any git add or git rm commands from being run, pick the ‘nochange’ mode.

If a git commit is incorrect, simply roll it back with git reset or fix it with a git commit --amend before the changes are pushed anywhere else. There’s no native --dry-run or undo for unarchive mode because that’s why you’re using git in the first place, right? (Plus, such features would require significant overhead and unit testing.)

--no-edit Tell git to skip opening your editor on commit. By default, you will be prompted to review/edit the commit message. (Git Tip: Delete the content of the default message to abort the commit.)
--git-commit-args, -G
 Extra arguments to pass to ‘git’

Note

What if I’m not using version control?

Sanity checks and commit modes are automatically disabled if the app is being installed into a directory that is not contained within a git working tree. Ksconf confirms that git is present and functional before running sanity checks.