Installation Guide

KSCONF can be installed either as a Splunk app or a Python package. Picking the option that’s right for you is fairly easy.

Unless you have experience with Python packaging or are planning on customizing or extending Ksconf, then the Splunk app is likely the best place for you to start. The native Python package works well for many developer-centric scenarios, but installation ends up being complicated for the more typical admin-centric use-case. Therefore, most users will find it easier to start with the Splunk app.

Note

The introduction of a Splunk app is a fairly new occurrence (as of the 0.6.x release). Originally we resisted this idea, since ksconf was designed to manage other apps, not live within one. Ultimately however, the packaging decision was made to ensure users of all levels can utilize the program, as Python packaging is a mess and can be daunting for the uninitiated.

Overview

Install Advantages Potential pitfalls
Python package
  • Most ‘pure’ and flexible install
  • One command install. (ideal)
  • Easy upgrades
  • More extendable (plugins)
  • Install Python package
  • Lots of potential variations and pitfalls
  • Many Linux distro’s don’t ship with pip
  • Must consider/coordinate installation user.
  • Often requires some admin access.
  • Too many install options (complexity)
Splunk app
  • Quick installation (single download)
  • Requires one time bootstrap command
  • Self contained; no admin access require
  • Fast demo; fight with pip later
  • Install Splunk App
  • Crippled Python install (no pip)
  • Can’t add custom extensions (entrypoints)
  • No CLI completion (yet)
  • Grandfather Paradox
Offline package
  • Requires many steps.
  • Inherits ‘Python package’ pitfalls.

Requirements

Python package install:

  • Python Supports Python 2.7, 3.4+
  • PIP (strongly recommended)
  • Tested on Mac, Linux, and Windows

Splunk app install:

  • Splunk 6.0 or greater is installed

Install Splunk App

Download and install the KSCONF App for Splunk. Then open a shell, switch to the Splunk user account and run this one-time bootstrap command.

splunk cmd python3 $SPLUNK_HOME/etc/apps/ksconf/bin/install.py

On Windows, open a terminal as Administrator and type:

cd "C:\Program Files\Splunk"
bin\splunk.exe cmd python3 etc\apps\ksconf\bin\install.py

Note

Splunk 7 vs Splunk 8

The above command will use Python 3 which will shortly be the only version supported. If you’re stuck on Splunk 7 or earlier, please replace python3 with python in the command above.

This will add ksconf to Splunk’s bin folder, thus making it executable either as ksconf or, less optimally, splunk cmd ksconf. (If you can run splunk without giving it a path, then ksconf should work too.)

At some point we may add an option for you to do this setup step from the UI.

Note

Alternate download

You can also download the latest (and pre-release) SPL from the GitHub Releases page. Download the file named like ksconf-app_for_splunk-ver.tgz

Install Python package

Quick Install

Using pip:

pip install kintyre-splunk-conf

System-level install: (For Mac/Linux)

curl https://bootstrap.pypa.io/get-pip.py | sudo python - kintyre-splunk-conf

Enable Bash Completion

Context-aware autocomplete can be a great time saver. If you’re on a Mac or Linux, and would like to enable bash completion, run these commands:

pip install argcomplete
echo 'eval "$(register-python-argcomplete ksconf)"' >> ~/.bashrc

(This option is not currently available for Splunk App installs due to a lack of documentation and testing available presently. It should be possible. Pull requests are welcome.)

Ran into issues?

If you encounter any issues, please refer to the Advanced Installation Guide. Substantial time and effort was placed into the assembly of the information based on various scenarios we encountered. A good place to begin would be in the Troubleshooting section.

Install from GIT

If you’d like to contribute to ksconf, or just build the latest and greatest, then installing from the git repository is a good choice. (Technically this is still installing with pip, so it’s easy to switch between a PyPI install, and a local install.)

git clone https://github.com/Kintyre/ksconf.git
cd ksconf
pip install .

See Developer setup for additional details about contributing to ksconf.

Validate the install

No matter how you install ksconf, you can confirm that it’s working with the following command:

ksconf --version

The output should look something like this:

                                  #
                                  ##
 ###  ##     #### ###### #######  ###  ##  #######
 ### ##     ###  ###           ## #### ##
 #####      ###  ###      ##   ## #######  #######
 ### ##     ###  ###      ##   ## ### ###  ##
 ###  ## #####    ######   #####  ###  ##  ##
                                        #

ksconf 0.7.3  (Build 376)
Python: 2.7.15  (/Applications/splunk/bin/python)
Git SHA1 dc94f811 committed on 2019-06-05
Installed at: /Applications/splunk/etc/apps/ksconf/bin/lib/ksconf
Written by Lowell Alleman <lowell@kintyre.co>.
Copyright (c) 2019 Kintyre Solutions, Inc, all rights reserved.
Licensed under Apache Public License v2

  kintyre_splunk_conf  (0.7.3)

    Commands:
      check           (stable)    OK
      combine         (beta)      OK
      diff            (stable)    OK
      filter          (alpha)     OK
      merge           (stable)    OK
      minimize        (beta)      OK
      promote         (beta)      OK
      rest-export     (beta)      OK
      rest-publish    (alpha)     OK   (splunk-sdk 1.6.6)
      snapshot        (alpha)     OK
      sort            (stable)    OK
      unarchive       (beta)      OK
      xml-format      (alpha)     OK   (lxml 4.2.5)

Missing 3rd party libraries

Note

Splunk app for KSCONF users don’t need to worry about this.

As of version 0.7.0, ksconf now includes commands that require external libraries. But to keep the main package slim, these libraries aren’t strictly required unless you want the specific commands. As part of this change, ksconf --version now reports any issues with individual commands in the 3rd column. Any value other than ‘OK’ indicates a problem. Here’s an example of the output if you’re missing the splunk-sdk package.

...
promote         (beta)      OK
rest-export     (beta)      OK
rest-publish    (alpha)     Missing 3rd party module:  No module named splunklib.client
snapshot        (alpha)     OK
...

Note that while the rest-publish command will not work in the example above, all of the other commands will continue to work fine. If you don’t need rest-publish then there’s no need to do anything about it. If you want the packages, install the “thirdparty” extras using the following command:

pip install kintyre-splunk-conf[thirdparty]

Other issues

If you run into any issues, check out the Validate the install section.

Command line completion

Bash completion allows for a more intuitive and interactive workflow by providing quick access to command line options and file completions. Often this saves time since the user can avoid mistyping file names or be reminded of which command line actions and arguments are available without switching contexts. For example, if the user types ksconf d and hits Tab, then the ksconf diff is completed. Or if the user types ksconf, and hits Tab twice, the full list of command actions are listed.

This feature uses the argcomplete Python package and supports Bash, zsh, tcsh.

Install via pip:

pip install argcomplete

Enabling command line completion for ksconf can be done in two ways. The easiest option is to enable it for ksconf only. (However, it only works for the current user; it can break if the ksconf command is referenced in a non-standard way.) The alternate option is to enable global command line completion for all python scripts at once, which is preferable if you use argparse for many python tools.

Enable argcomplete for ksconf only:

# Edit your bashrc script
vim ~.bashrc

# Add the following line
eval "$(register-python-argcomplete ksconf)"

# Restart you shell, or just reload by running
source ~/.bashrc

To enable argcomplete globally, run the command:

activate-global-python-argcomplete

This adds a new script to your the bash_completion.d folder, which can be used for all scripts and all users, but it does add some minor overhead to each completion command request.

OS-specific notes:

  • Mac OS X: The global registration option may not work as the old version of Bash was shipped by default. So either use the one-shot registration, or install a later version of bash with homebrew: brew install bash then. Switch to the newer bash by default with chsh /usr/local/bin/bash.
  • Windows: Argcomplete doesn’t work on windows Bash for GIT. See argcomplete issue 142 for more info. If you really want this, use Linux subsystem for Windows instead.