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

	-o
	--option

Variable settings start with a double minus ("--") followed be a setting assignment. See the SETTINGS section for a description of available settings.

--setting=value

Source variables may be assigned for symbolic substitution or conditional command interpretation within scripts. These are application specific global source variables you assign for your own purposes and reference as %variable or %{variable} inside a source file. When a value contains spaces or special characters you will need to quote the value or the entire argument. Although command shells allow escaped quotes (\") in a quoted argument, NodeBrain will not accept a quote within the value being assigned.

variable=value variable="value" "variable=value"

Commands may by specified as arguments starting with a semi-colon. When commands contain spaces or special characters you will need to quote the argument. Quotes used within the command must be escaped or enclosed within outer single quotes; e.g., ":assert name=\"john doe\";" or ':assert name="john doe";'.

:command :"command"

A command file may be specified with an optional assertion to set local source variables for symbolic substitution (%variable or %{variable}) and/or conditional interpretation. Special file names of "-" and "=" may be used to read from standard input (stdin). A minus sign "-" is used when you want a prompt for interactive input. An equal symbol "=" is used when you are piping commands into nb and want them written to standard output (stdout) without prompts.

file[,assertion] -[,assertion] =[,assertion]

An assertion is a comma seperated list of assignments. Assignment of string values requires the use of quotes, so you will need to enclose the entire argument in quotes and escape the quotes within the assertion. Here are some examples of file arguments.

myscript.nb myscript.nb,a=1,b=2 "myscript.nb,a=\"abc\",b=\"def\"" - =,a=1 "=,a=\"abc\""

To select interactive mode with a command prefix, a prefix directive may be entered as an option. This turns on the --prompt option described under OPTIONS below. After processing all arguments, a prompt of the form "prefix>" is displayed to stdout. Commands entered at the prompt are appended to the prefix before intepretation. This is used to direct commands to a specific node without having to type the prefix on each command line. While in interactive mode, a new prefix directive may be entered at a prompt. A prefix directive is only recognized when used as an option or in response to an interactive prompt.

-">prefix"

Arguments are processed in the order specified on the command line, enabling option changes, variable setting, and commands before, between and after file arguments. All arguments are processed within a common name space. A series of arguments are processed like lines in a script. The table of examples below shows the relationship between a command line argument and a command within a NodeBrain script.

Argument Syntax    Command Syntax    -d    set daemon;    --noDaemon    set noDaemon;    a=1    %assert ..a=1;    b="abc"    %assert ..b="abc";    c=abc    %assert ..c="abc";    :"assert a=1,b=\"hello\""    assert a=1,b="hello";    :"show -t"    show -t    myscript.nb    source myscript.nb;    myscript.nb,a=1,b=2    source myscript.nb,a=1,b=2;

-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.
-D	The --noDaemon option causes nb to not go into background mode 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 --noDaemon option.
-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.
-P	The --noPrompt option is used to turn off the --prompt option.
-q	The --query option is used to query for unknown values after processing all arguments. This option is used for diagnostic scripts.
-Q	The --noQuery option is used to turn off the --query option.
-s	The --servant option is used to enter a server mode without going into the background. With this option, NodeBrain assumes it is already a child and prepares to communicate with a parent or piped processes on stdin and stdout.
-S	The --noServant option is used to turn of the --servant option. This can be used to override a -s option coded on the hash-bang header of a NodeBrain script.

The next set of options control the behavior of NodeBrain while commands are processed and internal events are triggered. These options must be specified somewhere before the file arguments you want processed with the option.

-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.
-B	The --noBail option turns off the --bail option.
-t	The --trace option is used by developers for debugging NodeBrain internal logic. Trace messages are written while this option is on.
-T	The --noTrace option turns off the --trace option.

--logfile=file	The logfile setting specifies a file where the log is written when nb daemonizes. An alias of "--log" is recognized for compatibility with earlier version.
--outdir=dir	The outdir setting specifies a directory where output of a spawned process is stored if not directed elsewhere. An alias of "--out" is recognized for compatibility with earlier versions.
--pidfile=file	The pidfile setting specifies a file where the process identifier (PID) is to be stored when daemonizing. This can be used by init scripts (/etc/init.d).
--user=user	When running as root, the user setting causes the process user to be set after deamonizing. This setting is ignored for non-root users.
--group=group	When running as root, the group setting causes the process group to be set after deamonizing. This setting is ignored for non-root users.

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 a rule and an 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"

A full description of the NodeBrain command language is beyond the scope of this manual. See documents available online at www.nodebrain.org.

See nb.syn(5) for an introduction to command syntax.

#!/usr/bin/nb argument
... commands ...

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

$ ./myscript

instead of

$ nb argument myscript

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

~/.nb/user.nb	Commands in a user profile are processed when nb starts, before arguments are processed. It is handy for definitions a user want to be available any time nb is executed.
.nb/caboodle.nb	If a caboodle profile is found relative to the working directory, it is processed after the user profile. A caboodle is a directory designed to be the working directory for a NodeBrain application, where files are referenced with relative paths to simplify the configuration of multiple instances of an application. A caboodle profile is a convenient way for multiple agents to share definitions within an application.
*.nb	We recommend a ".nb" suffix on NodeBrain command (rule) files, although it is not required.
*.nbs	Optionally, you may want to use a ".nbs" suffix on scripts with a shebang ("#!") line. I personally prefer no suffix on files that can be executed as commands.
*.nbx	We recommend a ".nbx" suffix on NodeBrain translator rule files. This also is not required.

See nb.cfg(5) for more information on files.

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.

NB_MODULE_PATH	The NB_MODULE_PATH variable provides a platform independent way of specifying a path for locating node modules. This path overrides the native system search paths by qualifying module names so that a search is avoided. The following example illustrates a setting that directs NodeBrain to search the current directory first and then the parent directory when loading modules (plug-ins).
	NB_MODULE_PATH="./:../" nb myscript.nb

	Successful completion.
>0	An error occurred while the bail option was enabled, or a severe error terminated execution. Use the diagnostic messages to identify the specific error.

yyyy/mm/dd hh:mm:ss NB000 a 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)

Messages generated by node modules have a similar structure.

yyyy/mm/dd hh:mm:ss NM000 a module term : text

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 2000, NodeBrain was used in a second experimental application 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. The initial release was flawed in many respects and generated little interest in the Open Source community.

In April 2004, NodeBrain 0.6 was released with some of the rough edges smoothed a bit. For example, the expected GNU style "configure, make, make install" sequence was supported by the source distribution, replacing "edit this handcrafted make file for your environment". A prototype C API was included for node modules (plug-ins) to enable programmers to extend the capabilities of NodeBrain without fussing with base source code.

In early 2009, NodeBrain 0.7 was released with support for a simplified syntax. Support for some features was moved out of the interpreter and into node modules, replacing feature specific syntax with syntax common to all nodes.

In February of 2013, NodeBrain 0.8 was released, adding a message feature that enables events to be shared between agents more quickly, statistical anomaly detection, and security patches.

In August 2014, version 0.9.02 was released under an MIT license with performance enhancements to enable very large rule sets in special cases. This was followed by a December 2014 release of version 0.9.03 providing more flexibility in the order of rule definition commands.

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.

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