Alive Daemon for the APS Alive System


Installation Notes
------------------

All the code is C, and requires no external libraries.  It build with
gcc and make.

Before building, some defaults need to be changed in the top-level
Makefile.  The first set of defaults are the standard installation
directories, typically modified by changing the "prefix" value; if you
don't plan to use "make" to install the files, you can ignore
this. The other default, "Cfg_File" specifies the default location for
the system configuration file, needed by alived and its direct tools;
this is built into the programs.

Install the configuration file alived_config.txt (from the init
directory) into the location specified by "Cfg_File", as it holds
parameters that are used by the server alived and its associated
tools.  It specifies what ports to use, the number of missing
heartbeats that is called a failure, how often to check for failed
IOCs, and the locations of files and directories.  Make sure any
specified directory paths exist, as the daemon won't make them.

Run "make" in the top-level directory, and you have four executables.
- alived is the alive server, and typically runs as a daemon
- alivectl is a tool program for controlling the daemon
- event_dump is a auxiliary tool program that dumps the binary event
  files for an IOC 

If you want to have make install the executables, then run "make
install".  The account running this must be able to install into the
locations specified in the Makefile.  To remove them, similarly run
"make uninstall".


Usage Notes
-----------

To start the daemon, you can just run "alived" or run it with a
configuration file. Here's the help:

alived [-h|-t] [configuration_file]
   -h for this help
   -t means run in terminal, not as a daemon


The control program "alivectl" can only be run on the computer with
the daemon (as a security measure), and it uses an IPC socket.  It is
not meant for use by normal users.  Here's the help:

alivectl (-v|-q|-p|-s|-c|-l|-e|-i <ioc>|-d <ioc>|-a <prefix>) [<socket>]
  The socket can be specified, else a default value will be used.
    -v  prints the version of the alive daemon and tools
    -q  stops current alived
    -p  pings the daemon to make sure it is running
    -s  prints current status
    -c  prints configuration information
    -l  prints list of IOCs
    -e  prints list of event subscription clients
    -i  prints information about IOC
    -d  deletes ioc specified from database
    -a  archives the database into CSV files, using prefix for file names
    
When you want to stop the daemon, run "alivectl -q".

At this point, have some alive records point to the server's IP
address using the RHOST field.  You can then see if they are showing
up with "alivectl -l".  Then you can look at them with "-i" by also
giving the IOCs name.

The log file specified by "log_file" is the (partially utilized) error
log file. The "event_file" file is a log of all events that occur
(BOOT, FAIL, MESSAGE, CONFLICT_START, CONFLICT_STOP, RECOVER). The
"info_file" file is a log of all the environment variables retrieved
from IOCs at the time it happens.  The "control_socket" IPC socket
allows the control program to talk to the daemon.  The "event_dir"
directory holds the binary event log for each IOC.  The "state_dir"
directory holds the binary IOC state (needed at restart of the daemon)
for each IOC.

The events should be self explanatory: BOOT is when an IOC appears
with a new incarnation value, FAIL is when a time allowing for a
certain number of heartbeat expires (so the IOC is assumed down),
RECOVER is when an IOC shows up after failing (like when the network
had a temporary problem), CONFLICT_START is when multiple IOCs with
the same name show up, CONFLICT_STOP is when the conflict stops, and
MESSAGE is when the value in the .MSG field of the alive record is
changed.


Clients
-------

The daemon has a network client API library and a default client,
alivedb, which are included in a different package.  They can be
built and installed without installing the daemon.