KSCONF
Overview
Details
https://github.com/Kintyre/ksconf
What is KSCONF?
KSCONF is a command-line tool that helps administrators and developers manage their Splunk environments by enhancing control of their configuration files. The interface is modular so that each function (or subcommand) can be learned quickly and used independently. While most users will probably only use a subset of the total capabilities of this tool, it’s reassuring to have a comprehensive toolbox of powerful assets ready to be utilized at a moment's notice. Ksconf works with, rather than replace, your existing Splunk deployment mechanisms and version control tools.
KSCONF is open source and an open development effort. Check us out on GitHub
Pronounced: k·s·kȯnf
Design principles
- Ksconf is a toolbox. - Each tool has a specific purpose and function that works independently. Borrowing from the Unix philosophy, each command should do one small thing well and be easily combined to handle higher-order tasks.
- When possible, be familiar. - Various commands borrow from popular UNIX command line tools such as “grep” and “diff”. The overall modular nature of the command is similar to the modular interface used by “git” and the “splunk” cli.
- Don’t impose workflow. - Ksconf works with or without version control and independently of your deployment mechanisms. If you are looking to implement these things, ksconf is a great building block.
- Embrace automated testing. - It’s impractical to check every scenario between each release, but significant work has gone into unit testing the CLI to avoid breaks between releases.
Common uses for ksconf
- Promote changes from “local” to “default”
- Maintain multiple independent layers of configurations
- Reduce duplicate settings in a local file
- Upgrade apps stored in version control
- Merge or separate configuration files
- Push .conf stanzas to a REST endpoint (send custom configs to Splunk Cloud)
What's in the KSCONF App for Splunk?
This Splunk app comes bundled with a CLI tool that helps manage other Splunk apps. While this is not a traditional use case for a Splunk app, it is a very quick and easy way to deploy ksconf.
Why did we make this a Splunk app? While ksconf is technically just a Python package that can be deployed in a variety of ways, we found that the logistics of getting it deployed can be quite difficult due to a packaging issues, legacy cruft, and OS limitations. This approach avoids all that mess.
Getting Started
Full documentation for ksconf, including this app, is hosted at read-the-docs. A full copy of the ksconf documentation is also included, similar to how Splunk ships with a full copy of the docs in the system/README folder. (And all the air-gapped people rejoice! but sadly, no one could hear them.)
Docs
- Official docs hosted via ReadTheDocs.io
- Command line reference
Need help?
- Ask questions
- Chat about #ksconf on the Splunk User group Slack channel
Get Involved
Roadmap
Additional Splunk UI features are planned, but currently not implemented.
- Dashboard to track all changes coordinated by
ksconf - Configuration snapshot tracking
- Custom SPL command to give visibility into what exists in the
localfolder. (The built-inrestcommand only shows you the final merged view of your settings; and sometimes you have to look deeper.)
Installation & Configuration
See the Install an add-on in Splunk's official documentation. There is one manual step required to activate the CLI portion of this app, if you choose to do so. See the Installation docs for more details.
Support
Community support is available on best-effort basis. For information about commercial support, contact Kintyre
Issues are tracked via GitHub
History
See the full Change log
Release Notes
Version 0.12.3
Version 0.13.1
Version 0.12.1
- New
ksconf attr-getandksconf attr-setcommands - Added filter matching based on attribute/value combinations.
- Allow for in-place
ksconf mergeoperations - Tons of minor bug fixes (including the inline docs)
See full release notes
Version 0.11.9
Fix Splunk packaging bug.
See change log
Version 0.11.5
See full change log here:
https://ksconf.readthedocs.io/en/stable/changelog.html#ksconf-v0-11-5-2023-08-25
Version 0.11.7
See change log
Python packaging issue found. Do not use this version.
Version 0.9.2
- The
filtercommand can now include/exclude stanzas based on the boolean value ofdisabledusing the new--enabled-onlyor--disabled-onlyarguments. The default behavior remains the same, that is, thedisabledattribute is completely ignored.
Version 0.9.1
- Ksconf now tries harder to preserve file modification times. This is supported in
merge,combineandpackagecommands.
Specifically, merged.conffiles and concatenated files will keep the most recent modification time in the destination.
This should make the output of`ombineandpackage(by extension) more deterministic in many scenarios.
Version 0.9.0
- Expand use cases for
ksconf combinewith new--keep-existing <pattern>and--disable-cleanuparguments. - Support
ksconf promoteby combining--stanza <pattern>and--summaryor--diffoptions at the same time. - New
ksconf diffoutput options for (1) setting detail level using--detail {global,stanza,key}and (2) new JSON output format with--format json. Fixed an diff output bug and some inconsistencies in space. - Allow enabling/disabling TTY colors via environmental variable:
KSCONF_TTY_COLOR={auto,force,off}. This can also be done with--disable-colorCLI option.
Read the full change log here:
https://ksconf.readthedocs.io/en/v0.9.0/changelog.html#ksconf-0-9
Version 0.8.7
- Support combining
*.conf.specfiles inksconf combine, thus allowingREADME.dto be it's own layer. - Fixed potential
ksconf unarchiveissue with older version of git wheregit add DIRdidn't assume the--alloption. So if you're stuck on git 1.7/1.8 ksconf should still work
Version 0.8.6
- Fixed
install.pySplunk app CLI install helper script to support referencing a specific version of Python. This allows Splunk 8.0 user sto run ksconf using Python3, for example. - Minor doc tweaks
- Fixed ASCII art issue.
Full list:
https://ksconf.readthedocs.io/en/devel/changelog.html#ksconf-v0-8-6-2020-04-20
Version 0.8.4
Build and packaging enhancements
- CLI change: Replaced short option for
--allowlistto be-a, before it was-w. - Add some safety checks to the
packagecommand to check for app naming issues and hidden files and directories. - Added
{{app_id}}variable toksconf packagecommand. - Added a new optional argument to
copy_files()for additional control over the destination path in the build folder. - Minor tweak to unhandled exceptions. The name of the exception class is now shown.
- When using
make_missinginupdate_conf(), missing directories will now be created too. - Additional fixes to the Ksconf for Splunk App
build.pyscript
See details here: https://ksconf.readthedocs.io/en/v0.8.4/changelog.html#ksconf-v0-8-4-2020-03-22
Version 0.8.3
- New command ksconf package is designed for both Splunk developers and admins. This includes simple but helpful options to merge ‘local’ into ‘default’, set the an app version, set the top-level folder name (if it’s different on the file system), and so on.
- New module ksconf.builder helps build Splunk apps using a pipeline; or when external Python libraries are bundled into an app
- Legit layer support with built-in layer filtering capabilities is available in several commands. Now you can easily have layers for both "default" and "lookups", for example.
- Python 3! Head's up: We'll be dropping support for Python 2 in an upcoming release
Official change log: https://ksconf.readthedocs.io/en/latest/changelog.html#ksconf-0-8
Version 0.7.10
Empty stanza bug fix
- Fixed bug where empty stanzas in the local file could result in stanza removal in default with
ksconf promote. - Updated
ksconf diffinterface to improve handling of empty stanzas
Version 0.7.8
Version 0.7.7
Version 0.7.6
Version 0.7.5
Version 0.7.4
Version 0.7.3
Version 0.7.2
Version 0.7.1
Version 0.7.0
This release fixes up packaging issues with python package folders that may caused issues after upgrades. Unfortunately, this means everyone who had installed 0.6.x should uninstall and do a fresh install of 0.7.0. Hopefully this issue is resolved and extra steps like this won't be required in the future.
As always, read the full change log here:
https://ksconf.readthedocs.io/en/v0.7.0/changelog.html#release-v0-7-0-2019-02-27