Assorted reformating

[metad.git] / metad.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename metad.info
@settitle Metad -- The Daemon for controlling daemons.
@setchapternewpage off
@c %**end of header

@ifinfo

@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top Metad

@end ifinfo

@titlepage
@title METAD
@subtitle The Daemon for controlling Daemons
@author The School of Computer Science and Engineering
@author Computing Support Group
@end titlepage

@menu
* Introduction::                
* Configuration::               
* Control::                     
* Logs::                        

 --- The Detailed Node Listing ---

Introduction

* Functionality::               
* Usefulness::                  

Functionality

* Service Classes::             

Configuration

* Invocation::                  
* Config file format::          
* General options::             
* The Daemon Class::            
* The Listener Class::          
* The Stream Class::            

Config file format

* Service Name and Class::      
* Options::                     
* Program and arguments::       

General options

* Max::                         
* Dir::                        
* User::                        
* Pidfile::                     
* Watch_output::                
* Enabled::                     
* Crash::                       

The Daemon Class

* Min::                         
* Period::                      

Control

* Disabling and Enabling::      
* Killing::                     
* Starting::                    
* Listing::                     
* Reread and Restart::          
* Broadcast::                   
* metac::                       
@end menu

@node Introduction, Configuration, Top, Top
@chapter Introduction

@emph{Metad} is a program for running other programs.
Unlike the shell (which also satisfies that description), Metad runs
background system programs rather than foreground user programs.

Metad serves a purpose similar to @code{cron}, @code{inetd}, and
@code{init}, and could replace them all.
The significant enhancement metad has over these programs is that it is
easily controllable, from anywhere on the network.

@menu
* Functionality::               
* Usefulness::                  
@end menu


@node Functionality, Usefulness, Introduction, Introduction
@section Functionality

The basic function of metad is to run programs in response to certain
stimuli.
These stimuli can be time passing, other programs exiting, I/O
activity being possible on some socket, or direct request.

Metad will also, on request, send signals to any of the programs that it
has run, report on its status, and disable or re-enable any of the
services it offers. The requests are sent to metad over the network by
the @code{metac} program described below in @xref{metac}.

Metad gets a list of services that it should provide from a
configuration file (@pxref{Config file format}). This file describes,
for each service,
what program to run, how to run it, and when to run it.

The @emph{what} part is simply the name of the file containing the
program.
The @emph{how} part includes command line arguments, working directory
and user id.
The @emph{when} part is probably most interesting.

@menu
* Service Classes::             
@end menu

@node Service Classes,  , Functionality, Functionality
@subsection Service Classes
Meta understands a small number of types or @dfn{classes} or service,
each of which respond to different stimuli.
@table @code
@item daemon
The @code{daemon} is the simplest form for service
(and the only one currently implemented).
A @code{daemon} service will run its program either repeatedly,
periodically, on request, or any combination of these.
It may allow multiple instances of the program to be running at once,
and can impose an upper and lower limit on this number.

It may also be able to run its program just once (at startup) or on
completion of some other services program (not implemented yet).

@item listener
The @code{listener} class supports programs which need to listen for input on
a network port.
Metad will set up the network port and will wait for activity. When
activity is noticed, metad will run the program, passing it the network
port, so that it can do what ever is needed.
When the program exits, metad will resume waiting for more activity.

The port can be a udp/ip port or a tcp/ip port.

This is similar to the dgram/wait service of @code{inetd} and the
stream/wait service of some implementations of @code{inetd}.

@item steam
The @code{stream} class supports programs which need to respond to
network stream connections, such as @code{telnetd} or @code{fingerd}.
Metad will listen on a stream socket for a connection request.
It will then accept the connection, possibly verify the source, and then
run the program passing the the connection.

As with all metad services, it is possible to limit the number of
program instances which are running concurrently.

@end table

@node Usefulness,  , Functionality, Introduction
@section Usefulness

The main goal that metad was developed to meet, was to assist in the
development of various daemon services which needed to be run on various
machines around the network.
The sort of assistance required involved:
@itemize @bullet
@item
Restarting a daemon if it dies, possibly reporting the death.
@item
Killing a restarting a daemon when a new version is installed.
@item
Taking control of new daemons.
@item
Running some program on all machines on the network.
@end itemize

This goal lead to the @emph{daemon} class and the @emph{metac} control
program being created.
The @emph{listener} and @emph{stream} classes are later additions
brought about due to a dissatisfaction with inetd.

Say something about shortcomings?? hiding failure and not being able to
control named.

@node Configuration, Control, Introduction, Top
@chapter Configuration

@menu
* Invocation::                  
* Config file format::          
* General options::             
* The Daemon Class::            
* The Listener Class::          
* The Stream Class::            
@end menu

@node Invocation, Config file format, Configuration, Configuration
@section Invocation

Metad takes precisely two command line arguments.
The first is used as the name of the configuration file, as described
below.
The second is used as the name of the file which contains the metad
program.
This is used when metad is asked to restart itself (for instance, when a
new version has been installed).

Metad also inspects its "zeroth" argument. If this is the string
@samp{metad-restart}, then metad assumes that it has just restarted
itself and looks on @strong{stdin} for a description of the previous state
(in particular, what processes were running).


@node Config file format, General options, Invocation, Configuration
@section Config file format

The configuration file for metad simply lists the different services
that metad should monitor, one per line.
Any line that is not empty or a comment line (beginning with a hash or
number sign @samp{#}) is a service line.
Each line is broken up into words on spaces and tabs. Spaces and tabs
can be preserved in words by quoting them with single or double quotes.
Quotes and back slashes can be preserved by prefixing them with back
slashes.

The words are the services name, its class, some options, the program
name, and the programs arguments.
The program name is distinguished from options by the fact that it
starts with a slash.

@menu
* Service Name and Class::      
* Options::                     
* Program and arguments::       
@end menu

@node Service Name and Class, Options, Config file format, Config file format
@subsection Service Name and Class

The service name is any unique string of characters and is
uninterpreted.
In the future, services may be grouped based on a common prefix of the
name. This prefix would be up to a period.

The class name is one of a predefined set of classes, currently only
@samp{daemon} is supported.

@node Options, Program and arguments, Service Name and Class, Config file format
@subsection Options

The options provide details one how and when a service will run a
program.
Some options are applicable to all classes of service. These are the
General options described below (@pxref{General options}).
Others are specific to a class and are detail under the particular class
below.

Most options take the form of @samp{@var{name}=@var{value}}.

@node Program and arguments,  , Options, Config file format
@subsection Program and arguments
As mentioned, the program is the first word on the line which begins
with a slash. The full path name of the program must be given.
Subsequent words are passed to the program as an argument list. There
must always be at least one argument, which is normally the name of the program.

@node General options, The Daemon Class, Config file format, Configuration
@section General options

The General options are applicable to all classes of service. The
default value can be different with different services.
The default listed below is the default used for the @code{daemon} service.
@menu
* Max::                         
* Dir::                        
* User::                        
* Pidfile::                     
* Watch_output::                
* Enabled::                     
* Crash::                       
@end menu

@node Max, Dir, General options, General options
@subsection Max

The @dfn{max} option sets the maximum number of concurrent processes
that can be running for a particular service. The default for
@code{daemon}s is one. Format is @code{max=@var{nn}} when @var{nn} is a
decimal integer.

@node Dir, User, Max, General options
@subsection Dir

The @dfn{dir} option sets the working directory for processes run for
this service. The default is the same as metad's working directory.
A full path name should be given.

@node User, Pidfile, Dir, General options
@subsection User

The @dfn{user} option specifies an alternate userid to for processes run
for this service. Metad must be run by @strong{root} for this to work.
The default is to leave the user id unchanged from that of metad.

When setting the userid, the groups ids are also set to those for the
named user.

@node Pidfile, Watch_output, User, General options
@subsection Pidfile

Some daemon programs insist on forking and continuing to perform useful
work in the child while the parent exits. This is useful in many
circumstances, but makes it difficult for metad to continue to monitor
and control the program.
To help with this, the @dfn{pidfile} option specifies the name of a file which the program
might write the process id of the forked child.

When a process that metad has started exits, metad checks the
appropriate @var{pidfile} to see if it was written since the process
started, and if it contains the pid of an active process.
If this check succeeds, then metad assumes that the process found is
carrying one the work of the original process.

This process will then be the target of any @strong{kill} commands, and
it will be treated just as though it were the original process.

@node Watch_output, Enabled, Pidfile, General options
@subsection Watch_output

If the @dfn{watch_output} option is listed for a service, then metad
will connect the standard output and standard error streams of any
processes started for that service to a pipe.
Metad will monitor the pipe for two purposes.

@enumerate
@item
Any data received from the pipe will be logged with syslog as an
informational message about the processes.
@item
Metad will assume that the program is still active until an end-of-file
is read on the pipe --- even if the process that metad first started exits.
@end enumerate

@node Enabled, Crash, Watch_output, General options
@subsection Enabled

The @dfn{enabled} option can be used to enabled or disable a service at
startup. The value can be one of the words @samp{yes} and @samp{no}. The
default value is @samp{yes}.

@node Crash,  , Enabled, General options
@subsection Crash

The @dfn{crash} option specifies a program to run after a crash (exit
due to signal). The program is expected to clean up or report the
problem.
Currently this is unimplemented so details are scarce.

@node The Daemon Class, The Listener Class, General options, Configuration
@section The Daemon Class

The @code{daemon} class understands two more options. They are @samp{min}
and @samp{period}.
@menu
* Min::                         
* Period::                      
@end menu

@node Min, Period, The Daemon Class, The Daemon Class
@subsection Min

The @dfn{min} option specifies the minimum number of processes that
should be running for the service. If fewer than that minimum are
running, new processes will be started until the minimum is reached.

The default minimum is zero.

@node Period,  , Min, The Daemon Class
@subsection Period

The @dfn{period} option specifies how frequently a daemon service should
start a new processes. The value should be a decimal integer with a
single character suffix.
Suffixes are @samp{s} for seconds, @samp{m} for minutes, @samp{h} for
hours, or @samp{d} for days. If no suffix is given, seconds is assumed.

If this period passes without a processes being start (or attempted to
be started), metad will attempt to start a process to execute the
services program. If the maximum number of processes are already
running, the attempt will fail, but will still be recorded as an attempt
and metad will wait for the period to pass again.

@node The Listener Class, The Stream Class, The Daemon Class, Configuration
@section The Listener Class

The Listener class is not implemented yet, so details are scarce.
It is expected to need a port option (service/protocol, e.g. pop3/tcp).

@node The Stream Class,  , The Listener Class, Configuration
@section The Stream Class

The Stream class is not yet implemented, so details are not available.
It is expected to need a port option (service/protocol e.g. telnet/tcp)
and multiple access options (access+.domain access-@@netgroup
access+nnn.nnn/16)

The identity of the peer will probably be provided in the environment,
e.g. METAD_PEER=host.domain.au:port


@node Control, Logs, Configuration, Top
@chapter Control

A particularly useful feature of metad is the fact that it can be
controlled from anywhere on the network.
To achieve this, metad understands a fairly simple command protocol.
Commands can be sent either over a tcp/ip connection, in which case a
response is returned, or via a udp/ip datagram. The use of datagrams
means that a command can be broadcast to all metads on a given subnet.

As one of the commands the metad will obey is to rebroadcast a command,
commands can easily be broadcast around a medium sized internet.

@menu
* Disabling and Enabling::      
* Killing::                     
* Starting::                    
* Listing::                     
* Reread and Restart::          
* Broadcast::                   
* metac::                       
@end menu

@node Disabling and Enabling, Killing, Control, Control
@section Disabling and Enabling

Individual services can be disabled and re-enabled.

When disabled a service will not start any new processes, though it will
not attempt to stop and processes that are already running.
A disabled service that would normally listen for some specific network
activity will not listen for that activity at all.

Services are disabled be sending the command @samp{disable
@var{servicename}} and are enabled with the command @samp{enabled
@var{servicename}}.

These can be easily sent with metac using option @samp{-D @var{service}}
and @samp{-E @var{service}}.

@node Killing, Starting, Disabling and Enabling, Control
@section Killing

Killing a process involves sending a Unix signal to the process. This
does not always cause it to die.

To send a signal to all processes for a particular service, the command
is @samp{kill @var{signum} @var{service}}.
To send to a specific process, its process id must be given instead of
the servicename.

Sending signal 15 (SIGTERM) can easily be done with metac using @samp{-K
@var{service}} or @samp{-K @var{processid}}.

@node Starting, Listing, Killing, Control
@section Starting

Some classes (currently only daemon, definitely not stream, probably
listener) will start a new process on request. This request is sent with
the @samp{run} command.
Optional extra information can be sent with the run command to modify
the action of the started program. This is passed the the program
through the environment variable @emph{METAD_ARG}.
The command to run a new process is
@samp{run @var{service} @var{extra-information}}.

If no extra information is to be sent, this can be done with metac using
@samp{-r @var{service}}. To send extra information simply add @samp{-a
@var{args}}.


@node Listing, Reread and Restart, Starting, Control
@section Listing

Metad can be asked to send a report on the services it is maintaining
including the current processes which are running. The information is
returned in a binary format which is only understood by metac.
Either a single service can be listed (command @samp{list @var{service}}, option
@samp{-l @var{service}}) or all services can be listed.
(command @samp{list}, option @samp{-L}).

I should say something about the listing that is returned... later.

@node Reread and Restart, Broadcast, Listing, Control
@section Reread and Restart

The @samp{reread} command causes metad to reread its config file.
New services can be added and options, programs and arguments can be
changed. If a service has be removed from the config file, then the
service is not forgotten by metad (it might have running processes) but
it is disabled.

The @samp{restart} command causes to metad to exec a new instance of
itself, replacing the old one.
Information about what processes are running for which service is passed
through so that there will be no undue interruption of
service. Processes for services which no longer exist will be simply
forgotten.

This is useful after installing a new version of metad.

@node Broadcast, metac, Reread and Restart, Control
@section Broadcast

The @samp{broadcast} command will broadcast it arguments as a command to
all nearby metads (on the same subnet). This may cause the command to be
delivered to some metads multiple times (if they are on machines with
multiple interfaces). As most metad commands are fairly idempotent, this
is not likely to be a problem, but should be considered.

@node metac,  , Broadcast, Control
@section metac

Metac is the program to use to send commands to metad.
It takes are arguments a number of commands and a number of hosts to
send the commands to. It may be asked to broadcast the commands, or to
send them via datagrams. The default it to send them over a stream
connection.

Commands and host names may be intermixed on the command line. All
commands will still be sent to all hosts.

Commands can be given explicitly using the @samp{-C} flag, or more
briefly using one of the command flags.
The flags understood by metac are:
@table @samp
@item -u
Send (udp) datagrams, rather than making stream connection.
@item -b
Broadcast datagrams on all network interfaces.
@item -B
All commands should be sent with a @samp{broad } prefix so that the
responding metad will broadcast the command in its subnet.
@item -v
Be verbose in reporting responses --- what does this mean???
@item -C command
Send the given command as is.
@item -r service
Send a @samp{run @var{service}} command.
@item -a args
Append the @var{args} to the previous @samp{-r} command;
@item -l service
Ask for a listing of the named service.
@item -L
Ask for a listing of all services.
@item -D service
Send a @samp{disable @var{service}} command.
@item -E service
Send a @samp{enable @var{service}} command.
@item -K pid/service
Send a @samp{kill 15 @var{pid/service}} command to kill the process or
service.
@item -R
Send a @samp{reread} command.
@item -X
Send an @samp{exit} command. (but thats not documented...);.
@item -V
Display version number of metac and send request for version information
to metads.
@end table

@node Logs,  , Control, Top
@chapter Logs

@contents
@bye