History

 

2003/02/24	Title:                 NodeBrain User’s Guide Author:                         Ed Trettevik <eat@nodebrain.org> Publisher:          The Boeing Company
	Release 0.5 ·          Released online through the NodeBrain open source project on SourceForge.net. ·          This document, like the software it describes, is a “prototype” version.  Revisions will be made in response to user feedback.
2003/03/18	Release 0.5.2 ·          Included reference to RANK command for agent configuration. ·          Reference to GRANT permission removed---not yet supported. ·          Context prefix syntax adjusted to match current program behavior. ·          Cache interval syntax included with EXPERT definition.
2003/07/24	Release 0.5.4 ·          Removed a section on an unimplemented feature for remotely reading queues. ·          Included short section (1.13) on using NodeBrain over SSH tunnels. ·          Added software change summary.
2003/10/26	Release 0.5.5   [Software not released---rolled into 0.6.0] ·          Brain declaration section explains how to specify persistent connections. ·          Calendar declaration syntax revised to match new implementation. ·          Time condition deficiency warnings removed---now fully implemented.  ·          ASSERT syntax updated to show shorthand notation for term=1 and term=0. ·          Time sequences are introduced. ·          Sequence rules are introduced.
2004/04/16	Release 0.6.0 ·          Revised syntax descriptions ·          Changed shebang line in examples to #!/usr/local/bin/nb ·          Included Chapter 6, Rules                               ·          Revised Chapter 10, Commands ·          Included Chapter 12, Source File Directives ·          Revised Chapter 13, Symbolic Substitution ·          Included Chapter 14, API Functions ·          Included Chapter 15, Expert Skill Module API ·          Revised Appendix A, Special Symbols ·          Included Appendix D, Sample Skill Modules

 

 

Preface

 

The NodeBrain language and interpreter were originally developed by The Boeing Company in 1998 for Unix and Linux system monitoring.  It started as an informal development project targeted first at non-critical lab and test systems, environments where a need for monitoring existed but where it was difficult to justify the expense of commercial monitoring products.  In this application, the NodeBrain interpreter was the decision making component of a kit that included Perl scripts for state probes and condition response actions.

 

In 2000, NodeBrain was used in a second experimental Boeing application, this time for enterprise wide security event correlation to augment the functionality of commercial intrusion detection products.  This application stretched the capabilities of NodeBrain, requiring several enhancements to handle the higher volume and poor quality of events found in intrusion detection at that time.  

 

In September of 2002, the Boeing Intellectual Property Council approved the release of NodeBrain source code to an open source project.  This decision was based on a desire to contribute to the open source community and tap into the energy of this community to evolve NodeBrain further.

 

The NodeBrain program, nb, was released as a “working prototype” (version 0.5) in February 2003 under the GNU General Public License.  NodeBrain development is now managed as an open source project on http://SourceForge.net.

 

In March 2004, a second prototype (version 0.6) was released with an Expert Skill Module API that enables programmers to extend NodeBrain functionality without modification to nb.  This was done for three reasons: 1) the open source community had shown little interest in the original prototype, 2) a plug-in feature was requested, and 3) it is convenient for extensions that address Boeing specific requirements that are not appropriate for release to the open source project. 

 

See www.nodebrain.org for more information and the latest update to this document.

 

 

 

 

Document Conventions

 

We use a modified BNF (Backus Neur Form) notation to describe the syntax of the NodeBrain language, as illustrated by the following example. 

 

Syntax:
	assertCmd	::= ( assert š | ` ) [assertion ] [ ; [ comment ] ] •
	assertion	::= assertionList | cacheAssertion  [  ,  assertionList ]
	assertionList	::= cellAssertion { , cellAssertion }
	cellAssertion	::= cellIdentifier ( = | == ) cellExpression | [ ! ] cellIdentifier
	cellIdentifier	::= identifier | identifier “(“ [ cellist ] “)”
	cacheAssertion	::= [ ! ]  “(“ [ cellist ] “)”
	cellList	::=  cellExpression  { ,  cellExpression }

 

Meta-symbols have a special meaning, except when enclosed in quotes to represent a literal symbol within the language.

 

          ::=     is defined as

          |        or

          (  )     open and close sub-expression – e.g. ( happy | sad ) day

          [  ]     open and optional expression – 0 or 1 – e.g. [ really ] happy

          {  }    open and repeating expression – 0 or more – e.g. { really } happy

          “        open and close literal string – e.g. “|”, “(“, “)”, etc.

 

We deviate from BNF in our distinction between terminal symbols and syntax rule identifiers.  Instead of enclosing syntax rule identifiers between “<” and “>”,we use a different font for identifiers and terminal symbols.

 

          expression     Italics for syntax rule identifiers

          assert             Bold font for symbols of the language (terminal symbols)

 

When we want to emphasize the importance of “white space” or an “end of line” character, we use special symbols.

 

          š                  White space identifier

          •                  End of line identifier ( LF | CR | null character)

 

Sometimes we get a bit lazy and leave rule identifiers undefined if it seems obvious, or more often because they are defined elsewhere in the document.  We also assume a terminating character does not exist within the construct it terminates.  In the following example we assume no character is a quote.

 

          “ { character } “

 

We also don’t bother to quote our literal quotes.  Bold quotes with a space on both sides are literal quotes---symbols of the language, not meta-symbols.  When quotes are used to convert a meta-symbol into a literal symbol, it is clear by the spacing and the font.

 

          “{“     Literal brace.

 

The following rules describe the syntax of our modified BNF.  

 

Syntax:
	rule	::= identifier “:=” expression
	expression	::= term { š “|” š term }
	term	::= factor [ š term ]
	factor	::= identifier | spaceIdentifier | eolIdentifier | terminal |     subExpression | optionalExpression | repeatExpression
	identifier	::=  alpha { alpha }
	alpha	::=  a-z | A-Z
	spaceIdentifier	::=  š Represents one or more space characters
	eolIdentifier	::=  • Represents end-of-line character
	terminal	::=  string | “ string “
	string	::=  character { character }
	subExpression	::= “(“ expression “)”
	optionalExpression	::=  “[“ expression “]”
	repeatExpression	::= “{“ expression “}”

 

In examples we sometimes use “…” to mean “blah blah blah” in a place that is not the focus of the example.  You must replace “…” with valid syntax if you want to experiment with the example.

 

          define r1 on(…) a=5;

          define goldenRule on(others) …; # as you would have them do onto you

 

Sometimes commands that must be coded on a single line are shown as multiple lines in an example.  This is indicated by one line ending with “ …” and the next line starting with “… ”.

 

          define r1 on((a=5 and b=7) or (c=2 and d=17)): …

          … {on(a=2);(mo,we,fr):-dir;}

Release 0.6.0 Software Change Summary

 

Bugs Fixed:

 

• FIFO listener dropping input
• Piped stdin dropping input
• Missing LF after input commands in “tee” trace file
• Time conditions firing out of order in interactive mode
• Client identity not set for FIFO listener
• Error in real number object management
• ./configure script missing in source distribution
  (automake and autoconf now used to build configure and Makefile.in)

 

New Features:

 

• EXIT command
• Persistent peer connections
• Calendar declarations
• Additional time condition operators
• Time sequences
• Sequence rules
• Expert skill module API

 

Deprecated Syntax:

 

Command options listed here are still supported by the interpreter, but have been removed from the documentation.  The interpreter generates warning messages when these options are encountered.  Modify your rules to eliminate these warnings to avoid errors under a future release when the options are dropped.

 

·         SYSTEM command – see “-“ prefix command

·         EXEC command – see “=” prefix command

·         DEFAULT command – see %DEFAULT directive

·         LET command – see %ASSERT directive

·         LOAD command – see SOURCE command

·         Context object type – see DEFINE command - expert object type

·         Context prefix without trailing period – see Chapter 10, Commands

 

Except for the last item, these changes are cosmetic.  The last item is required to avoid conflicts between NodeBrain verbs and context prefixes.  Our transition plan will be completed in a future release as shown below. 

 

Old Syntax	Release 0.5.4	Release 0.6.0	Future Release
archive;	ARCHIVE command	ARCHIVE command	ARCHIVE command
define archive context;	Hides command	Warning on “context”	Error on “context”
archive define x string “abc”;		Warning on “archive”	Error on “define”
archive;	Null command	Null command	ARCHIVE command

 

New Syntax	Release 0.5.4	Release 0.6.0	Future Release
archive;	ARCHIVE command	ARCHIVE command	ARCHIVE command
define archive expert;	Error on “expert”
archive. define x cell “abc”;	Error on “archive.”
archive;	Null command	Null command	ARCHIVE command

 

 

Incompatibilities:

 

We want to avoid disruptive changes normally, but with very few people using prototype versions we will sometimes introduce a change that requires modification to existing rules without first providing warnings.  Hopefully this will not be too great an inconvenience, particularly when changing seldom used features.  Our goal is to have a solid design by version 1.0, so when a two step change seems inappropriate, we will make a disruptive change in one step.  This is the case with the changes listed here.

 

·         The “unknown” value is now represented by “??” instead of “?”.  Commands using “?” for unknown values will now produce an error message and fail.

·         The “unknown” operator has changed from “??” to “?”.  This prefix operator is in recognized in assertions as well as conditions.

 

Old 0.5.4 Syntax	New 0.6.0 Syntax
define a cell ?;   # accepted define a cell;     # preferred	define a cell ??;  # accepted define a cell;      # preferred
assert a=?;	assert a=??;    # accepted assert ?a;        # preferred
define r1 on(a=?)	define r1 on(a=??);  # accepted This has no value accept for testing because the condition a=?? is always unknown—same as on(??).
define r1 on(??a)	define r1 on(?a);

 

 

 

New Syntax

 

·         A connection persistence interval (in seconds) may be specified when declaring a peer brain. 

    declare term brain identity@host:port[{persistence_interval}][(queue)];

When this option is specified under release 0.6.0, an established connection is maintained until one of the peers terminates.  In a future release, connections will be dropped after the specified interval of inactivity.

---

Copyright Ó 2003, 2004 The Boeing Company
Permission granted for use of content under terms of the GNU Free Documentation License.