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

	- o
	-- option

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; e.g. ":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\""

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    Script 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;

-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.
-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.
	The --solve option is used to solve for unknown values after processing all arguments. This option is used for diagnostic scripts.
	The --noSolve option is used to turn off the --solve option.

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.

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. You will need to study the NodeBrain User's Guide to master the concepts and syntax. You can access it online at http://www.nodebrain.org/nbUserGuide.pdf.

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

#!/usr/local/bin/nb arguments
--- NodeBrain commands ---

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

$ ./myscript

instead of

$ nb arguments 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/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 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 line translation rule files. This also is not required.

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

NB_MOD_PATH

The NB_MOD_PATH variable provides a platform independent way of specifying a path for locating NodeBrain Expert Skill 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 (plugins).

NB_MOD_PATH="./:../" nb myscript.nb

0	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)

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 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. 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 "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 skill modules (plug-ins) to enable programmers to extend the capabilities of NodeBrain without fussing with base source code.

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	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 only started to developed a test suite for exercising individual features in a structured systematic way. Regression testing is primarily 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>.

[1] NodeBrain Home Page

[2] NodeBrain User Guide

[3] NodeBrain Language Reference

[4] NodeBrain Module Reference

[5] NodeBrain API Reference