/***************************************************************************** 
  Copyright(C) 1996, 1997 Network Flight Recorder, Inc.
  All rights reserved.

  Use and distribution of this software and its source code
  are governed by the terms and conditions of the
  Network Flight Recorder Software License ("LICENSE.TXT") 

  File:   README
  Author: Kent Landfield <kent@nfr.net>
 
 *****************************************************************************/ 
                              NFRWATCH

NFRWATCH is used to start up the NFR programs and services.  Normally,
nfrwatch is started as root from an rc.* file. It creates a runtime
environment that monitors required NFR processes to assure they are
running.

When nfrwatch is executed it reads the configuration file the admin specified 
on the command line.  Multiple NFRs can be started by calling nfrwatch
with different config files which point to different NFR directory
structures.  

There are two sections in the config file, one part for environment variables
and the other part for command entries describing the processes nfrwatch is
to deal with.

--------------------
Environment Section:
--------------------

There are two required variables in the Environment section, 

   NFRHOME - Root directory of the nfr execution environment. 
   NFRUSER - Set this to the account name of the user that NFR should
             run as. This needs to match the ownership of the files in
             the nfr runtime directory.

You will need to set these to the appropriate place prior to calling nfrwatch.
You can set other environment variables but they are optional.

SHELL, IFS, HOME, LOGNAME, USER, NFRUID and NFRGID are set in nfrwatch and 
are not changeable in the configuration file.  

    HOME is set to NFRHOME
    LOGNAME and USER are set to NFRUSER
    NFRUID and NFRGID are set to the numeric uid and gid intern

----------------
Command Entries:
----------------

The format of a command entry is as follows.

+Program : Start Command : Priv : Nice : Respawn: Pidfile : Termination Command

Field definitions:

 +Program       - meta name of the subsystem. This must begin with a '+'.
                  The '+' is used to indicate that this is a command entry.

  Start Command - actual command line to execute.

  Priv          - Execute with root privilege or not (Y/N)
                  If 'Y' is specified then the process will be started with
                  root access.
                  If 'N' is specified then the process will be started as
                  the specified NFRUSER.

  Nice          - Nice value to execute with (0-39)

  Respawn       - Does this process need to be respawned on termination. 
                  If this is a process that needs to be restarted in the
                  event of a failure, put an 'R' in the Respawn field.

  Pidfile       - Location of pidfile (relative to nfrhome or absolute)

  Termination Command - Means to terminate the process. 
                  You can specify to have one of the supported signals be 
                  sent to the process or you can specify a command line 
                  to be executed that's purpose is to notify the process 
                  that it is time to shutdown.

                  Supported Termination Signals
                     SIGHUP       1    Hangup 
                     SIGINT       2    Interrupt 
                     SIGKILL      9    Killed
                     SIGTERM      15   Terminated 
                     SIGUSR1      16   User Signal 1 
                     SIGUSR2      17   User Signal 2 

-------------
General Flow:
-------------

When the nfrwatch program is initiated, it reads the config file and 
determines the User ID to use to initiate its configured services.
It expands configuration variables used in the file. Be sure to list
them in the file if you wish to use them to expand another variable or
command line.  After reading the configuration file and expanding any 
variables used it constructs the environment to be used to execute the 
listed processes.

It the changes directory to the directory specified in NFRHOME, checks
to assure it is the only version running in this directory and begins
starting the listed processes.

When executing the individual processes it determines if privilege is
needed. If not it then sets the UID/GID to the listed NFR account.
file. If a nice value is lists it executes the process at the listed
nice value.  Currently alertd, spacemand, nfrd and the webserver are 
configured to be initiated.

If the process executed is a direct descendent (in other words it does not
fork and exec itself as a server process might) then when the process 
terminates and the respawn flag indicates a "Respawn" is needed then the 
start command is re-executed.  If the process is not a direct child (as
in a grandchild or great grandchild) then on a configurable time interval 
(default 1 minute), nfrwatch loops checking the pid files listed to assure 
the the process are still active and restarts any process that has terminated
and is configured to be restarted.

If a termination command is received (SIGTERM) then nfrwatch executes the 
Termination commands associated with the process in the config file.  In 
some cases that will require nfrwatch to send a signal to the process and 
in other cases that might require executing a command (such as 
"bin/ctlnfrd halt").

------------------------
Changing Configuration:
------------------------

This should not have to be done as it comes properly configured but it
can be added to by editing the configuration file you wish to use.

You will need to assure that the two variables NFRUSER and NFRHOME are
correct.

Use the -c option to check the configuration file.  It will tell you
if there are errors. Otherwise it will print out the information in
the configuration file.  For example:

        # nfrwatch -c testnfr.conf

------------------------------
Starting and Stopping nfrwatch
------------------------------

Nfrwatch is started via your systems /etc/rc* mechanisms.  Add an entry
to the appropriate file to assure nfrwatch is executed when the system 
boots.  

It can also be run manually using the command line options below. 

In order to properly shutdown nfrwatch, you should send it a SIGTERM
signal. This can be done manually with the kill(1) command.  Normally
your system will send a SIGTERM to executing daemon processes during
system shutdown.

------------------------------
Command line options:
------------------------------

The program 'nfrwatch' is used to start and stop the NFR software and to 
restart any programs that are terminated early.

Syntax:

      nfrwatch [-cdv] [-t seconds] configuration-file

Options:

    -c  
        Checks the syntax of the environment variables and command entries 
        in the configuration file. If errors are encountered, the errors are 
        printed out. If no errors are found then nfrwatch prints the Execution 
        Environment variables and the Command Entries and nfrwatch terminates.

    -d  
        Turns on debugging.  This is useful when making substantial changes
        to the nfr.conf or creating a new configuration file. Debugging prints
        out a great deal of information about what nfrwatch has it is tables
        and what it is doing. All output is printed to stderr.
	  
    -v
        Turns on verbose output.  The program execution environment and
        command entries are printed to stderr.
          
    -t seconds 
        Specifies the amount of time, in seconds, that nfrwatch waits 
        before checking to assure the NFR programs are still executing.
        The default period before rechecking is 60 seconds.

 configuration-file 
     Specifies the file that contains configuration information for nfrwatch.        Use absolute or relative paths. A configuration file must be specified
     when starting nfrwatch. 

-----------------
Testing nfrwatch:
-----------------

The file testnfr.conf can be used in conjunction with the test programs
chldprog and svrprog to test nfrwatch if you are porting it to another
platform. The source for both of these programs is the file testprog.c.
Make sure that you set the NFRHOME and NFRUSER variables according to
your local needs before testing.  

    chldprog - does not do subsequent forks and execs and remains
               a direct descendent of nfrwatch
    svrprog  - acts as a server process normally does and forks off a
               subsequent child process to do the work while the initial
               parent process is terminated
               
to start testing nfrwatch

        # nfrwatch -d -v testnfr.conf

Note: nfrwatch tries to create pid files in the etc/run directory. 
      Make sure this directory exists.

