Sella NMS v1.0.0 (01/19/05) - http://www.digitalgenesis.com

Documentation Notes:

The documentation provided here is only a basic overview. The configuration
files sella_nms.conf, policy-statements.conf, format-statements.conf and
map-statements.conf all provide comments that explain many of the configuration
options.

Detailed documentation is available at:

  http://www.digitalgenesis.com/software/sella_nms/manual

NOTE: At the time of release, the online documentation is not complete.

Additional information and install help can be found within our forums:

  http://build.digitalgenesis.com/support/forum


Quick Install:

  0. Untar the distribution within a temp directory. It will create a sella_nms-1.0.0
     directory. Several examples follow:

     For .tar.gz files:
       tar xvzf sella_nms-1.0.0.tar.gz
        -or-
       zcat sella_nms-1.0.0.tar.gz | tar xvf -

     For .tar.bz2 files:
       tar xvIf sella_nms-1.0.0.tar.bz2
        -or-
       tar xvf sella_nms-1.0.0.tar.bz2 --with-compress-program=bzip2
        -or-
       bzcat sella_nms-1.0.0.tar.bz2 | tar xvf -

  1. Run './configure' in the sella_nms directory (you may need extra flags).

     cd sella_nms-1.0.0

     ./configure

  2. Run 'make all', then 'make install' as root.

     make all
     su -c 'make install'

  3. Setup sella_nms MySQL database. (Assuming database name of 'sella_nms'.)

     mysql -u root -p sella_nms < docs/sella_nms-mysql.sql

  4. Create a Sella NMS user within MySQL. Connect as root to MySQL.

     mysql -u root -p mysql

     Then issue the GRANT command for MySQL 4.x:

     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,LOCK TABLES,CREATE TEMPORARY TABLES,
            CREATE,DROP ON sella_nms.* TO user@localhost IDENTIFIED BY 'passwd';

     Or, for MySQL 3.23.x:

     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON sella_nms.*
            TO user@localhost IDENTIFIED BY 'passwd';

  5. Open and edit sella_nms.conf. Configure as needed. Most options
     are described to the right of the option.

     vi /usr/local/sella_nms/etc/sella_nms.conf
     -or-
     emacs /usr/local/sella_nms/etc/sella_nms.conf

     The options that *must* be changed are the 'prefix' section within
     'discovery icmp' and the 'storage' section within 'system global'. The
     sella_nms.conf file is described in more detail later in this file.

  6. Start up the Sella NMS daemon.

     cd /usr/local/sella_nms/sbin
     ./sella_nms

     The servers log file (usually /var/log/messages) will contain output from
     the daemon. Optionally, the daemon can be started in the foreground for easier
     access to log messages, as show below:

     ./sella_nms -f

  7. Edit config.php in the html directory. Setting the database options as needed.

     cd /usr/local/sella_nms/html
     vi config.php
     -or-
     emacs config.php

  8. Configure web server to serve up Sella NMS Web GUI.

     For Apache, set your 'DocumentRoot' and 'DirectoryIndex' within your
     httpd.conf as follows:

     DocumentRoot "/usr/local/sella_nms/html"
     DirectoryIndex index.php index.html

     This configuration assumes that you have Apache working with PHP already, and
     are only using this web server for Sella NMS. Optionally, you could symlink
     '/usr/local/sella_nms/html' to your 'htdocs' directory or setup a virtual
     server.

  9. Test by viewing the Web GUI in your browser.

     It may take several minutes for the Web GUI to begin displaying content. The
     sella_nms daemon needs to discover your network and begin monitoring it.


Configuration:

  This section covers the configuration options and how they work:

  Configuration Files
  -------------------

    sella_nms.conf - Main configuration file.

      Contains system and module specific configuration options. Most
      configuration is done within this file.

    policy-statements.conf - Policy configuration file.

      Contains policy-statements that can be used on modules to adjust
      their functionality and interwith the system.

    format-statements.conf - Format configuration file.

      Contains format-statements which are applied to a policy. Formats
      specify allowed variables, values and actions the policy can use.

    map-statements.conf - Map configuration file.

      Contains map-statements which are applied to a policy or format.
      Maps are used to correlate the database to data used within a policy.


  Configuration Style Overview
  ----------------------------

    The basic style of the config file follows a 'key value' pair, or a
    'key block' pair. All 'key value' pairs are terminated by a semicolon
    as shown below:

      timeout 1000;

    All 'key block' pairs are a keyword followed by a { } block or a [ ] block.
    The block may contain a series of 'key value', 'key block' or values.
    Below is an example:

      icmp {
        enabled;
        timeout 1000;
        prefix {
          10.0.0.0/24;
        }
        policy {
           output[ EXAMPLE_POLICY ];
        }
      }

    The configuration files support nesting up to a depth of 255. The limit can
    be altered by editing FLATFILE_MAXDEPTH within flatfile.h and recompiling.

    Bash, C, C++/Java and SQL comment styles are supported within the
    any of the configuration files.

    Below is an example of a bash style comment:

    icmp {
      # disable;
      options [ non-blocking ];
      load /usr/local/sella_nms/libexec/monitor/libicmp.so.0;
    }
    
    Below is an example of a multiline C style comment:

    icmp {
      /*
        disable;
        options [ non-blocking ];
      */
      load /usr/local/sella_nms/libexec/monitor/libicmp.so.0;
    }
    
    Below is an example of a C++/Java comment:

    icmp {
      // disable;
      options [ non-blocking ];
      load /usr/local/sella_nms/libexec/monitor/libicmp.so.0;
    }
    
    Below is an example of an SQL comment:

    icmp {
      -- disable;
      load /usr/local/sella_nms/libexec/monitor/libicmp.so.0;
      options [ non-blocking ];
    }

    Includes and nested includes are supported within the configuration files.
    Below is an example of a file include:

      #include "/usr/local/sella_nms/etc/policy-statements.conf"

    Configuration merging is supported. If the configuration includes two blocks
    at the same depth, they will be merged as the configuration is parsed.

    If the configuration was defined as show below:

    output {
       log {
         trace-options [ debug thread ];
       }
    }

    output {
       log {
         trace-options config;
         policy {
           output [ UPDATE_LOG ];
         }
       }
    }

    The configuration would merge and would be interpreted by Sella NMS as if
    it were the following configuration:

    output {
       log {
         trace-options [ debug thread config ];
         policy {
           output [ UPDATE_LOG ];
         }
       }
    }

    The configuration will be merged even if they are within seperate include
    files.


  Configuration Syntax
  --------------------

   <module-name> {
      <key> <value>;
      policy {
         input [ <policy-name> ... ];
         output [ <policy-name> ... ];
      }
      trace-options [ (all | developer | debug | config | sql | policy-sql | policy | policy-in | policy-out | thread | timer | internal) ];
      <sub-module-name> {
         <key> <value>;
         policy {
            input [ <policy-name> ... ];
            output [ <policy-name> ... ];
         }
         trace-options [ (all | developer | debug | config | sql | policy-sql | policy | policy-in | policy-out | thread | timer | internal) ];
      } 
   }

   system {
      process {
         nice <-20 to 19>;
         pidfile <filename>;
         statfile <filename>;
         core-dump <size in megs>;
      }
      security {
         user <username>;
         group <group>;
         umask <umask-value>;
         chroot <directory>;
      }
      syslog {
         faciliy <level>;
         severity <severity>;
      }
      snmp-mibs {
         <mib-directory>;
      }
      global {
         storage {
            <description> {
               debug;
               driver   (mysql | pgsql);
               server   <hostname>;
               port     <port number>;
               database <database-name>;
               username <username>;
               password <password>;
               compression;
            }
         }
      }
      modules {
         load <filename>;
         <module-name> {
            disable;
            load <filename>;
            options [ (blocks | non-blocking) (resident | non-resident) (thread | process) ];
            order <0-2147483647>;
            schedule {
               startup;
               delay <seconds>;
               cron <crontab format>;
               second (# | #-# | #,# | */#);
               minute (# | #-# | #,# | */#);
               hour (# | #-# | #,# | */#);
               dayofmonth (# | #-# | #,# | */#);
               month (# | #-# | #,# | */#);
               dayofweek (# | #-# | #,# | */#);
            }
            <sub-module-name> {
               disable;
               load <module>;
               options [ (blocks | non-blocking) (resident | non-resident) (thread | process) ];
               order <0-2147483647>;
               schedule {
                  startup;
                  delay <seconds>;
                  cron <crontab format>;
                  second (# | #-# | #,# | */#);
                  minute (# | #-# | #,# | */#);
                  hour (# | #-# | #,# | */#);
                  dayofmonth (# | #-# | #,# | */#);
                  month (# | #-# | #,# | */#);
                  dayofweek (# | #-# | #,# | */#);
               }
            }
         }
      }
   }

   policy-options {
      policy-statement <policy-name> {
         term <term-name> {
            from {
               <variable> <value>;
            }
            then {
               apply-map <map-name>;
               set {
                  <variable> <value>;
               }
               output {
                  <output-module-name> {
                     <variable> <value>;
                     status <string/variable>
                     brief <string/variable>;
                     detail <string/variable>;
                     channel <channel-name>;
                  }
               }
               (accept | reject | next-term | next-policy);
               apply-format <format-name>
            }
         }
      }

      format-statement <format-name> {
         term <term-name> {
            from {
                variable <variable-name> {
                   required (yes | no);
                   apply-map <map-name>;

                   type [ prefix string integer regex ];
                   function (equal-to | not-equal | at-least | at-most | less-than | more-than);
                }
                group <group-name> {
                   required (yes | no);
                   apply-map <map-name>;

                   type [ prefix string integer regex ];
                   function (equal-to | not-equal | at-least | at-most | less-than | more-than);
                   variable <variable-name>;

                   group <sub-group-name> {
                      required (yes | no);
                      apply-map <map-name>;

                      type [ prefix string integer regex ];
                      function (equal-to | not-equal | at-least | at-most | less-than | more-than);
                      variable <variable-name>;
                   }
                }
            }
            then {
               set {
                  varible <variable-name> {
                     value [ <value> ... ];
                  }
               }
               action {
                  default (accept | reject | next-term | next-policy);

                  values [ accept reject next-term next-policy ];
               }
            }
         }
      }

      map-statement <map-name> {
         term <term-name> {
            from {
               query <string>;
            }
            then {
               set {
                  <variable> <value>;
               }
            }
         }
      }
   }


  Sella NMS Module Scheduler
  --------------------------

    The Sella NMS scheduler is controlled by utilizing the 'order', 'blocking',
    'non-blocking', 'startup', 'delay', 'schedule', 'thread' and process'
    directives. Modules may have nested sub-modules which follow their own
    scheduler.

    The 'order' directive specifies when a module should be started in relation
    to other modules. A higher ordered module will not be able to start until
    all 'blocking' lower ordered modules have completed and all 'non-blocking'
    lower ordered modules have started.

    The 'schedule' directive specifies the time or interval at which a module
    should run. The time or interval does not start until all 'blocking' lower
    ordered modules have completed. When 'schedule' is combined with
    'non-blocking' (default for schedule) the module will repeatedly start at
    the specified interval. If 'schedule' is combined with 'blocking', it will
    run only once. The 'schedule' directive uses a modified subset of Vixie Cron
    notation, allowing accuracy down to the second. 

    The 'delay' directive will cause a module to wait for a number of seconds
    before starting up. The delay will begin from the time that the module would
    have normally started. The 'delay' directive can be combined with the
    'schedule' directive, but is only applied on the first iteration.

    The 'startup' directive will cause a module to ignore its 'schedule' on its
    first run (within its parents scope). The 'delay' directive can be combined
    with 'startup'.

    The 'thread' or 'process' directive will cause the module to run as a thread
    or a process. Currently this option is ignored and defaults to thraed.


  Sella NMS Core Directives
  -------------------------

  This section covers directives that are part of the Sella NMS daemon itself.

    system - Specifies options to the Sella NMS daemon, including which modules
             to run.

      Hierarchy: top
      Syntax: system { ... }
      Default: n/a
      Required: yes
      Module: core
      Compatibility: Since v0.3.0.

    modules - Specifies the modules that Sella NMS will run.

      Hierarchy: system
      Syntax: modules { ... }
      Default: n/a
      Required: yes
      Module: core
      Compatibility: Since v0.1.0.

    disable - Disabled module and its children.

      Hierarchy: system module <module-name>
      Syntax: disable
      Default: n/a
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    load - Specifies a DSO (module) for a module to load and run.

      Hierarchy: system module <module-name>
      Syntax: load <filename>
      Default: n/a
      Required: yes
      Module: core
      Compatibility: Since v0.1.0.

    order - Specifies the order in which the module should be scheduled to run,
            relative to other modules. Lower ordered modules are run before
            higher order modules.

      Hierarchy: system module <module-name>
      Syntax: disable
      Default: n/a
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    options - Specifies module options.

      Hierarchy: system module <module-name>
      Syntax: options { ... }
      Default: n/a
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    blocking - Specifies if the module should block modules from a higher order
               from running.

      Hierarchy: system module <module-name> options
      Syntax: blocking
      Default: blocking
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    non-blocking - Specifies if the module should not block modules from a
                   higher order from running.

      Hierarchy: system module <module-name> options
      Syntax: non-blocking
      Default: blocking
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    resident - Specifies if the module's library should stay resident when not
               scheduled to be running, resulting in less system library calls.
               Only applies to non-blocking modules.

      Hierarchy: system module <module-name> options
      Syntax: resident
      Default: non-resident
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    non-resident - Specifies if the module should be unloaded when not scheduled
                   to be running.

      Hierarchy: system module <module-name> options
      Syntax: non-resident
      Default: non-resident
      Required: no
      Module: core
      Compatibility: Since v0.3.0.

    thread - Specifies that the module should run as a child thread of its
             parent.

      Hierarchy: system module <module-name> options
      Syntax: thread
      Default: thread
      Required: no
      Module: core
      Compatibility: Future

    process - Specifies that the module should run as a process owned by its
             parent.

      Hierarchy: system module <module-name> options
      Syntax: process
      Default: thread
      Required: no
      Module: core
      Compatibility: Future

    schedule - Specifies various intervals at which a module should run, in a
               modified crontab-style format.

      Hierarchy: system module <module-name>
      Syntax: option { ... }
      Default: n/a
      Required: no
      Module: core
      Compatibility: Since v0.3.0.
      Notes:

        Specifying a schedule implies the module option 'non-blocking', unless
        'blocking' is specified. 

        Schedule supports a subset of Vixie Cron notations for fields. Supported
        notations include ranges (5-10), lists (1,3,5,7), and steps (*/5).

        Below are the allowed values for each field.

        field       allowed values
        -----       --------------
        second      0-59
        minute      0-59
        hour        0-23
        dayofmonth  1-31
        month       1-12
        dayofweek   0-7 (0 or 7 is Sun)

    global - Specifies configuration that is available to all modules that
             Sella NMS will run.

      Hierarchy: system
      Syntax: global { ... }
      Default: n/a
      Required: yes
      Module: core
      Compatibility: Since v0.3.0.

    storage - Specifies storage configuration that is available to all
              modules that Sella NMS will run.

      Hierarchy: system global
      Syntax: storage <description> { ... }
      Default: n/a
      Required: yes
      Module: core
      Compatibility: Since v0.3.0.

    type - Specifies the database type to use. This directly triggers libdbi's
           database plugins. The default is MySQL.

      Syntax:  type (mysql | pgsql)
      Context: system global storage <description> { ... }
      Default: mysql
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.

    server - Specifies the IP address or hostname of the database server. If
             this is set to 'localhost', then the client library will use the
             default file socket for access (usually /tmp/mysql.socket).

      Syntax:  server <IP or hostname>
      Context: system global storage <description> { ... }
      Default: localhost
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.

    socket - Specifies the database socket to use, rather than using TCP/IP.

      Syntax:  socket <filename>
      Context: system global storage <description> { ... }
      Default: /tmp/mysql.socket
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.


    port - Specifies the TCP port to use when accessing the database.

      Syntax:  port <integer>
      Context: system global storage <description> { ... }
      Default: 3306
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.

    database - Specifies the database to utilize.

      Syntax:  database <string>
      Context: system global storage <description> { ... }
      Default: sella_nms
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.


    username - Specifies the MySQL username when connecting to the database.

      Syntax:  username <string>
      Context: system global storage <description> { ... }
      Default: sella_nms
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.


    password - Specifies the MySQL password when connecting to the database.

      Syntax:  password <string>
      Context: system global storage <description> { ... }
      Default: empty string/no password
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.

    compression - Specifies that data should be compressed on connections 
                  to the database. This will cause additional overhead when 
                  communicating with the database, but could give a speed
                  benefit if you are reading or writing to a database over a
                  low speed Internet connection. Not Recommended.

      Syntax:  compression
      Context: system global storage <description> { ... }
      Default: disabled
      Required: no
      Module: core (libstorage.so)
      Compatibility: Since v0.3.0.


  Sella NMS Module Directives
  ---------------------------
  
    discovery - Specifies options to the discovery daemon.

      Syntax: discovery { ... }
      Context: root, module
      Default: n/a
      Required: yes
      Module: libdiscovery.so
      Compatibility: Since v0.1.0.

    monitor - Specifies options to the monitor daemon.

      Syntax: discovery { ... }
      Context: root, module
      Default: n/a
      Required: yes
      Module: libmonitor.so
      Compatibility: Since v0.3.0.

    output - Specifies options to the output module.

      Syntax: output { ... }
      Context: module
      Default: n/a
      Required: yes
      Module: liboutput.so
      Compatibility: Since v0.3.0.

    icmp - Specifies options to specific to the icmp module.

      Syntax: icmp { ... }
      Context: discovery, module discovery
      Default: n/a
      Required: no
      Module: libicmp.so (discovery)
      Compatibility: Since v0.1.0.

    snmp - Specifies options to specific to the snmp module.

      Syntax: snmp { ... }
      Context: discovery, module discovery
      Default: n/a
      Required: no
      Module: libsnmp.so (discovery)
      Compatibility: Since v0.2.0.

    topology - Specifies options to specific to the topology module.

      Syntax: topology { ... }
      Context: discovery, module discovery
      Default: n/a
      Required: no
      Module: libtopology.so (discovery)
      Compatibility: Since v0.2.0.

    interface - Specifies the interface to send packets from.

      Syntax:  interface <name>
      Context: <daemon-name> icmp
      Default: System Default
      Required: no
      Module: libicmp.so (discovery), libicmp.so (monitor)
      Compatibility: Since v0.2.0.

    send - Specifies the number of packets to send to each IP.

      Syntax:  transmit <number>
      Context: <daemon-name> <module-name>
      Default: 3
      Required: no
      Module: libicmp.so (discovery)
      Compatibility: Since v0.1.0.

    require - Specifies the number of packets required to return from an active device.

      Syntax:  require <number>
      Context: <daemon-name> <module-name>
      Default: 1
      Required: no
      Module: libicmp.so (discovery)
      Compatibility: Since v0.1.0.

    timeout - Specifies the timeout between retrys in milliseconds. Longer
              timeout settings will make a discovery take longer, but will
              allow loaded devices more time to answer.

      Syntax:  timeout <milliseconds>
      Context: deamon_name <module-name>
      Default: 2000
      Required: no
      Module: libicmp.so (discovery), libsnmp.so (discovery)
      Compatibility: Since v0.1.0.

    threads - Specifies the number of threads to use for this module.

      Syntax: threads <number>
      Context: <daemon-name> <module-name>
      Default: 16
      Required: no
      Module: libsnmp.so (discovery)
      Compatibility: Since v0.2.0.

    retry - Specifies the number of times to retry a device, after the first attempt
            to connect has failed.

      Syntax:  require <number>
      Context: <daemon-name> <module-name>
      Default: 2
      Required: no
      Module: libsnmp.so (discovery)
      Compatibility: Since v0.2.0.

    prefix - Specifies the prefix(es) to scan for active devices. Supports CIDR
             notation.

      Syntax:  netblock <netblock | { ... }>
      Context: <daemon-name> <module-name>
      Default: n/a
      Required: no
      Module: libicmp.so (discovery), libsnmp.so (discovery)
      Compatibility: Since v0.3.0.

    oid - Specifies the oids that should be collected from a device. Supports both
          numbered OIDs and named OIDs.

      Syntax:  oid <oid_name | { ... }>
      Context: <daemon-name> <module-name>
      Default: n/a
      Required: no
      Module: libsnmp.so (discovery)
      Compatibility: Since v0.2.0.


Fini
