ksconf minimize

See also

See the Minimizing files for background on why this is important.

Minimize a conf file by removing any duplicated default settings.

Reduce a local conf file to only your intended changes without manually tracking which entries you’ve edited. Minimizing local conf files makes your local customizations easier to read and often results in cleaner upgrades.

usage: ksconf minimize [-h] [--target TARGET] [--dry-run | --output OUTPUT]
                       [--explode-default] [-k PRESERVE_KEY]
                       CONF [CONF ...]

Positional Arguments

CONF The default configuration file(s) used to determine what base settings are. The base settings determine what is unnecessary to repeat in target file.

Named Arguments

--target, -t The local file that you wish to remove duplicate settings from. This file will be read from and then replaced with a minimized version.
--dry-run, -D Enable dry-run mode. Instead of writing and minimizing the TARGET file, preview what would be removed as a ‘diff’.
--output

Write the minimized output to a separate file instead of updating TARGET.

This option can be used to preview the actual changes. Sometimes if --dry-run mode produces too much output, it’s helpful to look at the actual minimized version of the file in concrete form (rather than a relative format, like a diff.) This may also be helpful in other workflows.

--explode-default, -E
 

Enable minimization across stanzas for special use-cases. Helpful when dealing with stanzas downloaded from a REST endpoint or btool list output.

This mode will not only minimize the same stanza across multiple config files, it will also attempt to minimize any default values stored in the [default] or global stanza as well. For this to be effective, it’s often necessary to include system-level defaults in the CONF list. For example, to trim out cruft in savedsearches.conf, make sure you add etc/system/default/savedsearches.conf as an input.

-k, --preserve-key
 Specify attributes that should always be kept.

Example usage

cd Splunk_TA_nix
cp default/inputs.conf local/inputs.conf

# Edit 'disabled' and 'interval' settings in-place
vi local/inputs.conf

# Remove all the extra (unmodified) bits
ksconf minimize --target=local/inputs.conf default/inputs.conf

Undoing a minimize

You can use ksconf merge to reverse the effect of minimize by running a command like so:

ksconf merge default/inputs.conf local/inputs.conf

Additional capabilities

For special cases, the --explode-default mode reduces duplication between entries in normal stanzas (as normal) and then additionally reduces duplication between individual stanzas and default entries. Typically you only need this mode if your dealing with a conf file that’s been fully expanded to include all the layers, which doesn’t happen under normal circumstances. This does happen anytime you download a stanza from a REST endpoint or munged together output from btool list. If you’ve ever done this with savedsearches.conf stanzas, you’ll be painfully aware of how massive they are! This is the exact use case that --explode-default was written for.

In such a case, it may be helpful to minimize against the full definition of default, which effectively requires looking at all the layers of default. This includes all global app settings, and system-level settings.

There are limitations to this approach.

  • You have to manually list out all the layers. (Sometimes just pointing to the system-level defaults is good enough)
  • Minimize doesn’t take namespace into account. This means ownership, sharing, and ACLs are ignored.

In many ways minimize mimics what Splunk does every time it updates a conf file, as discussed in How Splunk writes to conf files. If you find yourself frequently needing the power of --explode-default, at some point a potentially better approach may be to simply post stanzas to the REST endpoint. However, this typically does a good enough job, especially for offline scenarios.

Additionally, this command doesn’t strictly require a bloated file. For example, if disabled = 0 is both a global default, and set on a per-stanza basis, that could be reduced too. However, typically this isn’t super helpful.