import cinit from unix.schottelius.org
Signed-off-by: Nico Schottelius <nico@ikn.schottelius.org>
This commit is contained in:
Nico Schottelius
parent
3729fc68eb
commit
423ba10303
13396 changed files with 269468 additions and 0 deletions
|
|
@ -0,0 +1,327 @@
|
|||
cinit - Configuring
|
||||
===================
|
||||
Nico Schottelius <nico-cinit__@__schottelius.org>
|
||||
0.1, for cinit 0.3, Initial version from 2005-05-28
|
||||
:Author Initials: NS
|
||||
|
||||
|
||||
This documentes describes how to configure cinit.
|
||||
You should already have cinit installed, otherwise read
|
||||
"cinit - Installing" first.
|
||||
|
||||
|
||||
General configuration layout
|
||||
----------------------------
|
||||
Cinit uses the <<<cconfig>>> configuration syntax, which means that
|
||||
the configuration is kept as simple as possible. The following
|
||||
sections will show you what that means.
|
||||
|
||||
The cinit configuration consists of
|
||||
- a special configuration directory
|
||||
- and the service definitions.
|
||||
|
||||
Paths
|
||||
-----
|
||||
Normally the configuration is kept below '/etc/cinit'
|
||||
(though you can change this before compiling in conf/cinit_dir).
|
||||
|
||||
The full description of the path layout of cinit and how to change it
|
||||
can be found in 'paths.text'.
|
||||
|
||||
Conf
|
||||
----
|
||||
The special configuration directory is normally called `conf/`
|
||||
(defined at compile-time in `conf/c_confdir`).
|
||||
|
||||
For all executables into this directory apply the same rules as mentioned
|
||||
below in "Execution: on and off": Appened .params specifies parameters,
|
||||
appended .env specifies environment.
|
||||
|
||||
|
||||
conf/last
|
||||
~~~~~~~~~
|
||||
This is the last part that will be executed. After it has finished, cinit
|
||||
will halt, power-off or reboot your machine.
|
||||
|
||||
You can use it for whatever task to accomplish (as most things of cinit), but
|
||||
the idea behind it is to use it for cleaning up things that are not covered
|
||||
by the off parts of the services. This maybe swapoff (although this is an unecessary
|
||||
call before poweroff, imho and even if needed this could be handled within the
|
||||
off part of the same services that enabled it) or `umount -a` for everything
|
||||
manually mounted and not unmounted yet.
|
||||
|
||||
|
||||
conf/sleep_before_kill
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
This file contains just one line: The number of seconds to sleep after SIGTERM was sent
|
||||
to every remaining process before sending SIGKILL to all processes. If this file
|
||||
is unreadable or not existent, cinit will fall back to the value compiled in
|
||||
(which was specified at build time in conf/sleep_kill).
|
||||
|
||||
|
||||
Services
|
||||
--------
|
||||
cinit is service based. Other init systems use shell
|
||||
scripts (for instance /etc/rc, /etc/init.d/rc as starters
|
||||
and /etc/rc*.d/* as "service definitions").
|
||||
|
||||
'current-init-problems.text' explains why cinit does *not*
|
||||
use nor recommends the use of shell scripts.
|
||||
|
||||
A service is simply a directory. This directory contains information about
|
||||
|
||||
- what should be started when starting the service
|
||||
- what should be started when stoping the service
|
||||
- what dependencies the service has
|
||||
- whether to restart it, when it exits
|
||||
|
||||
|
||||
Full service definition
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
. A service consists of
|
||||
- a base directory (like /etc/cinit/svc/mount/root/)
|
||||
- dependency configuration (`needs` and `wants`)
|
||||
- start/stop programs (`on` and `off`)
|
||||
- respawn flag (`respawn`)
|
||||
|
||||
|
||||
Base directory
|
||||
^^^^^^^^^^^^^^
|
||||
You can create the base directory everywhere below /etc/cinit/svc.
|
||||
You may and it is recommened to create a directory structure
|
||||
(see 'example-directory-structure.text').
|
||||
|
||||
|
||||
Dependencies
|
||||
^^^^^^^^^^^^
|
||||
The subdirectories
|
||||
|
||||
- `wants`
|
||||
- and `needs`
|
||||
|
||||
contain the dependencies for the service.
|
||||
|
||||
Read 'dependencies.text' for more information.
|
||||
|
||||
|
||||
Respawning
|
||||
^^^^^^^^^^^
|
||||
If you create the empty file 'respawn' (adjustable via conf/c_respawn)
|
||||
the service will be restarted after it exits.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
# Tell cinit to respawn the eth0.udhcpc service
|
||||
touch /etc/cinit/svc/network/eth0.udhcpc
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
|
||||
Execution: on and off
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
When a service starts, the file `on` in the service
|
||||
directory is executed. It is ok, if this file is not existing.
|
||||
When a service stops, the file `off` in the service
|
||||
directory is executed.
|
||||
|
||||
The file with the extension `.params` is used to specify the arguments
|
||||
to pass. Each line contains exactly one parameter.
|
||||
|
||||
The file with the extension `.env` is used to specify the environment
|
||||
to pass. Each line contains exactly one variable definition in the form
|
||||
'variable=value'.
|
||||
|
||||
. The following six files are possibly used on starting/stoping:
|
||||
- ./on (the program called on startup)
|
||||
- ./on.params (the parameters to pass to the program, see conf/c_params)
|
||||
- ./on.env (the environment to pass to the program, see conf/c_env)
|
||||
- ./off (the program called when shutting down the service)
|
||||
- ./off.params (the parameters to pass to the program)
|
||||
- ./on.env (the environment to pass to the program)
|
||||
|
||||
Some examples:
|
||||
----------------------------------------------------------------------
|
||||
/etc/cinit/svc/init:
|
||||
./wants -> services it wants
|
||||
./needs -> services it needs
|
||||
----------------------------------------------------------------------
|
||||
|
||||
A more or less normal service without dependencies:
|
||||
----------------------------------------------------------------------
|
||||
/etc/cinit/testsvc:
|
||||
on -> link to program
|
||||
on.param -> parameters to program
|
||||
respawn -> restart it
|
||||
----------------------------------------------------------------------
|
||||
|
||||
A service with all options used:
|
||||
----------------------------------------------------------------------
|
||||
/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 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
|
||||
----------------------------------------------------------------------
|
||||
|
||||
|
||||
Profiles
|
||||
--------
|
||||
Profiles allow you to define different startup scenarios and select
|
||||
those before bootup. Read 'profiles.text' for more information about
|
||||
profiles.
|
||||
|
||||
The profile support was added in cinit-0.0.6.
|
||||
|
||||
|
||||
Service execution order
|
||||
------------------------
|
||||
The first service executed is '/etc/cinit/svc/init'.
|
||||
If a profile is selected '/etc/cinit/svc/`profilename`' is used
|
||||
instead.
|
||||
|
||||
Cinit builds a full service dependency tree through the `wants`
|
||||
and `needs` of the first service and its dependencies
|
||||
(recursively).
|
||||
|
||||
After the tree is generated, cinit begins to start the services
|
||||
at the end of the tree. These services have no `needs`.
|
||||
|
||||
If you manage to create circular dependencies your system will not startup.
|
||||
You can verify the correctness your configuration with the script
|
||||
`cinit.check.config`.
|
||||
|
||||
|
||||
Hints
|
||||
-----
|
||||
|
||||
Service executing / parameters
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The on and off files can and should be links to the programs you want
|
||||
to execute instead of a shell script. This way you save yourself the overhead
|
||||
of loading a shell. The speed enhancement is very big if you have shells
|
||||
like bash installed as /bin/sh (which is *not* senseful anyway, I would
|
||||
recommend dash or ksh for /bin/sh).
|
||||
|
||||
The on.params and off.params files could also be links to system configuration:
|
||||
|
||||
Assume the service is called local-tuning/keyboard.
|
||||
The service could look like this:
|
||||
----------------------------------------------------------------------
|
||||
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 ...).
|
||||
----------------------------------------------------------------------
|
||||
|
||||
|
||||
Daemons
|
||||
~~~~~~~~
|
||||
Daemons are programs that go away to the background (using fork()) after
|
||||
start).
|
||||
|
||||
The fork-away strategy seems to be some illness introduced by traditional
|
||||
init systems, that are dependent on the fact, that a process exits on
|
||||
startup.
|
||||
|
||||
cinit in contrast remembers the process ID (pid) of the services it
|
||||
restarts (those with `respawn` enabled).
|
||||
|
||||
So when the daemon fork()s away and the parent process exits it looks to
|
||||
cinit like the watched service died and cinit will restart it.
|
||||
|
||||
Happily, most processes can be taught not to go to background.
|
||||
Some processes even do that by default and very less are broken that
|
||||
one cannot tell them not to background.
|
||||
|
||||
A list of known processes that are normally used in respawn
|
||||
processes can be found in 'daemons.backgrounding.text'.
|
||||
|
||||
If your process is not listed in `daemons.backgrounding.text',
|
||||
check the documentation of your daemon program, if may have a
|
||||
switch to disable forking.
|
||||
|
||||
But, with a small hack it is even possible to respawn those broken processes:
|
||||
|
||||
We start a program, that
|
||||
- starts the daemon,
|
||||
- monitors the pidfile of the daemon,
|
||||
- waits until that pid does not exist anymore
|
||||
- and then exits.
|
||||
|
||||
Such a program is included into the cinit source tarball,
|
||||
though I do not recommend using it. The better way is to implement
|
||||
non forking mode into your process.
|
||||
|
||||
The name of the program (actually a shell script) is 'cinit.wait.for.daemon'.
|
||||
|
||||
You can use it as the `on` part of a service and add
|
||||
|
||||
- the pidfile,
|
||||
- the process binary
|
||||
- and the process parameters
|
||||
|
||||
to `on.params`.
|
||||
|
||||
Thus the service could look like:
|
||||
----------------------------------------------------------------------
|
||||
svc-broken-daemon/
|
||||
on -> /sbin/cinit.wait.for.daemon
|
||||
on.params:
|
||||
/var/run/apache.pid
|
||||
/usr/packages/apache-2.0.51/bin/httpd
|
||||
-DSSL
|
||||
----------------------------------------------------------------------
|
||||
(This is not a so good example, because Apache supports non-forking mode).
|
||||
|
||||
Be aware: This is just a hack, first try to avoid backgrounding
|
||||
and you won't need this hack!
|
||||
|
||||
|
||||
Logging
|
||||
~~~~~~~
|
||||
Currently there's no special logging support.
|
||||
When a process writes to stdout, it will be displayed on
|
||||
the same stdout cinit is connected to.
|
||||
|
||||
In newer versions cinit (perhaps cinit-0.4) will also support logging
|
||||
stdout and stderr of a service.
|
||||
|
||||
|
||||
How to migrate your old init-system configuration to cinit
|
||||
----------------------------------------------------------
|
||||
This is highly dependent on your actual system, your system
|
||||
configuration and your own ideas.
|
||||
|
||||
Cinit is able to replace all other init systems I know about.
|
||||
|
||||
So the only question is "How to do it?".
|
||||
|
||||
There are some hints on how to migrate to cinit in general and also
|
||||
some os specific help in the file 'migrating-init-systems.text',
|
||||
|
||||
|
||||
Debugging the configuration
|
||||
----------------------------
|
||||
Use `ls -lR /etc/cinit` or one of the tools found in contrib+tools/.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
Currently there are some example configurations available
|
||||
at http://unix.schottelius.org/cinit/samples/cinit-0.3/, sorted
|
||||
by host on which they are created.
|
||||
|
||||
In near future, there will also be a file name configuration.example.text,
|
||||
which will lead you to a sample configuration.
|
||||
|
||||
|
||||
References
|
||||
----------
|
||||
+ [[[cconfig]]] http://nico.schotteli.us/papers/linux/cconfig/
|
||||
Loading…
Add table
Add a link
Reference in a new issue