nbkit(1) NodeBrain Administrator Guide
Version 0.9.03 - December 2014
nbkit(1)

NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | CABOODLE COMMANDS | AGENT COMMANDS | PLAN COMMANDS | FILES | HISTORY | BUGS | AUTHOR | DOCUMENTATION | SEE ALSO


NAME

  nbkit - NodeBrain Kit Utility

SYNOPSIS

  nbkit { -c | --caboodles | -k | --kits }

nbkit caboodle verb [arguments]

nbkit caboodle link directory

nbkit caboodle unlink

nbkit caboodle use kit

nbkit caboodle { export | import | upgrade } archive-file

nbkit caboodle alarm [ route="..." ] [ appl="..." ] [ group="..." ] [ node="..." ] [ severity="..." ] [ text="..." ]

nbkit caboodle { archive | bounce | config | connect | start | stop } agent

nbkit caboodle { commit | compile | disable | edit | enable | list | setup | view } plan

DESCRIPTION

  The nbkit(1) command is used to manage NodeBrain applications that conform to the NodeBrain Kit and Caboodle Framework described by the nbkit.caboodle(7) manual page. While the nbkit(1) command is provided with the NodeBrain rule engine, it is designed to work with caboodles built using NodeBrain kits. Caboodles reside on systems where the rule engine is installed, while kits are development tools not normally installed on production systems.

The Caboodle NodeBrain Kit provides the key components of a caboodle necessary for many of the nbkit command options described here to work. Without a caboodle constructed from the Caboodle NodeBrain Kit (or a compatible package), the nbkit command has little or no value. The Caboodle NodeBrain Kit also provides caboodle components enabling a web interface for browser access to most of the same operations performed using the nbkit command.

The nbkit command is primarily a method of invoking an nbkit_ command within a caboodle. This means the actual behavior of many of the commands described here will depend of the version of the Caboodle NodeBrain Kit used to create your caboodle.

The following common terms have a specific meaning within the context of a NodeBrain kit.

caboodle    A directory containing a collection of components organized into a predefined set of subdirectories. Components make reference to other components using paths relative to the caboodle. This makes a caboodle portable.

kit    A collection of components organized like a caboodle, but intended for distribution and used to construct caboodles or add functionality to existing caboodles. A caboodle may be composed from multiple kits.

agent    A NodeBrain script that runs as a background process, or daemon.

plan    An XML document used to represent a set of NodeBrain rules or configuration files based on a model. A plan compiler converts a plan from XML document format into a target format, often NodeBrain rules.

ARGUMENTS

 

-c    Display a list of defined caboodles.
--caboodle   

-k    Display a list of installed NodeBrain kits.
--kits   

caboodle    This argument is specified on most nbkit commands to identify the caboodle upon which to operate. The value specified is a single word alias for the caboodle path. See the link command in the next section.

verb    This argument identifies the operation to be performed on the specified caboodle.

arguments    Additional arguments depend on the verb specified.

CABOODLE COMMANDS

  Commands that operate on a caboodle without reference to specific components are described in this section. Commands that operate on agents and plans are described in the next two sections.

link    Use to define a caboodle. This command simply creates a symbolic link in the home directory of the user under a subdirectory of ".nb/caboodle". Other commands make use of the symbolic link to set the working directory before performing an operation.

    nbkit caboodle link directory

For a caboodle directory "/var/foobar" that you want to reference as "foobar", you would enter the following command.

    nbkit foobar link /var/foobar

unlink    Use to undefine a caboodle.

    nbkit caboodle unlink

If you want to redefine a caboodle to use a different directory, it is not necessary to use "unlink". You may simply issue a "link" command again specifying a different directory.

use    The "use" verb associates a caboodle with an installed kit. This makes the components provided by the kit available to the caboodle.

    nbkit caboodle use kit-directory

To associate nbkit-system-0.8.14 with a caboodle, the command would be as follows.

    nbkit caboodle use /usr/share/nbkit/nbkit-system-0.8.14

export    Use to export a caboodle to a compressed tar file as a backup, or to copy to another server. Log files and other files considered to be caboodle specific and of no value to similar caboodles are not exported.

    nbkit caboodle export archive-file

For example:

    nbkit mycaboodle export /tmp/mycaboodle.tar.gz

import    Use to import an exported caboodle into a similar caboodle without replacing locally modified components, and without disturbing components in the caboodle not found in the archive. This is appropriate in cases where there is local maintenance performed downstream from the source of the archive, including cases where a caboodle is a combination of imports from multiple upstream archive providers.

    nbkit caboodle import archive-file

For example:

    nbkit mycaboodle2 import /tmp/mycaboodle.tar.gz

upgrade    Use to upgrade a caboodle from an exported caboodle, without protecting local modifications and additions. This is appropriate when following a policy of not making local modifications, and the archive provides a complete set of application components.

    nbkit caboodle upgrade archive-file

For example:

    nbkit mycaboodle2 upgrade /tmp/mycaboodle.tar.gz

alarm    Generate an alarm to subscribers. This command sends a NodeBrain alert command to the alarm node of the Caboodle agent supporting the specified caboodle. Multiple optional alarm attributes may be specified. Some have default values when not specified. All alarm attributes may be referenced by an alarm subscription, which is required for actual distribution of the alarm.

    nbkit caboodle alarm attribute="value" [ ... ]

Specify one or more alarm attributes:

appl    Specify the name of the application to which the alarm applies.

group    Specify a value that categories the alarm; e.g. "OS", "Database", "Web". The group attribute is intented to route alarms to a unique group of subject experts. This is unlike the route attributes which may be used to provide visibility to various interested recipients.

node    Specify the hostname associated with the alarm. By default, the local hostname is used.

route    Specify a comma seperated list of routing codes for alarm subscriptions. The codes are strings that have meaning within a given application. For example, if the caboodle is a security event monitoring application, a value of "SOC" might be used to indicate the alarm is intented for the Security Operations Center. Multiple codes may be entered; e.g. "SOC,NOC".

severity    Specify a level of severity for the alarm. Typical values are "critical", "major", "minor", "warning" and "info", although you may select alternate values that work better in the context of your application.

text    Specify message text that describes the alarm condition; e.g. "Roof flew off the barn". You may include a message identifier of the form AAANNNN at the start of the text; e.g. "PWS0125 Roof flew off the barn".

AGENT COMMANDS

  Commands in this section operate on NodeBrain agents and are handed off to the bin/nbkit_agent command within the specified caboodle. An agent is a NodeBrain script that runs as a daemon.

    nbkit caboodle verb agent

The agent parameter must specify the name of an agent plan and/or the name of a NodeBrain script in the agent subdirectory; e.g. "Caboodle". To start the Caboodle agent provided by the Caboodle NodeBrain Kit, the command would be:

    nbkit caboodle start Caboodle

Specify one of the following verbs:

archive    Start a new log file after renaming the current log file with a current time stamp.

bounce    Stop and start the agent. If the current expected state is "down", the agent will be started and the expected state will change to "up".

check    Check expected state of an agent and change the current state to match. If an agent is expected to be "up" but is currently "down", it is started. If it is "up" and expected "down", it is stopped.

connect    Invoke the NodeBrain interpreter in interactive mode and prompt for commands to be issued to the specified agent.

start    Start the specified agent if it is currently "down" and set the expected state to "up".

stop    Stop the specified agent if it is currently "up" and set the expected state to "down".

PLAN COMMANDS

  Commands in this section operate on NodeBrain plans and are handled by the bin/nbkit_plan command within the specified caboodle. A plan is an XML document that normally translates into a set of NodeBrain rules or a configuration file based on a model. Compilers are provided to perform this translation. When an agent is managed as a plan, just one type of plan, these commands may be used to operate on the agent.

    nbkit caboodle verb plan

Operations performed by these commands may also be performed by the NodeBrain Planner web interface.

compile    Convert a plan XML document into the target format.
disable    Put a plan in a disabled state, or disable a relationship between two plans.
edit    Edit a plan configuration file. The XML document is converted into a temporary file with a less complex format and vi is invoked to edit the file. After exiting vi, the file is converted back into XML document format. The XML document is then optionally converted into a target format by the associated compiler.

enable    Allow a plan to generate alerts and start probe.
help    Display this list of commands.
list    Display a list of configured plan.
remove    Remove a plan from configuration.
rename    Rename a plan.
setup    Invoke assisted setup script for a plan.
show    Display plan relationships.
status    Display current status of plans.
view    Browse a plan configuration file.

FILES

 

~/.nb/caboodle    The caboodles are defined by a user, the caboodle name is defined as a symbolic link to the caboodle directory. The links are located in the ".nb/caboodle" subdirectory of the home directory of the user.
/usr/share/nbkit/kit    When kits are installed, the platform indepenent components are in this directory or "/usr/local/share/nbkit/kit

HISTORY

  The nbkit command was developed as part of the Caboodle NodeBrain Kit in 2006. It derives from a similar scheme developed for NodeBrain in 1998 called the System Monitor Kit or Sysmon.

BUGS

  Please report bugs to <bugs@nodebrain.org> or enter a bug report at http://nodebrain.org.

AUTHOR

  Ed Trettevik <eat@nodebrain.org>

DOCUMENTATION

  Online documentation is available at http://nodebrain.org. Manuals are also available in Texinfo format in the git repository. These documents are included in source distribution files.

SEE ALSO

  nbkit.caboodle(7) nodebrain(7), nb(1)

NodeBrain 0.9.03December 2014nbkit(1)