README ¶
Kitctl
kitctl
is a command-line tool for working with Gravwell kits. It is designed so users can more easily maintain kits in version control repos.
Commands and Flags
Kitctl's basic syntax is similar to the go
tool:
kitctl [flags] <command> [arguments]
The commands are:
unpack
: unpack a kit filepack
: pack the kit into a fileinfo
: print information about the kitinit
: start a new kit from scratchconfigmacro
: manage config macrosdep
: manage dependencies
Commands may have sub-commands, which are presented as additional arguments. For example, to create a new config macro, use the "add" sub-command: kitctl configmacro add
.
Flags are specified before the command, e.g. kitctl -name "My Kit" init
. See each command's section for a list of flags it expects.
Unpack a Kit
To unpack a kit into the current directory, run kitctl unpack
and give it the path to a kit file:
; kitctl unpack /tmp/ipmi.kit
This creates a file named MANIFEST
and individual directories for each type of object in the kit:
MANIFEST file macro playbook template
dashboard license pivot searchlibrary
Pack a Kit
To pack a kit from the current directory, run kitctl pack
and give it the desired output filename:
; kitctl pack /tmp/mykit.kit
Get Kit Info
The kitctl info
command gives information about the kit in the current directory:
; kitctl info
•Kit ID: io.gravwell.ipmi
•Name: IPMI
•Description: An IPMI kit that pairs with the Gravwell IPMI ingester.
•Version: 2
•Minimum Gravwell version required: 4.1.6
•Maximum Gravwell version allowed: 0.0.0
•Dependencies:
none
•Items:
license BSD-2
macro IPMI
dashboard 46495878862902
dashboard 249638155122607
dashboard 205736850289731
template 22e76583-e349-4400-8fc4-b238378a9b23
[...]
file 070e37c1-051e-4eb5-9126-c346b970ad89
playbook c6032ccd-790e-4361-ab10-1620b6d98272
Create a New Kit
Use the init
command to start a new kit from scratch. Be aware that building a kit this way is challenging; we generally recommend building the initial kit within Gravwell, then migrating it to a version-controlled repository using kitctl unpack
.
; kitctl -name 'Sample Kit' -desc 'A sample kit' -id 'io.gravwell.sample' -minver '3.2.0' init
The init
command accepts the following flags:
-id <kit id>
specifies the unique ID for the kit, e.g.-id io.gravwell.networkenrichment
-name <kit name>
specifies the human-friendly name of the kit-desc <description>
sets a more detailed description for the kit-version <version>
(optional) sets the version for the kit. Defaults to 1.-minver <version>
(optional) sets a minimum Gravwell version for the kit, e.g.-minver 4.1.2
-maxver <version>
(optional) sets a maximum Gravwell version for the kit, e.g.-maxver 5.0.0
.
NOTE: Most users should not use the -maxver
flag without very good reason. Gravwell makes great efforts to support backward compatibility, so kits will typically work fine in newer versions of Gravwell.
Manage Config Macros
Config Macros are a special kind of macro. During kit installation, Gravwell will prompt the user to set values for the config macros. The configmacro
command offers several subcommands to manage config macros.
Config macros have two types: "tag" and "other". The type helps the Gravwell GUI prompt the user for potential values. If set to "tag", the GUI will only allow the user to specify tags. If set to "other", the user may enter any value.
configmacro list
This subcommand lists the names of all config macros in the current kit.
; kitctl configmacro list
FOO
BAR
configmacro show
This subcommand prints information about a specific config macro, selected using the -name
flag:
; kitctl -name FOO configmacro show
Name: FOO
Description: My config macro
Default value: changeme
Type: OTHER
configmacro add
This subcommand adds a new config macro to the current kit. It requires the following flags:
-name <name>
sets the macro name. Note that macros must be upper-case alphanumeric strings; the only other characters allowed are dash (-) and underscore (_).-desc <description>
sets a human-friendly description for the macro.-default-value <value>
specifies a default value for the macro.-macro-type <type>
sets the type of the macro. This should be either "tag" or "other".
To add a macro named IPMI_TAG
which defines the tag containing IPMI entries, with a default value of ipmi
, run this:
; kitctl -name 'IPMI_TAG' -desc 'Tag containing IPMI entries' -default-value ipmi -macro-type tag configmacro add
Note that kitctl will check the macro name against existing config macros and against all regular macros. It will reject any name that conflicts with an existing one.
configmacro del
This subcommand deletes an existing config macro. The name of the macro to delete is specified by the -name
flag:
; kitctl -name IPMI_TAG configmacro del
Manage Dependencies
Kits may specify dependencies, additional kits which must be installed before that kit can itself be installed. A dependency consists of a kit ID (e.g. io.gravwell.networkenrichment
) and a minimum kit version. Kitctl manages dependencies using the dep
command.
dep list
This subcommand lists all dependencies defined for the current kit.
; ../kitctl dep list
io.gravwell.networkenrichment >= 2
dep add
This subcommand adds a new dependency to the kit. Use the -id
flag to specify the kit ID and the -version
flag to give the required minimum version of that kit.
; kitctl -id io.gravwell.networkenrichment -version 2 dep add
dep del
This subcommand removes a dependency from the kit. Use the -id
flag to specify the dependency to be removed.
; ../kitctl -id io.gravwell.networkenrichment dep del
Documentation ¶
There is no documentation for this package.