cinit - Configuring =================== Nico Schottelius 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 <<>> 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/