Contents:

A) Usage overview

B) "man" pages # to be written


A) Usage overview
=================

This should get most people started, and for experienced users, this
would probably be sufficient.

I will use two examples, qmail and dnscache, since most mail servers
will use both (though many of them would use tinydns or friends).

As explained in the README, the dt-run package sets up a fairly
complete sysV init scheme independent from the one provided by the
traditional `rc' scripts and start/stop sequencing scheme.  

The services and their logs are managed by supervises that run under
svscan's tender loving care. `svscan' itself is supervised for easier
control. 

Runlevel changes are managed by a "runlevel changer" script,
dt-runlevel.init.  This script uses the scripts of the  runlevelconf
package to decide which services to start/stop at the current
runlevel. 

svscan
******

`svscan' service directory is /service, the directory containing links
to services to run under svscan controlled supervises.

`svscan' is normally started by init according to the entries you put
in /etc/inittab.  You can also start it by hand, as

/var/service/dt-run/dt-svscan.init start

This will start a supervised svscan with supervise directory
/var/service/svscan, so you can check svscan's status with

svstat /var/service/svscan

It is *not* safe to start svscan with

svscan /service &

since svscan does not check if another svscan is already running in
/service.

You can do

/var/service/dt-run/dt-svscan.init stop

to stop svscan; this will also stop all the supervises *and* the
services and service logs running under svscan's control.  I would use
this command only in emergency situations.  Avoid using

svc -d /var/service/svscan

unless you know what you are doing.

Setting up and managing services
********************************

A service is set up using add-service.sh, and many services can be set
up at once.  For example, 

add-service.sh qmail rblsmtpd dnscache 

This sets up the services according to the config file
/var/service/dt-run/dt-list.  In the config file dt-list, you can
specify what runlevels a service should run at, and what services the
given service depends on for startup.

If svscan is running, the above add-service.sh command will also start
those services that should be run at the current runlevel.  For those
services which should not run at the current runlevel, only the
supervises will be started.

Once a service is set up with add-service.sh, it can be managed by svc
in the directory 

/service/`service'

For example,

svc -t /service/rblsmtpd

Note that doing

svc -x /service/rblsmtpd

does not do what you expect, since the supervise will be restarted by
svscan. 

For compatibility, and for convenience, you can use the script
`service'.init to manage a service.  For example, 

qmail.init stop

will not only stop qmail, but its log as well (not the supervises,
though!).  In case you have to wait for qmail to stop, you will get
messages of the form

	 11s passed while waiting for qmail to stop

Once the service stopped, you get a nice green [OK]---or red [FAILED]
if the service for some reason could not stop. 

The command `service.init stop' will give a [FAILED], if the service
does not stop in 120 seconds.  If you did not do this at the time of
the installation, this 120 seconds is configurable by setting MAX_STOP
in the file

/var/service/dt-run/dt-config

You can similarly start `service' with

`service'.init start

Run

`service'.init help

to see all the stuff you can do with `service.init'.


Removing services
*****************

If you do not want to run a service anymore, you can remove it with
remove-service.sh.  For example

remove-service.sh qmail dnsache

This command 

* stops the services and their logs.  Each service is given 120
  seconds to stop; if it is not enough, the service gets killed with
  `svc -k'. 

* removes the init scripts for the services (like qmail.init).  In
  fact, this just mean deleting the link 

  /usr/local/sbin/`service'.init -> /var/service/dt-run/dt-service.init

* removes the link /service/`service'.

* stop supervises for the services and their logs.

* remove services from each runlevel's list of services.

runlevel change
***************

Runlevel change is managed by /var/service/dt-run/dt-runlevel.init
which is run "from" /etc/inittab.  

At each runlevel change, if dt-runlevel.init is called as

dt-runlevel.init start

it makes a list of services currently running, feeds this list to
rlc-go, which in turn produces an ordered list of services to
start/stop at the new runlevel.  

`dt-runlevel.init' then runs `service.init stop' on each service to be
stopped.  If service does not stop in 120 seconds, it gets killed with
`svc -k'.  Finally, `dt-runlevel.init' runs `service.init start' on
each service to be started.

If dt-runlevel.init is called as

dt-runlevel.init stop

it will just stop (and 120 seconds later, kill) all currently running
services that should not run at the new runlevel, but no new services
will be started.  

tcprules files
**************

The tcprules file for `service' is expected to be 

/var/service/`service'/tcprules

and the "cdb" file is

/var/service/`service'/tcprules.cdb

For example,

/var/service/rblsmtpd/tcprules
/var/service/rblsmtpd/tcprules.cdb

Once a service is set up with add-service.sh, you can create the cdb
file with the command

`service'.init cdb

For example,

rblsmtpd.init cdb

It is important to note that whatever you specified as CDB during
installation, the tcprules file by `service'.init is assumed to be the
same without the `.cdb' extension.


logging
*******

The main multilog directory for `service' is specified in the log run
file of `service'.  By default, the log run file is

/var/service/`service'/log/run

and the main logdirectory is 

/var/service/`service'/log/main/

There are various ways to look at the logfiles, but you probably
almost always want to filter the output with tai64nlocal. So you can
do something like

cat /var/service/qmail/log/main/current | tai64nlocal |less

The main log directory is specified by the last argument in the last
line of the log run file:

exec setuidgid $LOGUSER multilog t $FILENO $FILESIZE ./main

You can, of course, change this run file to anything you need, but do
not forget that multilog is run as $LOGUSER, and any file or directory
you specify has to be owned by $LOGUSER.  For example, if the last
line of the log run file is

exec setuidgid $LOGUSER multilog t $FILENO $FILESIZE \
./main '-*' '+* * status: *' =status

and LOGUSER=dtlog, then you first need to do

touch  /var/service/`service'/log/status
chmod 644 /var/service/`service'/log/status
chown dtlog /var/service/`service'/log/status
chgrp $(id -g dtlog) /var/service/`service'/log/status

Now about FILENO and FILESIZE.  These make it possible to customize
multilog's log filesize and file number without tinkering with the log
run file.  Namely, 

-- If you do not do anything, then the size and number of log files is
   multilog's default.
 
-- You can set the default log filesize and file number by doing
   something like

   echo 1,000,000 >  /var/service/multilog/filesize
   echo 18        >  /var/service/multilog/fileno

   These values are then used by *all* services. (Unless:) 

-- You set the log filesize and file number for a service by doing
   something like 
   
   echo 5,000,000 >  /var/service/`service'/filesize
   echo 25	  >  /var/service/`service'/filesno

   Then these values are used by service instead of those specified in 
   /var/service/multilog/file{size,no}.

For your convenience, you can separate digits in the files filesize
and fileno, by any number of commas, dots and spaces.  So you can do
either of 

   echo 5,000,000 >  /var/service/qmail/filesize
   echo 5.000.000 >  /var/service/qmail/filesize
   echo 5 000 000 >  /var/service/qmail/filesize

multilog gets `5000000' either way.












