finit/doc/config.md

Configuration

• Introduction
• Syntax
• Limitations
  • /etc/finit.conf
  • /etc/finit.d

Introduction

Finit can be configured using only the original /etc/finit.conf file or in combination with /etc/finit.d/*.conf. Finit 3 can even start a system using only /etc/finit.d/*.conf`, highly useful for package-based Linux distributions -- each package can provide its own "script" file.

• /etc/finit.conf: main configuration file, read only once at boot
• /etc/finit.d/*.conf: snippets, usually one service per file

Not all configuration directives are available in /etc/finit.d/*.conf and some directives are only available at bootstrap, runlevel S, see the section Limitations below for details.

To add a new service, simply drop a .conf file in /etc/finit.d and run initctl reload. (It is also possible to SIGHUP to PID 1, or call finit q, but that has been deprecated with the initctl tool). Any service read from this directory is flagged as a dynamic service, so changes to or removal of /etc/finit.d/*.conf files, is detected.

On initctl reload the following is checked for all services:

• If a service's .conf file has been removed, or its conditions are no longer satisifed, the service is stopped.
• If the file is modified, or a service it depends on has been reloaded, the service is reloaded (stopped and started).
• If a new service is added it is automatically started — respecting runlevels and return values from any callbacks.

For more info on the different states of a service, see the separate document Finit Services.

Syntax

• module <MODULE>
  Load a kernel module, with optional arguments

• network <PATH>
  Script or program to bring up networking, with optional arguments

• rlimit <hard|soft> RESOURCE <LIMIT|infinity>
  Set the hard or soft limit for a resource. RESOURCE is a lower-case string matching the RLIMIT_ constants from setrlimit(2), without the prefix. E.g. to set RLIMIT_CPU, use cpu. The limit is an integer that depends on the resource being modified, see the man page for more information. The special limit infinity means unlimited.

        # No process is allowed more than 8MB of address space
        rlimit hard as 8388608

        # Core dumps may be arbitrarily large
        rlimit soft core infinity

• runlevel <N>
  N is the runlevel number 1-9, where 6 is reserved for reboot.
  Default is 2.

• run [LVLS] <COND> /path/to/cmd ARGS -- Optional description
  One-shot command to run in sequence when entering a runlevel, with optional arguments and description.

  run commands are guaranteed to be completed before running the next command. Highly useful if true serialization is needed.

• task [LVLS] <COND> /path/to/cmd ARGS -- Optional description
  One-shot like 'run', but starts in parallel with the next command.

  Both run and task commands are run in a shell, so pipes and redirects can be freely used:

        task [s] echo "foo" | cat >/tmp/bar

• service [LVLS] <COND> /path/to/daemon ARGS -- Optional description
  Service, or daemon, to be monitored and automatically restarted if it exits prematurely. Please note that you often need to provide a --foreground or --no-background argument to most daemons to prevent them from forking off a sub-process in the background.

        service [2345] <svc/sbin/zebra> /sbin/ospfd -- OSPF daemon

The [2345] is the runlevels ospfd is allowed to run in, they are optional and default to level 2-5 if left out.

The <...> is the condition for starting ospfd. In this example Finit waits for another service, /sbin/zebra, to have created its PID file in /var/run/zebra.pid before starting ospfd.

For a detailed description of conditions, and how to debug them, see the Finit Conditions document.

• inetd service/proto[@iflist] <wait|nowait> [LVLS] /path/to/daemon args
  Launch a daemon when a client initiates a connection on an Internet port. Available services are listed in the UNIX /etc/services file. Finit can filter access to from a list of interfaces, @iflist, per inetd service as well as listen to custom ports.

        inetd ftp/tcp	nowait	@root	/usr/sbin/uftpd -i -f
        inetd tftp/udp	wait	@root	/usr/sbin/uftpd -i -t

The following example listens to port 2323 for telnet connections and only allows clients connecting from eth0:

        inetd 2323/tcp@eth0 nowait [2345] /sbin/telnetd -i -F

The interface list, @iflist, is of the format @iface,!iface,iface, where a single ! means to deny access. Notice how interfaces are comma separated with no spaces.

The inetd directive can also have -- Optional Description, only Finit does not output this text on the console when launching inetd services. Instead this text is sent to syslog and also shown by the initctl tool. More on inetd below.

• runparts <DIR>
  Call run-parts(8) on DIR to run start scripts. All executable files, or scripts, in the directory are called, in alphabetic order.

  It can be beneficial to use S01name, S02othername, etc. if there is a dependency order between the scripts. Symlinks to existing daemons can talso be used, but make sure they daemonize by default.

  As the optional /etc/rc.local shell script, make sure that all your services and programs either terminate or start in the background or you will block Finit.

• include <CONF>
  Include another configuration file. Absolute path required.

• tty [LVLS] <DEV> [BAUD] [noclear] [nowait] [TERM]
tty [LVLS] <CMD> <ARGS> [noclear] [nowait]
  The first variant of this option uses the built-in getty on the given TTY device DEV, in the given runlevels. Default baud rate is 38400.

  Example:

        tty [12345] /dev/ttyAMA0 115200 noclear vt220

The second tty syntax variant is for using an external getty, like agetty or the BusyBox getty.

By default both variants clear the TTY and wait for the user to press enter before starting getty.

Example:

        tty [12345] /sbin/getty  -L 115200 /dev/ttyAMA0 vt100
        tty [12345] /sbin/agetty -L ttyAMA0 115200 vt100 nowait

The noclear option disables clearing the TTY after each session. Clearing the TTY when a user logs out is usually preferable.

The nowait option disables the press Enter to activate console message before actually starting the getty program. On small and embedded systems running multiple unused getty wastes both memory and CPU cycles, so wait is the preferred default.

Notice the ordering, the TERM option to the built-in getty must be the last argument.

Embedded systems may want to enable automatic DEV by supplying the special @console device. This works regardless weather the system uses ttyS0, ttyAMA0, ttyMXC0, or anything else. Finit figures it out by querying sysfs: /sys/class/tty/console/active.

Example:

        tty [12345] @console 115200 noclear vt220

On really bare bones systems Finit offers a fallback shell, which should not be enabled on production systems since. This because it may give a user root access without having to log in. However, for bringup and system debugging it can come in handy:

        configure --enable-fallback-shell

One can also use the service stanza to start a stand-alone shell:

        service [12345] /bin/sh -l

When running make install no default /etc/finit.conf will be installed since system requirements differ too much. Try out the Debian 6.0 example /usr/share/doc/finit/finit.conf configuration that is capable of service monitoring SSH, sysklogd, gdm and getty!

Every run, task, service, or inetd can also list the privileges the /path/to/cmd should be executed with. Simply prefix the path with [@USR[:GRP]] like this:

    run [2345] @joe:users /usr/bin/logger "Hello world"

For multiple instances of the same command, e.g. a DHCP client or multiple web servers, add :ID somewhere between the run, task, service keyword and the command, like this:

    service :1 [2345] /sbin/httpd -f -h /http -p 80   -- Web server
    service :2 [2345] /sbin/httpd -f -h /http -p 8080 -- Old web server

Without the :ID to the service the latter will overwrite the former and only the old web server would be started and supervised.

The run, task, service, or inetd stanzas also allow the keyword log to redirect stderr and stdout of the application to syslog, using logger.

Worth noting is that conditions is allowed for all these stanzas. For a detailed description, see the Conditions document.

Limitations

To understand the limitations of finit.conf vs finit.d it is useful to picture the different phases of the system: bootstrap, runtime, and shutdown. The finit.conf file can be used for all possible settings, but finit.d/*.conf can only be used for runtime settings.

/etc/finit.conf

This file was the only way to set up and boot a system using Finit. It is used for pre-runtime settings like system hostname, network bringup and shutdown:

• host
• mkdod
• network
• runparts
• include
• shtudown
• runlevel
• ... and all configuration stanzas from /etc/finit.d below

/etc/finit.d

Support for partial .conf files in /etc/finit.d was added to handle changes of the system configuration at runtime. It does not support the above finit.conf settings described above, only the following:

• module, but only in runlevel S
• service
• task
• run
• inetd
• rlimit
• tty

NOTE:* The /etc/finit.d directory was previously the default Finit runparts directory. Finit no longer has a default runparts, make sure to update your setup, or the finit configuration, accordingly.