From ddaef0600f6a452ba2df21bbc375f6bec966f48e Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Tue, 28 Jul 2026 10:11:23 +0200 Subject: [PATCH] doc: rewrite sample.conf in the block format This is what 'initctl create' and 'initctl edit -c' put in front of a user writing their first .conf file, so it is also the whole of the "initctl emits the new format" work: neither command generates syntax, they copy this file and open an editor on it. The ASCII diagram naming eight positional fields goes with it. A block has no positions to explain. Signed-off-by: Joachim Wiberg --- src/sample.conf | 116 +++++++++++++++++++++++++++++------------------- 1 file changed, 71 insertions(+), 45 deletions(-) diff --git a/src/sample.conf b/src/sample.conf index e6c6ceab..b742a523 100644 --- a/src/sample.conf +++ b/src/sample.conf @@ -1,62 +1,88 @@ -# sample.conf: template cgroup/run/task/service stanza for finit +# sample.conf: template run/task/service stanza for finit +# +# A .conf file is a series of blocks. Every setting is a key inside +# one, so nothing has to be memorised by position: +# +# service NAME { +# description = "What it is" +# runlevel = "2345" # default: 234 +# conditions = { "net/lo/up" } # wait for these +# envfile = "-/etc/default/daemon" +# command = "/usr/sbin/daemon ARGS" +# } +# +# A leading '-' on a path means carry on if it is missing, so the +# envfile above is optional. Debian and Buildroot keep those files in +# /etc/default, Alpine in /etc/conf.d. +# +# There are four kinds of stanza: +# +# - run : one-shot, wait for it before continuing with the next +# - task : one-shot, started in parallel with the next +# - service : supervised daemon, run in foreground, restarted if it crashes +# - sysv : /etc/init.d style script, start/stop/restart # # The top-level cgroups can be defined anywhere, but share the same # namespace. It is up to the user to ensure groups are defined only -# once, otherwise the last read .conf wins. See below for assigning -# run/task/services to cgroups. The below example creates the cgroup -# NAME with the following cpu and memory settings: +# once, otherwise the last read .conf wins: # -# cgroup NAME cpu.weight:1000 mem.max:65 +# cgroup NAME { +# cpu.weight = 1000 +# memory.max = 65M +# } # -# The one-shot commands 'run' and 'task' are called only once per -# runlevel. Finit does not restart them when they exit. +# A service joins one by naming it, and may override settings for +# itself alone. Here foo and bar share the group foo, baz has its own: # -# - run : wait for completion before continuing with next stanza -# - task : like run but started in background, parallel with other stanzas -# - service : supervised daemon, run in foreground, restarted if it crashes -# -# The env: is an optional path to a file with environment variables to -# adjust the behavior of daemons. Debian and Buildroot use /etc/default -# while Alpine use /etc/conf.d -- ensure your Finit is built correctly. -# The leading '-' determines if its OK to start the service even if the -# env file is missing. -# -# run [LVLS] log command ARGS -- Command -# task [LVLS] log command ARGS -- Command -# service [LVLS] log env:[-]/etc/default/daemon daemon ARGS -- Daemon daemon -# ^ ^ ^ ^ ^ ^ ^ ^ -# | | | | | | | `-- Optional description -# | | | | | | `----------- Daemon arguments -# | | | | | `-------------------------- Path to daemon -# | | | | `---------------------------------------------------- Optional env. file -# | | | `-------------------------------------------------------- Redirect output to log -# | | `--------------------------------------------------------------- Optional conditions -# | `---------------------------------------------------------------------- Optional Runlevels -# `------------------------------------------------------------------------------ Monitored application -# -# Each stanza can also hold a 'cgroup' argument, or be prefixed with -# cgroup.NAME to place all following stanzas in the same group. In -# the following example, foo and bar share the cgroup foo but baz -# runs in its own cgroup baz: -# -# cgroup.foo -# service cgroup:cpu.weight:250,mem.max:655350 foo args -- foo desc -# service cgroup:cpu.weight:150,mem.max:655350 bar args -- bar desc -# service cgroup.baz:cpu.weight:300 baz args -- baz desc +# service foo { cgroup foo {} command = "foo args" } +# service bar { cgroup foo { cpu.weight = 150 } command = "bar args" } +# service baz { cgroup baz { cpu.weight = 300 } command = "baz args" } # Debian GNU/Linux: start SSH daemon as soon as basic networking comes up -#service [2345] env:-/etc/default/ssh /usr/sbin/sshd -D $SSHD_OPTS -- OpenSSH daemon +#service sshd { +# description = "OpenSSH daemon" +# runlevel = "2345" +# conditions = { "net/lo/up" } +# envfile = "-/etc/default/ssh" +# command = "/usr/sbin/sshd -D $SSHD_OPTS" +#} # Alpine Linux: Oneshot task to run once at bootstrap, yes pipes are possible :) -#task [S] env:/etc/conf.d/loadkmap zcat $KEYMAP | loadkmap -- Loading keymap +#run kmap { +# description = "Loading keymap" +# runlevel = "S" +# envfile = "/etc/conf.d/loadkmap" +# command = "zcat $KEYMAP | loadkmap" +#} # Alpine Linux: start SSH daemon with $DROPBEAR_OPTS from /etc/conf.d -#service [2345] cgroup.user env:-/etc/conf.d/dropbear dropbear -R -F $DROPBEAR_OPTS -- Dropbear SSH daemon +#service dropbear { +# description = "Dropbear SSH daemon" +# runlevel = "2345" +# envfile = "-/etc/conf.d/dropbear" +# cgroup user {} +# command = "dropbear -R -F $DROPBEAR_OPTS" +#} # Handle PWR button to shutdown/reboot -- useful in Qemu (virt-manager) -# Depends on syslogd having started. Redirect any output to log. -#service [2345] cgroup:mem.max:32000,cpu.max:1000 log acpid -f -- ACPI daemon +# Depends on syslogd having started. Redirect any output to the log. +#service acpid { +# description = "ACPI daemon" +# runlevel = "2345" +# conditions = { "pid/syslogd" } +# cgroup system { +# memory.max = 32M +# cpu.max = 1000 +# } +# log { } +# command = "acpid -f" +#} # Start rsyslogd as soon as possible, should always run # Provides pid/syslogd condition -#service [S12345] name:syslogd env:-/etc/default/rsyslog rsyslogd -n $RSYSLOGD_OPTIONS -- Reliable syslog daemon +#service syslogd { +# description = "Reliable syslog daemon" +# runlevel = "S12345" +# envfile = "-/etc/default/rsyslog" +# command = "rsyslogd -n $RSYSLOGD_OPTIONS" +#}