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
2005/04/04	Release 0.6.1 and 0.6.2   ·          The content of chapters titled API Functions and Expert Skill Module API was moved to a new document titled NodeBrain API Reference.  The API has been revised, so there are several updates and additions to the content as well. ·          The content of sections related to cache tables and Sample Skill Modules was moved to a new document titled NodeBrain Module Reference.  New modules have been added and are covered in that document. ·           Chapter 10, Commands o      DEFINE IF, ON, and WHEN rules – action priority added o      WINDOWS command syntax – SHOWENV verb added ·          Chapter 13, Symbolic Substitution o      Cell expression substitution replaces “term substitution expressions” ·          Appendix D, Transitional Features ·          Appendix E, Release News – replaces “Software Change Summary”.

 

 

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 in response to a request, but also because it is a convenient feature for extensions that address Boeing specific requirements that are not appropriate for release to the open source project.  The API was refined a bit through May of 2005 with the 0.6.1 and 0.6.2 releases. 

 

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 š | ` ) [assertionList ] [ ; [ comment ] ] •
	assertionList	::= cellAssertion { , cellAssertion }
	cellAssertion	::= cellIdentifier ( = | == ) cellExpression | [ ! | ? ] cellIdentifier
	cellIdentifier	::= identifier | [ identifier ] ( [ cellist ] )
	cellList	::=  cellExpression  { ,  cellExpression }

 

Meta-symbols have a special meaning, except when in bold font where they represent themselves as symbol within the language.

 

          ::=     is defined as

          |        or

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

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

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

          “”       literal string – e.g. “|”, “(“, “)”, etc. (prefer bold font)

 

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

 

We are phasing out this use of meta-symbol quotes by simply using bold font to identify literals.

 

          {        Literal brace

          {        Meta-symbol

 

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 “ | boldString
	string	::=  character { character }
	boldString	String in bold font
	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;}

 

---

Copyright © 2003, 2004, 2005 The Boeing Company