Cheat Sheet

Here’s a quick rundown of handy ksconf commands:

Note

Note that for clarity, most of the command line arguments are given in their long form. Many options also have a short form too.

Long commands may be broken across line for readability. When this happens, a trailing backslash (\) is added so the command could still be copied verbatim into most shells.

General purpose

Comparing files

Show the differences between two conf files using ksconf diff.

ksconf diff savedsearches.conf savedsearches-mine.conf

Sorting content

Create a normalized version a configuration file, making conf files easier to merge with git. Run an in-place sort like so:

ksconf sort --inplace savedsearches.conf

Tip

Use the ksconf-sort pre-commit hook to do this for you.

Extract specific stanza

Say you want to grep your conf file for a specific stanza pattern:

ksconf filter search/default/savedsearches.conf --stanza 'Errors in the last *'

Say you want to list stanzas containing cron_schedule:

ksconf filter Splunk_TA_aws/default/savedsearches.conf --brief \
    --attr-present 'cron_schedule'

Remove unwanted settings

Say you want to remove vsid from a legacy savedsearches file:

ksconf filter search/default/savedsearches.conf --reject-attrs "vsid"

To see just to the schedule and scheduler status of scheduled searches, run:

ksconf filter Splunk_TA_aws/default/savedsearches.conf \
    --attr-present cron_schedule \
    --keep-attrs 'cron*' \
    --keep-attrs enableSched
    --keep-attrs disabled

Cleaning up

Reduce cruft in local

If you’re in the habit of copying the default files to local in the TAs you deploy, here a quick way to ‘minimize’ your files. This will reduce the local file by removing all the default settings you copied but didn’t change. (The importance of this is outlined in Minimizing files.)

ksconf minimize Splunk_TA_nix/default/inputs.conf --target Splunk_TA_nix/local/inputs.conf

Pushing local changes to default

App developers can push changes from the local folder over to the default folder:

ksconf promote --interactive myapp/local/props.conf myapp/default/props.conf

You will be prompted to pick which items you want to promote. Or use the --batch option to promote everything in one step, without reviewing the changes first.

Advanced usage

Migrating content between apps

Say you want to move a bunch of savedsearches from search into a more appropriate app. First create a file that list all the names of your searches (one per line) in corp_searches.txt

ksconf filter --match string --stanza 'file://corp_searches.txt' \
    search/local/savedsearches.conf --output corp_app/default/savedsearches.conf

And now, to avoid duplication and confusion, you want to remove that exact same set of searches from the search app.

ksconf filter --match string --stanza 'file://corp_searches.txt' \
    --invert-match search/local/savedsearches.conf \
    --output search/local/savedsearches.conf.NEW

# Backup the original
mv search/local/savedsearches.conf \
    /my/backup/location/search-savedsearches-$(date +%Y%M%D).conf

# Move the updated file in place
mv search/local/savedsearches.conf.NEW search/local/savedsearches.conf

Note

Setting the matching mode to string prevents any special characters that may be present in your search names from being interpreted as wildcards.

Migrating the ‘users’ folder

Say you stood up a new Splunk server and the migration took longer than expected. Now you have two users folders and don’t want to loose all the goodies stored in either one. You’ve copied the users folder to user_old. You’re working from the new server and would generally prefer to keep whatever on the new server over what’s on the old. (This is because some of your users copied over some of their critical alerts manually while waiting for the migration to complete, and they’ve made updates they don’t want to lose.)

After stopping Splunk on the new server, run the following commands.

mv /some/share/users_old  $SPLUNK_HOME/etc/users.old
mv $SPLUNK_HOME/etc/users $SPLUNK_HOME/etc/users.new

ksconf combine $SPLUNK_HOME/etc/users.old $SPLUNK_HOME/etc/users.new \
    --target $SPLUNK_HOME/etc/users --banner ''

Now double check the results and start Splunk back up.

We use the --banner option here to essential disable an output banner. Because, in this case, the combine operation is a one-time job and therefore no warning is needed.

Putting it all together

Pulling out a stanza defined in both default and local

Say wanted to count the number of searches containing the word error

ksconf merge default/savedsearches.conf local/savedsearches.conf \
    | ksconf filter - --stanza '*Error*' --ignore-case --count

This is a simple example of chaining two basic ksconf commands together to perform a more complex operation. The first command handles the merge of default and local savedsearches.conf into a single output stream. The second command filters the resulting stream finding stanzas containing the word ‘Error’.

Building an all-in one TA for your indexing tier

Say you need to build a single TA containing all the index-time settings for your indexing tier. (Note: Enterprise Security does something similar this whenever they generate the indexer app.)

ksconf merge etc/apps/*TA*/{default,local}/props.conf \
    | ksconf filter --output=TA-for-indexers/default/props.conf \
      --include-attr 'TRANSFORMS*' \
      --include-attr 'TIME_*' \
      --include-attr 'MUST_BREAK*' \
      --include-attr 'SHOULD_LINEMERGE' \
      --include-attr 'EVENT_BREAKER*' \
      --include-attr 'LINE_BREAKER*'

This example is incomplete because it doesn’t list every index-time props.conf attribute, and leaves out file:transforms.conf and fields.conf, but hopefully you get the idea.