nbkit.caboodle(7) NodeBrain Administrator Guide
Version 0.9.03 - December 2014
nbkit.caboodle(7)

NAME | SYNOPSIS | DESCRIPTION | DIRECTORIES | VERSION CONTROL | HISTORY | BUGS | AUTHOR | DOCUMENTATION | SEE ALSO


NAME

  nbkit.caboodle - NodeBrain Kit and Caboodle Framework

SYNOPSIS

  nbkit caboodle { start | stop | bounce | ... } Caboodle

DESCRIPTION

  The NodeBrain Kit and Caboodle Framework is a method of managing NodeBrain applications. The nbkit(1) command works with a NodeBrain caboodle constructed from NodeBrain kits. The Caboodle NodeBrain Kit provides an initial set of components for managing NodeBrain applications as caboodles. While NodeBrain is a rule engine that can be used however you like, NodeBrain kits conform to this framework to provide a quick path to a working application. You are encouraged to build applications and application kits based on this framework, unless you find or create a framework that works better for your application.

The following common terms have a specific meaning within the context of the NodeBrain Kit and Caboodle Framework.

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 root directory. 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 translation scheme. A plan compiler converts a plan from XML document format into a target format, often NodeBrain rules.

adapter    A script or program that adapts a caboodle component to another application or specifc environment. For example, adapters may be used to send alarms to syslog, email to administrators, and SNMP traps to downstream systems.

servant    A script or program that runs as a child to NodeBrain to perform a function for which another programming language is preferred. Servants may communicate with NodeBrain on stdin, stdout, and stderr.

DIRECTORIES

  Within a caboodle there are several subdirectories with a defined purpose. All components within a caboodle must assume the caboodle is the working directory and reference other components via a relative path to maintain portability of the caboodle.

The Caboodle NodeBrain Kit does not make use of all the directories listed below. Some are defined only to provide guidance for other kits.

.nb    A special directory for use by the nb (NodeBrain interpreter) command. If a caboodle.nb file is found in this directory, NodeBrain sources it at startup. Variables defined here may be used within rule files to adapt to a particular instance of a caboodle for a given application, where other components are shared by all instances.

This is the only directory within a caboodle of which the NodeBrain interpreter seems to have some awareness. In fact, the NodeBrain interpreter has no awareness of caboodles. It simply supports a .nb directory in the working directory, and the caboodle concept depends on the caboodle being the working directory when the interpeter and all other components are invoked.

This directory should not be used by components other than NodeBrain and node modules to avoid naming conflicts.

adapter    Commands that adapt a NodeBrain application component to specific interface requirements. For example, alarm adapters can be included here to adapt alarms to a particular protocol or to an external event management system interface.

agent    NodeBrain agent scripts. It is best to manage agents using an agent plan, in which case the agent script in this directory will be generated for you by the agent compiler. This directory also has files that identify the expected state of each agent.

bin    Used for commands that do not fall into the categories for which other directories are defined. See adapter, agent, exit, and servant directories.

cache    This directory has subdirectories that contain files used to cache information for a limited duration to avoid more expensive lookup, often where lookup may be relatively frequent. In cases where deleting the data would impact more than just the performance hit of having to perform a more expensive lookup, the var directory should be used instead.

config    This directoy may continue configuration files that are unique to a given caboodle. However, this directory is deprecated and you should use the etc directory for all new configuration files.

etc    Configuration files unique to a given caboodle amongst multiple caboodles synchronizing other components via a version control system. Since it is not appropriate to version control this file in a repository shared by other caboodles, it is sometimes helpful to manage these files using plans with compilers that can be directed to produce files in this directory based on symbolic variables and conditional compilation. See the .nb and plan directories.

exit    Commands that communicate a result via their exit code only. Unlike servants, these commands are normally not designed for use with NodeBrain. However, their exit code may identity the state of a monitored element, making it easy to map the exit code into a NodeBrain assertion.

kit    Used to manage kit dependencies. This directory is reserved for the nbkit command and should not be used by other kit components.

lib    Libraries and Perl modules supporting other kit components. As with all caboodle components, these components must be referenced using a relative path to maitain portability of the caboodle.

log    Log files for agents and other kit components. NodeBrain agents normally manage the rotation, compression, and deletion of their log files. When including other log files here, remember to provide the necessary management to avoid filling up your file system. Consider using the Caboodle agent to manage additional log files unless you have a more convenient method.

message    Used by the Message module and other modules using the NodeBrain Message Log API. Do not use this directory for other purposed.

msg    Used by alarm adapters (e.g. adapter/mail.alarm) that lookup and include a description of the alarm condition and response instructions. Subdirecties are defined for logical sets of alarms identified by the first three or four characters of a message identifier. For example a message CAB0001 would be described in the CAB subdirectory in a file named CAB0001. Within the message set subdirectory (e.g. CAB) additional files provide header, footer, and missing file text.

out    Output files produced by commands issued by NodeBrain when the output is not redirected. These files are retained for a few days for troubleshooting.

pipe    FIFO files for sending commands to Pipe nodes in NodeBrain agents or for communicating between other caboodle components.

plan    Contains a subdirectory for each plan, including the XML document, plan relationship files, and normally any files generated from the XML document by the associated compiler. In some cases the generated files go to another directory (e.g. \fPetc\fP) that does not share the same version control repository used by the plan directory.

queue    This directory contains subdirectories for Peer module gueues. This mechanism is deprecated and a future release of the Peer module will switch to message logs. NodeBrain message logs provide a more efficient method of sending events between agents and are currently supported by the Message module. See the Message module manual for more info.

security    Contains certificates and access lists.

servant    Contains servant commands that output NodeBrain commands to stdout. Commands that do not conform to this standard belong in bin, adapter, or exit. Servant commands may optionally accept commands from NodeBrain on stdin and report error conditions on stderr.

setup    Setup components. A kit may provide components in this directory for setting up an application.

socket    Local domain socket files for communication between NodeBrain processes using the Peer module. This directory may also be used for communication between other caboodle components that use local domain socket files.

user    Application user files. This directory is for storing user preferences and other user related information. There is no recommendation on how to organized user data in this directory.

var    Data files used in the normal operation of a NodeBrain application. Use the cache directory for temporary caching of data obtained from a more authoritive source.

web    Web content and scripts for web based tools. Individual tools should use sub-directories. For example, the NodeBrain planner uses the "planner" subdirectory and the Webster modules uses the "webster" subdirectory by default.

VERSION CONTROL

  It is a recommended practice to put the following caboodle subdirectories under version control.

    adapter, bin, exit, lib, msg, plan, servant, user, and web

When a NodeBrain application is distributed over multiple instances of like caboodles, a version control system may be used to provide synchronization of NodeBrain rules and other caboodle components. Using this approach, the recommended directories are checked out at each instance of the caboodle. A caboodle is then a working directory where only a subset of the directories a under version control. Changes at one instance of the caboodle can be commit to the repository with an update performed at the other instances to pick up the same changes. NodeBrain application used to monitor a group of like servers that required the same set of monitoring rules and components would be a good candidate for this approach. In this case it is best to identify a master caboodle where the updates are applied first. This helps to avoid conflicts that can easily occur in the plan XML documents because of the way the NodeBrain planner time stamps some of the XML elements.

HISTORY

  Work on the Caboodle NodeBrain Kit began in June of 2006, defining the NodeBrain Kit and Caboodle Framework. It is based on a tool developed in 1998 called the "System Monitor Kit", or "Sysmon". The NodeBrain program, nb(1), was first developed for Sysmon and then released as a single component in 2003 by the NodeBrain Open Source Project. NodeBrain kits were first released by the project in February of 2013.

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(1), nodebrain(7) nb(1)

NodeBrain 0.9.03December 2014nbkit.caboodle(7)