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
orgit 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 agit 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.