nb.cfg - NodeBrain Configuration Files

~/.nb/private.nb

~/.nb/nb_mod_module.nb

/etc/nb/host.nb

/etc/nb/nb_mod_module.nb

This primer should help you with basic NodeBrain configuration concepts. For a more complete understanding of individual commands you will need to study the NodeBrain User’s Guide, which you will find at http://www.nodebrain.org/nbUserGuide.pdf.

NodeBrain configuration files provide per user or system wide declarations and definitions. The syntax used in these files is the same as any *.nb file, but they focus primarily on keys and modules---the things you don’t want to define over and over in NodeBrain scripts.

When nb(1) starts it first checks for a ~/.nb/private.nb file. If this file exists, it is sourced almost as if it were the first argument. The only difference is input lines are not displayed---to avoid exposing private keys. The permissions on this file should be set to prevent access by anyone other than the owner (chmod 600, or chmod 400).

The other files listed in the SYNOPSIS above are not automatically sourced as of the 0.6.0 release. They are proposed here as a naming standard for files a user might want to source from their ~/.nb/private.nb file, or from configuration files created for specific applications.

The /etc/nb/host.nb file is proposed as a place to put definitions useful to all users on a system. For example, if you create a NodeBrain agent on a system and want to give access to potentially all users, you might declare a public key for each user in /etc/nb/host.nb with a brain declaration for the agent. If you do not want to give all users access, you should use an application specific configuration file instead.

The ~/.nb/nb_mod_module.nb files and /etc/nb/nb_mod_module.nb files are proposed for defining skills implemented by a skill module. Under release 0.6.0 you are required to explicitly source these files if needed. In a future release, we plan to have nb(1) automatically look for these files when an undefined module is referenced.

Examples of commands you will want to study for NodeBrain configuration are introduced here.

The IDENTIFY command is executed in a separate execution of nb(1) to generate an identity and add the declaration to your ~/.nb/private.nb file. This command is never used within a configuration file.

  # Create an identity (name associated with a public and private key)

  identify identity;

Once generated, the owner of an identity may copy the declaration to their ~/.nb/private.nb file for other accounts and hosts. The public key may be shared with other users to place in their ~/.nb/private.nb file as a "shared secret." We do not anticipate NodeBrain Protocol (NBP) being used in applications where the public keys are actually published. They should only be "public" within a small application community.

  # declare an identity - declare private keys in private.nb only

  declare identity identity key;

In order to communicate with a peer nb(1) process (what we call a "brain"), you must declare the brain.

  # declare a peer brain

  declare brain brain identity@host;

Use the SOURCE command to include commands from another file. This might be used to source an /etc/nb/host.nb file or a module configuration file. It is also intended for use within NodeBrain application configuration files as a way to organize rules into logical sets for maintenance and reuse.

  # source commands from another file

  source file [assertions];

The following commands might be found in an /etc/nb/nb_mod_module.nb file or a user’s ~/.nb/nb_mod_module.nb file.

  # declare a skill module - see nb_mod(7)

  declare module module file;

  # declare a skill - see nb_mod(7)

  declare skill skill module.skill[(args)][:text]

There are no NodeBrain specific environment variables.

When errors are found in configuration files, NodeBrain displays an error message. However, lines in a user’s ~/.nb/private.nb are not displayed because they are supposed to be "private." This is intended primarily to prevent keys from being unintentionally exposed in log files and on terminal displays. Because the source lines are not displayed, but the error messages are, you may have difficulty in some cases identifying the bad line. To work around this problem you can rename your ~/.nb/private.nb file and execute it under the new name.

$ cd ~/.nb
$ mv private.nb private.nb%
$ nb private.nb%      ... find the problem
$ vi private.nb%      ... resolve the problem
$ nb private.nb%      ... verify
$ mv private.nb% private.nb

See nb(1) for information on message format.

The ~/.nb/private.nb file was introduced with NodeBrain Protocol (NBP) client authentication in March, 2000.

The idea of /etc/nb/host.nb and nb_mod_module.nb was introduced with skill modules in release 0.6.0, April, 2004. This idea is expected to evolve a bit in subsequent 0.6.x releases.

There are no known bugs in the processing of configuration files. 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(1), nb.man(7), nb.syn(5), nb.mod(7), nb.lib(3)

[1] NodeBrain Home Page

[2] NodeBrain User’s Guide