--------------------------------------------------------------------------------
configuring cinit, Nico Schottelius 2005-05-28 (Last Modified: 2005-06-05)
--------------------------------------------------------------------------------

0. Pre-compile configuration
1. General configuration layout
2. Hints
2.0 Service executing / parameters
2.1 Daemons
2.2 Logging
2.3 Using prepared scripts
3. Profiles


0. Pre-compile configuration

Have a look at conf/*. Those variable will mostly be used when
compiling cinit. Some will be read later (like destdir).

1. General configuration layout

/etc/cinit (configurable via conf/cinit_dir) stores the complete
cinit configuration.

cinit is service based.
A service consists of
   - a base directory (like /etc/cinit/getty/1)
   - dependency configuration:

      ./wants  - services it wants to be started before (but it
                 will work anyway)

      ./needs/ - services it needs. If those services fail, this service
                 won't be started
 
   - a flag indicating whether to respawn the service:

      ./respawn (simply touch it)

   - the program to run when switching the service on and off:

      ./on        (a link to a program or a shell script)
      ./on.params (see conf/c_params, the parameters to pass to the program)
      ./on.env    (see conf/c_env, the environment to pass to the program)

      ./off          (call that when shutting down the service)
      ./off.params   (the parameters to pass to the program)
      ./on.env       (the environment to pass to the program)

You should have a look at the samples/ directory for examples.

If things are missing, cinit will continue with what's available.
This way you only need the files you use. Some examples:

   /etc/cinit/init:
      ./wants -> services it wants
      ./needs -> services it needs
      That's everything

   /etc/cinit/testsvc:
      on       -> link to program
      on.param -> parameters to program
      respawn  -> restart it
      That's everything, as it has no dependencies
 
   /etc/cinit/fullsvc:
      on          -> program to start when switching on
      on.params   -> parameters to pass to start program
      on.env      -> environment to pass to start program

      respawn     -> respawn on service

      off         -> program to start when switching off
      off.params  -> parameters to pass to stop program
      off.env     -> environment to pass to stop program

      wants/*     -> services it wants before starting (non-critical ones)
      needs/*     -> links to needed services (critical!) before starting


2. Hints

2.0 Service executing / parameters

The on and off files can and should be links to the programs you want
to execute. This way you save yourself loading the big shell (which is
on many Linux systems bash, why so ever, dash does the job as good, still
beeing small).

The on.params and off.params files could also be links to system configuration:

Assume the service is called local-tuning/keyboard. The on script
could look like:

   on -> /bin/loadkeys
   on.params -> /etc/sys/keyboard.mapping

   And /etc/sys/keyboard.mapping would contain only the string
   "dvorak" (or "de-latin1" or "sg-latin1" or ...).


2.1 Daemons

Respawning daemons is a bit more difficult, as daemons do often fork()
(go to background, the calling process exits).

This way cinit cannot watch it directly.

The first solution is to check the documentation of your daemon program,
if it has a switch to disable forking
   (  The following daemons / servers are known to do that easily:
      openssh [ssh server]:         -D
      bind [dns server/caching]:    -f
      syslogd [log server]:         -n
      isc-dhcp3 [dhcp server]:      -f
      qmail [mta]:                  normal behaviour
      tcpserver [super server]:     normal behaviour
      xinetd [super server]:        -dontfork
      openvpn [vpn server]:         normal behaviour
      oops [http proxy]:            normal behaviour
      frox [ftp proxy]:             "NoDetach" in config
      proftpd [ftp server]:         -n
      vsftpd [ftp server]:          normal behaviour (or: config: background=no)
      distccd [compile server]:     normal behaviour
      monotone [vcs]:               normal behaviour
      cupsd [printer server]:       -f or -F
      mini-lpd [printer server]:    normal behaviour

      And those daemons do not offer the possibility (as of release 0.0.6):

      - apache (only with debug mode)
      - portmap (only with debug mode)
      - inetd (some variants)
   )


The other possibility is to use a program, which will
   a) start the daemon
   b) look into the pidfile of the daemon
   c) will then wait until that pid does not exist anymore
   d) and then it exits and cinit will restart it (goto a) now)

Such a program will be included into one of the next cinit releases,
though I do not recommend using it. You should better contact the
authors and make them implement a clean non-forking mode.


2.2 Logging

Currently there's no special logging support.
When programs write to stdout, it will be displayed on
the same stdout cinit is connected to
(we don't even open /dev/console - we are too lazy currently).


2.3 Using prepared scripts

In the bin/ directory of this tarball you'll find:

   cinit.add.dependency - add a dependency to a service
   cinit.add.getty      - add a new getty
   cinit.create.empty.service - create an empty service
   cinit.remove.getty   - remove a getty service
   cinit.respawn.off    - switch respawing off
   cinit.respawn.on     - switch respawing on
   cinit.shutdown       - shutdown in /bin/sh


3. Profiles

Since cinit-0.0.6 there is profile in cinit.
Profiles are described in doc/profile.support.

X. Examples

Todo.

X.0 Getty
X.1 OpenSSH