nb - NodeBrain Interpreter, Agent, Client, and Utility.

nb { [ -d | --daemon | -p | --prompt | -q | --quit | -s | --solve ] | [ -b | --bail | -B | --noBail ] | [ -t | --trace | -T | --noTrace ] | variable=value | : command | file }

NodeBrain, nb(1), is a rule engine for state and event monitoring applications. It can be used as an application agent (Unix daemon or Windows service), interactive client, or command line utility. The NodeBrain rule language is relatively small and integrates with host shell scripting languages and command line utilities. The interpreter is designed to be lightweight, flexible, and extendable via modules conforming to NodeBrain’s Expert Skill Module C API. The built-in NodeBrain Protocol (NBP) supports encrypted and authenticated peer-to-peer communication that can operate through an SSH tunnel for added security.

See http://www.nodebrain.org for more information.

Switch options may be specified as single letters (e.g. -d) or names (e.g. --daemon). Arguments are processed in the order specified on the command line enabling option changes between files when specifying multiple input files.

The first set of options are used to specify an action to be taken after all of the command line arguments, including files, are processes. These options work as a group---turning one on terns the others off.

-d

The --daemon option is used to place nb in background mode after processing all arguments. This is the default option when listeners are defined, but must be explicitly specified for deaf daemons that are purely schedule driven.

-p

The --prompt option causes nb to prompt the interactive user for input after processing all arguments. This is the default when nb is invoked without any arguments.

-q

The --quit option causes nb to simply terminate after processing all arguments. This is the default option when no listeners have been defined. When listeners have been defined, the --daemon option is the default, but is overridden when you explicitly specify the --quit option.

-s

The --solve option is used to solve for unknown values after processing all arguments. This option is used for diagnostic batch scripts.

The next set of options control the behavior of NodeBrain while commands are processed and internal events are triggered.

-b

The --bail option is used to terminate on the first error message with an exit code of 1. This option is useful when a script or program calls nb to perform a task and wants to know if the request is successful. In this case, we also assume that every step of a multi-step command script must be successful for there to be any value in continuing.

-t

The --trace option is used by developers for debugging NodeBrain internal logic. Trace messages are written while this option is on.

-B

The --noBail option turns off the --bail option.

-T

The --noTrace option turns off the --trace option.

Global variables may be assigned for reference within command files. These are application specific variables you assign for your own purposes.

variable=value

There are two methods of supplying commands when invoking the interpreter: 1) using commands as arguments, and 2) using command files (scripts) as arguments.

:command

file

A full description of the NodeBrain command language is beyond the scope of this manual page. You will need to study the NodeBrain User’s Guide to master the concepts and syntax. You can access the document online at http://www.nodebrain.org/nbUserGuide.pdf. Here we will just point out there are commands that:

1) define a rule (i.e. condition and response),

2) assert a state change, and

3) take immediate action (e.g. execute a shell command).

Here’s one example of each, where the host shell command "echo" is used in both our delayed and immediate action.

define r1 on(a=b and c<5):-echo "r1 happened"

assert a=1,b=1,c=3;

-echo "r1 should have happened by now"

In some cases you may want to use NodeBrain as a special purpose scripting language. We say "special purpose" because NodeBrain is not procedural, and therefore not what you might expect in a scripting language. However, it may be a bit more convenient to invoke NodeBrain and a set of rules by coding a shebang ("#!") line on the rule file.

#!/usr/bin/nb arguments
... NodeBrain commands ...

If our example file is named "example1", we could invoke it as

$ ./sample1

instead of

$ nb arguments sample1

saving a few keystrokes. This is a Unix feature supported by NodeBrain simply because lines starting with hash ("#") are treated as comments.

Listeners provide another method of introducing commands to the NodeBrain rule engine when running as a Unix daemon or Windows service. Listeners can get commands from FIFO’s, log files, TCP/IP socket connections, and command queues. This enables communication between peer nb processes and between nb processes and other application processes.

~/.nb/private.nb

This is a user’s private configuration file. It may contain private keys and should be readable only by the owner.
 

*.nb

We recommend an ".nb" suffix on NodeBrain command (rule) files, although it is not required.
 

*.nbx

We recommend an ".nbx" suffix on NodeBrain line translation rule files. This also is not required.

There are no NodeBrain specific environment variables. Some of the C functions nb calls (e.g. for loading dynamic modules) are influenced by environment variables in ways we assume you can figure out for your environment.

0

Successful completion.
 

>0

An error occurred while the bail option was enabled, or a terminal error occurred. Use the diagnostic messages to identify the specific error.

NodeBrain is a bit verbose in logging commands and messages. The message format is

yyyy/mm/dd hh:mm:ss NB000a text

where "a" identifies a severity.

I

Information

T

Trace (debug information)

W

Warning

E

Error

L

Logic (error in NodeBrain code---condition that should not occur)

In version 1.0 you can expect "000" to be replaced with a message number from 001 to 999, providing better identification of each message condition. Options may also be added to make nb less verbose in logging input commands and output messages.

In 1998, NodeBrain was developed at The Boeing Company for Unix and Linux system monitoring in a small lab environment. In this application, NodeBrain was the decision making component in a kit that included Perl scripts for configuration, rule administration, state probes and rule actions.

In 2000, NodeBrain was used in a second experimental application at Boeing for enterprise wide intrusion detection alert correlation. In this application, it was adapted to handle events at a higher rate, support for Windows was added, and it was bundled with an Oracle database with a web user interface.

In February 2003, NodeBrain 0.5 was released as a "working prototype" under the GNU General Public License and is now managed as an Open Source project on http://SourceForge.net.

For a complete and current list of bugs, you must refer to the project web site. The bugs listed here are worth noting because they are not high on our list to resolve, so they may survive a few releases.

o

Time expressions will sometimes not produce the expected results because of what we call "the boundary problem" in our scheduling algorithm. There are normally ways to work around this problem by forcing a larger interval on the right side of an expression or sub-expression. You should use the FORECAST command to verify time expressions before using them in a rule.
 

o

Regular expressions have not been implemented for Windows platforms.
 

o

The --daemon option does not place nb in background mode on Windows. Instead, it ties up your command Window while continuing to run. However, NodeBrain will run as a service on Windows and provides commands for creating, starting, stopping and deleting services.

Since this is a prototype 0.x version, you can expect to encounter a few bugs that are unknown to the author. We have not yet developed a test suite for exercising individual features in a structured systematic way. Regression testing is performed using the author’s own applications by comparing the response of two different versions receiving a common (parallel) event stream. While this is useful for discovering bugs that might impact the author’s applications, it does not test the variety of rules and event streams you might invent.

Please report bugs by linking to the project page from the home page, http://www.nodebrain.org, or send email to <bugs@nodebrain.org>.

Ed Trettevik <eat@nodebrain.org>

nb.man(7), nb.cfg(5), nb.syn(5), nb.mod(7), nb.lib(3)

[1] NodeBrain Home Page

[2] NodeBrain User’s Guide