New file format

[troglobit]

New Finit .conf format

Reference for the libconfuse-based format in src/conf.c, written
from the schema and the actual translators.

Every setting is listed with what it does and a snippet you can paste
into a .conf file.

---

How a file is chosen and parsed

Both formats use .conf. There is no marker line and no new extension;
conf_parse_file() decides per file by trying to parse it:

1. Parse strictly with libconfuse. Success means block format.
2. On a parse error, parse again accepting any unknown key. If that
   succeeds the file is block format with a typo, and the strict error
   is reported with file and line. The file is not handed to the legacy
   parser.
3. If the lenient parse fails too, the file goes to the legacy
   one-liner parser.

One format per file. Mixing an environment { } block and a legacy
run [S] ... line in the same file makes the whole file fail both
parses, and it lands in the legacy parser, where the block lines are
junk.

Files are read from /etc/finit.conf first, then *.conf in
/lib/finit/system/, /run/finit/system/, /etc/finit.d/ and
/etc/finit.d/enabled/, in that order. /etc/finit.d/available/ is
never read; only what is enabled.

---

Grammar

Native libconfuse. Values are quoted strings, bare tokens, or integers;
lists use braces; sections may carry a title.

# shell comment
// C++ comment
/* C comment */

key      = "value"                 # string
number   = 20                      # integer
flag     = true                    # boolean
list     = { "one", "two" }        # string list
block title { key = "value" }      # titled section

path = "${HOME}/thing"             # environment expansion
include("/etc/finit.d/extra.conf") # native include

Bare tokens work where a string is expected, so memory.max = 65M and
restart = always both parse as strings.

Two conventions

Keys are kebab-case, never snake_case or CamelCase: restart-sec,
stop-timeout, reboot-watchdog.

List-valued keys are plural: conditions, conflicts, capabilities,
modules, extra-groups. Two imperatives keep their singular form
because they are verbs rather than nouns: mknod and include.

Aliases

Nine, no more. An alias may abbreviate the canonical name, or preserve
a legacy spelling; it may not simply rename.

Canonical	Alias
description	desc
conditions	cond
capabilities	caps
modules	mod
envfile	env
manual-start	manual
remain-after-exit	remain
stop-signal	halt
stop-timeout	kill

The - prefix

A leading - on a path means "carry on if it is not there", the same
mark systemd uses on EnvironmentFile= and ExecStart=:

service foo {
    envfile = "-/etc/default/foo"  # skip the file if missing
    command = "-/usr/sbin/foo"     # skip the whole stanza if missing
}

It is the only sigil that means "optional". Two others exist and mean
something else: ! on runlevel inverts the set, and ~ on a
condition propagates a reload. Both are covered where they apply.

---

service, task, run, sysv

Four block types share one schema, so every key below parses in all
four. The schema does not enforce which keys are meaningful where:
remain only does something for run and task, notify is
meaningless for sysv, and exec-start-ready is a no-op in run and
task because readiness only applies to daemons. None are rejected.

The section title is the identity, optionally name:id:

service sshd     { command = "/usr/sbin/sshd -D" }
service getty:1  { command = "/sbin/agetty tty1" }

command is the only required key. A block without it is skipped with
an error. Blocks run in the order they appear in the file, recovered by
sorting on each section's source line.

Identity and selection

Key	Alias	Type	Meaning
description	desc	string	Shown by initctl status, and during boot
command		string	Command and arguments; a leading - tolerates a missing binary
runlevel		string	Runlevels to run in, e.g. "2345", "S12345"; a leading ! inverts the set
conditions	cond	list	Conditions that must all be asserted before the block runs
if		string	Skip the block entirely unless the statement holds
conflicts		list	Other services this one cannot coexist with

service sshd {
    description = "OpenSSH daemon"
    runlevel    = "2345"
    conditions  = { "net/route/default" }
    command     = "/usr/sbin/sshd -D"
}

runlevel = "!12345" means every runlevel except those, the set
starts full and the listed levels are cleared. It is a set of
characters, not a range, so S and the digits, and !1-9 does not
work.

Condition prefixes

~ before a condition propagates a reload of the upstream service to
this one, instead of merely pausing and resuming it. Any condition in
the list may carry it. Note that it sets one flag for the whole block,
so writing it on a single condition still affects all of them.

service svc_b {
    conditions = { "pid/svc_a" }          # barrier: just needs A running
    command    = "/sbin/svc_b"
}

service svc_c {
    conditions = { "~pid/svc_b" }         # follow B's reload
    reload-signal = "none"                # ... by restarting
    command    = "/sbin/svc_c"
}

There is no way to express "run when this condition is not
asserted". A + and - pair for asserted and deasserted conditions
has been discussed, and the list is kept clear of anything that is not
a condition so those operators have room.

Porting note: a legacy condition list may be led by !, which is not
a condition and not a negation. It is a flag on the block, and it maps
to two different keys here depending on the block it was in.

Legacy	Block format
<!...> on a service or sysv	reload-signal = "none"
<!...> on a run or task	required = false

task pwrfail {
    conditions = { "sys/pwr/fail" }
    required   = false             # was <!sys/pwr/fail>
    command    = "initctl poweroff"
}

A ! left in a conditions list warns and is ignored, as does either
key on a block type it does not apply to.

Process environment

Key	Alias	Type	Meaning
envfile	env	string	File to source; a - prefix makes it optional
user		string	User to run as
group		string	Primary group
extra-groups		list	Supplementary groups
capabilities	caps	list	Linux capabilities to retain
tty		string	Controlling terminal for the process

service dropbear {
    envfile      = "-/etc/conf.d/dropbear"
    user         = "sshd"
    group        = "sshd"
    extra-groups = { "wheel", "dialout" }
    capabilities = { "CAP_NET_BIND_SERVICE" }
    command      = "/usr/sbin/dropbear -R -F $DROPBEAR_OPTS"
}

user without group runs in the user's own group. group without
user implies root. Note that envfile names a file to source;
inline variables are the top-level environment {} block.

Supervision and readiness

Key	Alias	Type	Meaning
type		string	Only "forking" is understood; anything else warns and is ignored
notify		string	Readiness protocol: none, pid, systemd, s6
pidfile		bool/string	true for the derived default, a bare name, or a path
pidfile-create		bool	Finit writes the file instead of the daemon
manual-start	manual	bool	Do not start automatically; initctl start only
remain-after-exit	remain	bool	run/task only; keep it in the service list after it exits
required		bool	run/task only; false means it does not hold up bootstrap
respawn		bool	Exiting is normal; restart at once rather than treating it as a failure

service nginx {
    type    = "forking"
    pidfile = "/run/nginx.pid"
    notify  = "pid"
    command = "/usr/sbin/nginx"
}

The daemon writes its own pidfile unless told otherwise, so the three
forms of pidfile name a path and nothing more:

service udevd {
    pidfile = true             # /var/run/<command basename>.pid
  # pidfile = "udevd"          # a bare name, /var/run/udevd.pid
  # pidfile = "/run/foo.pid"   # an explicit path
    command = "/lib/systemd/systemd-udevd"
}

pidfile-create = true is the exception, for a foreground daemon that
writes no pidfile of its own. It is the fragile path: Finit then
creates the file on start and removes it on stop. Naming the file and
choosing who writes it are separate decisions, so changing the path
never changes the owner.

Restart behaviour

Key	Alias	Type	Meaning
restart		string	true, false, always or never
restart-max		int	How many restarts before giving up; default 10
restart-sec		int	Seconds to wait between restarts
oncrash		string	reboot or script
reload-signal		string	Signal that reloads the daemon, or none to restart it instead
stop-signal	halt	string	Signal sent to stop the service, e.g. SIGTERM
stop-timeout	kill	int	Seconds between the stop signal and SIGKILL, 1-300
runtime-dir		string	Directory under /run, created at start, owned by user, removed on stop
state-dir		string	Same under /var/lib, persists
cache-dir		string	Same under /var/cache, persists
logs-dir		string	Same under /var/log, persists
config-dir		string	Same under /etc, persists

service watchdogd {
    restart      = "always"
    restart-sec  = 5
    oncrash      = "reboot"
    stop-signal  = "SIGTERM"
    stop-timeout = 10
    command      = "/usr/sbin/watchdogd"
}

Finit reloads a daemon by sending it reload-signal, SIGHUP by
default, unless exec-reload is set, which takes precedence. With
reload-signal = "none" there is no signal to send and the service is
restarted instead. Only SIGHUP and none are accepted for now, in
any case and with or without the SIG prefix, because the legacy line
this translates into can carry nothing else.

remain-after-exit decides whether a finished run or task keeps
existing. By default it does not: the entry is removed, so it re-runs
whenever its runlevel is entered again, initctl cannot see it, and
exec-stop-post never fires. With the key set it stays in the list in
a done state, is not re-run on runlevel re-entry, and gets a real
teardown when stopped or when it leaves its runlevels.

This is systemd's RemainAfterExit=, and the two agree on the default.
Finit is the unusual one in having a vanishing model at all: SMF's
duration = transient, s6-rc oneshots and OpenRC services all stay
around once run, so no other init system needs the option.

task firewall {
    runlevel          = "2345"
    remain-after-exit = true
    exec-stop-post    = "/usr/sbin/teardown-firewall"
    command           = "/usr/sbin/setup-firewall"
}

It is ignored, with a warning, for a task whose only runlevel is S.
Bootstrap tasks are pruned as soon as they finish, so there is nothing
left to remain, and their exec-stop-post never runs.

required = false needs a word on what it does not do. Finit has
two separate notions of blocking: a run blocks the next stanza,
which is what makes it a run rather than a task, and separately
the bootstrap barrier waits for every run and task to finish before
leaving runlevel S. required speaks only to the second. A run with
required = false still runs in sequence; it simply stops holding up
bootstrap. Run/tasks conditioned on hook/svc/up or hook/system/up
are exempt from that barrier already and need no key.

restart is the policy and restart-max the count. true is the
default policy, restart up to restart-max; false and never mean
no restarts; always is unlimited and ignores restart-max. An
unrecognised word warns and is treated as true.

respawn is not part of that family

respawn takes a different path through the state machine, and the
difference is not "forever" but why the process exited. For a
service, exiting is a failure: Finit counts it, waits restart-sec,
and gives up at restart-max. For a respawn service, exiting is
normal work, so it restarts at once with no counter and no give-up.
That is the getty case, where a login ending is the expected outcome
and the next getty should appear immediately.

The two are not interchangeable. restart = "always" still counts and
still waits, and restart-sec = 0 does not mean "immediately", it
means the retry timer is never armed, so the service would not come
back at all.

systemd has no equivalent key. A getty there is Restart=always with
RestartSec=0 and StartLimitIntervalSec=0 to switch the rate
limiter off, which is the same behaviour assembled from three general
settings rather than named as one.

Today a respawn service ignores restart-max and oncrash entirely,
even when it exits non-zero every time, so a permanently broken getty
retries forever and never triggers oncrash. The intended direction
is for respawn to honour the restart settings on a failing exit
while keeping the immediate restart on a clean one: normal exits stay
normal, failures become failures. That split is also where
on-failure and smarter backoff would fit.

Lifecycle scripts

Six hooks, each with a -timeout of its own, in seconds, 0-3600.
Without one the service's stop-timeout is used.

Key	Alias	Fires
exec-start-pre		before the service starts
exec-start-ready		once it signals readiness; daemons only
exec-stop		in place of the stop signal
exec-stop-post		after it has stopped, including after a crash
exec-reload		in place of SIGHUP
exec-cleanup		when the service is removed from the configuration

service dnsmasq {
    exec-start-pre         = "/etc/dnsmasq/pre.sh"
    exec-start-pre-timeout = 10
    exec-stop-post         = "/etc/dnsmasq/post.sh"
    exec-reload            = "/etc/dnsmasq/reload.sh"
    command                = "/usr/sbin/dnsmasq -k"
}

The script must exist and be executable or it is skipped with a
warning. Mapped onto systemd, exec-start-pre is ExecStartPre=,
exec-start-ready is ExecStartPost=, and exec-stop-post is
ExecStopPost=; exec-cleanup has no counterpart.

Service output

log {} says where the service's own output goes. /dev/null and
/dev/console are spelled as paths, so there is one way to say it.

Key	Alias	Meaning
file		Path, or /dev/null to discard, or /dev/console
priority		Syslog facility and level, e.g. daemon.info
identity		Syslog tag

service foo {
    log {
        file     = "/var/log/foo.log"
        priority = "daemon.info"
        identity = "foo"
    }
    command = "/usr/bin/foo"
}

service quiet  { log { file = "/dev/null" }  command = "/usr/bin/quiet" }
service chatty { log { }                     command = "/usr/bin/chatty" }

The empty block is how a service asks for syslog with defaults.
Careful when copying these: at file scope log {} is the rotation
block below, which has no file. There
is no log = true: libconfuse rejects a name declared as both a scalar
and a section.

Per-service cgroup and rlimit

Both are sections, covered below.

---

tty

Three shapes, distinguished by which key is present. A tty block with
none of device, command, notty or rescue is skipped with an
error.

Key	Alias	Type	Meaning
device		string	Terminal for the built-in getty, e.g. @console
baud		int	Line speed; omit to keep the kernel setting
term		string	TERM value, device form only
command		string	External getty; a leading - tolerates a missing binary
notty		bool	No terminal at all, for board bring-up
rescue		bool	Rescue shell
runlevel		string	Runlevels to run in
conditions	cond	list	Conditions that must be asserted
noclear		bool	Do not clear the screen before the prompt
nowait		bool	Skip the "press Enter to activate" prompt
nologin		bool	Run a shell directly instead of login

Built-in getty, selected by device:

tty console {
    device     = "@console"    # or /dev/ttyAMA0
    baud       = 115200        # omit to keep the kernel setting
    term       = "vt220"
    runlevel   = "12345"
    conditions = { "net/lo/up" }
    noclear    = true
    nowait     = true
    nologin    = true
}

External getty, selected by command:

tty agetty {
    command  = "/sbin/agetty -L ttyAMA0 115200 vt100"
    runlevel = "12345"
    nowait   = true
}

Board bring-up and rescue:

tty rescue {
    notty  = true
    rescue = true
}

term and baud apply only to the device form and are dropped for
an external getty. The booleans stay negative, matching agetty and
mingetty, which spell --noclear exactly this way and carry a whole
family of no flags between them. Two are worth knowing precisely:
nowait skips the "press Enter to activate" prompt, which Finit shows
by default where the gettys do not; and nologin runs a shell directly
rather than login, so it is stronger than agetty's --skip-login.

---

cgroup

Valid at top level, where it defines a group, and inside a service
block, where it joins one.

Common cgroup v2 keys are declared in the schema, so they are typed and
warning-free. Anything else is passed to the kernel verbatim, which is
what the legacy parser always did; the kernel rejects bad writes at
runtime. Consequence: a typo in a common key degrades to passthrough
rather than being caught.

Declared keys: cpu.weight, cpu.weight.nice, cpu.max,
cpu.max.burst, cpu.idle, cpuset.cpus, cpuset.mems,
memory.{min,low,high,max}, memory.swap.{high,max},
memory.oom.group, memory.zswap.max, io.{weight,max,latency},
pids.max.

cgroup system {
    cpu.weight      = 9800
    cpu.max         = "50000 100000"
    memory.max      = 65M
    hugetlb.2MB.max = 128M       # not declared, passed through
}

service acpid {
    cgroup system { cpu.weight = 250 }   # join, with an override
    command = "/usr/sbin/acpid -f"
}

service dropbear {
    cgroup user {}                       # join, no overrides
    command = "/usr/sbin/dropbear -F"
}

The keys are the cgroupfs filenames, so the config reads the same as
the kernel documentation. Dots are literal characters, not nesting.

A service joins exactly one group. If a block declares more than one
cgroup section the last wins and a warning names the one used.

The legacy cgroup.NAME context-switch line, meaning "every following
stanza joins NAME", has no block equivalent. Each block says which
group it joins.

---

rlimit

Valid at top level, where it applies to every block in the file, and
inside a service block, where it applies to that block only, layered on
the file-scope values.

Unlike cgroup keys the resource set is closed, it is the kernel ABI, so
the schema declares all of them and a typo is a hard parse error. Each
resource can be written bare, or with a soft. or hard. prefix. Bare
sets both.

Resources: as, core, cpu, data, fsize, locks, memlock,
msgqueue, nice, nofile, nproc, rss, rtprio, rttime,
sigpending, stack.

Values are a number, or unlimited (infinity also works).

rlimit {
    nofile      = 1024        # both soft and hard
    soft.nofile = 512
    hard.core   = unlimited
}

service bigmem {
    rlimit { memlock = unlimited }
    command = "/usr/bin/bigmem"
}

---

Templates

A file named name@.conf is a template. It is never started on its
own; enabling an instance creates name@INSTANCE.conf pointing at it,
and every %i is replaced with INSTANCE before the file is parsed.
Substitution happens over the whole file, so %i works in the section
title, in any value, and in the command line alike.

# /etc/finit.d/available/avahi-autoipd@.conf
service avahi-autoipd:%i {
    description = "ZeroConf for %i"
    envfile     = "-/etc/default/avahi-autoipd-%i"
    command     = "avahi-autoipd $AVAHI_AUTOIPD_ARGS %i"
    pidfile     = "/run/avahi-autoipd.%i.pid"
}

$ initctl enable avahi-autoipd@eth0.conf
$ initctl status avahi-autoipd:eth0

The instance name becomes the service :ID, so it is bounded by
MAX_ID_LEN. A bare name@.conf reaching the parser registers
nothing. Diagnostics are reported against the instance file, so a typo
in the template above appears as
/etc/finit.d/enabled/avahi-autoipd@eth0.conf:2: ....

---

environment

Global environment variables, free-form keys. env is an accepted
alias, matching the envfile/env pair on services.

environment {
    DEBUG = "1"
    PATH  = "/usr/sbin:/usr/bin:/sbin:/bin"
}

Read on every reload, not only at bootstrap. That matters because
conf_reset_env() clears all tracked variables at the start of each
reload, and entering the configured runlevel triggers one; gating the
block on bootstrap would drop every variable on the way out of runlevel
S. Matches doc/config/env.md.

Variables are global and shared by all services. For a service-local
environment use the per-service envfile key, which sources a file.

---

log

Rotation of Finit's own log, not service output. Always evaluated, not
bootstrap-gated. Shares its name with the per-service log {} block
deliberately; the two sit at different levels and more global log
settings are expected here.

log {
    size  = "200k"     # accepts k/M suffixes
    count = 5
}

---

Top-level directives

Everything below sits at file scope, outside any block.

Evaluated only at bootstrap

Key	Alias	Type	Meaning
hostname		string	System hostname; /etc/hostname still wins
modules	mod	list	Kernel modules to load
mknod		list	Device nodes to create
network		string	Script to bring up networking
rcsd		string	Override the finit.d directory
runparts		string	Directory of start scripts to run
runparts-progress		bool	Show progress for runparts
runparts-sysv		bool	Treat runparts scripts as SysV
runlevel		int	Runlevel to enter after bootstrap, 1-9 except 6
readiness		string	Only "none" is acted on

hostname = "anarchy"
runlevel = 2
modules  = { "loop", "dummy" }
mknod    = { "/dev/null c 1 3" }
network  = "/etc/network/start.sh"
runparts = "/etc/rc.d"

An out-of-range runlevel silently falls back to 2 rather than
erroring.

modules entries go to kmod_load(), which skips already-loaded
modules and shells out to modprobe; arguments after the module name
are passed along. mknod entries are concatenated onto a mknod
command and run interactively.

Evaluated on every reload

Key	Alias	Type	Meaning
shutdown		string	Script to run on shutdown
reboot-delay		int	Seconds to wait before reboot, 0-60
reboot-watchdog		bool	Reboot via the watchdog instead of the SoC
service-interval		int	Seconds between service checks, 0-1440

shutdown         = "/etc/shutdown.sh"
reboot-delay     = 5
reboot-watchdog  = true
service-interval = 300

Out-of-range values are ignored, leaving the previous value in place.

---

Worked example: a complete finit.conf

# Bootstrap
hostname = "anarchy"
runlevel = 2
modules  = { "loop" }

environment {
    PATH = "/usr/sbin:/usr/bin:/sbin:/bin"
}

log {
    size  = "200k"
    count = 5
}

rlimit {
    nofile = 8192
}

cgroup system {
    cpu.weight = 9800
    memory.max = 512M
}

tty console {
    device   = "@console"
    runlevel = "12345"
    noclear  = true
}

run kmap {
    description = "Loading keymap"
    runlevel    = "S"
    envfile     = "/etc/conf.d/loadkmap"
    command     = "/usr/bin/loadkeys sv-latin1"
}

service syslogd {
    description = "Syslog daemon"
    runlevel    = "S12345"
    envfile     = "-/etc/default/rsyslog"
    command     = "/usr/sbin/rsyslogd -n $RSYSLOGD_OPTIONS"
}

service sshd {
    description = "OpenSSH daemon"
    runlevel    = "2345"
    conditions  = { "net/route/default" }
    pidfile     = "/run/sshd.pid"

    exec-start-pre         = "/etc/ssh/pre.sh"
    exec-start-pre-timeout = 10

    log { file = "/var/log/sshd.log"  priority = "daemon.info" }
    cgroup system { cpu.weight = 100 }
    command = "/usr/sbin/sshd -D"
}

---

Per-service directories

The five *-dir keys mirror systemd's RuntimeDirectory= family. The
value is a name resolved under a fixed base, absolute paths and ..
are refused. The directory is created before each start, mode 0755,
chowned to user/group, and its full path is exported to the process
as RUNTIME_DIRECTORY, STATE_DIRECTORY, CACHE_DIRECTORY,
LOGS_DIRECTORY, or CONFIGURATION_DIRECTORY. Only the runtime
directory is removed when the unit stops (after exec-stop-post); a
completed non-remain run/task counts as stopped.

Each takes a -mode suffix key (octal, leading zero, default 0755),
and runtime-dir-preserve = "no" | "restart" | "yes" maps systemd's
RuntimeDirectoryPreserve=. config-dir is created but never
chowned, like systemd. An existing dir with the right owner is left
alone; on mismatch the tree is chowned back recursively.

These are the first block-only settings: no legacy token exists, the
values are set on the svc after service_register() returns it.
systemd accepts multiple directories per setting; these are scalar for
now, widening later is syntax-compatible since libconfuse accepts a
bare value for a list option.

Gaps worth knowing

initctl show does not print the translated line. It is an alias for
cat, so for a block-format service it prints the block. The plan
assumed otherwise, which means the "declare the same service in both
formats and compare the output" check it describes cannot be done
today. The translated one-liner is visible only with finit.debug=on,
as a translated: line.

Emitted one-liners are verified by reading and by that debug output,
not by the test suite. Three have been wrong so far: cgroup:NAME,
which parse_cgroup() reads as a settings string so the group was
never joined; cgroup.NAME:settings, whose separator has to be a
comma; and a nowarn that landed on the wrong service after a
refactor. All three are fixed, and the last one passed the whole test
suite before the debug output caught it.

Cgroups are untested. cgroup_avail() is false inside the test
namespace, so the suite cannot assert that a group was joined.

On libconfuse 3.3 each free-form cgroup key logs one spurious warning.
Values are captured correctly, only the logging differs, and Finit's
error callback absorbs it. Gone in 3.4.

doc/config/service-opts.md still documents stop:'script' without a
timeout. Both exec-stop and exec-reload now take one, so that page
is out of date.

---

Future

A persist flag for run/tasks whose only runlevel is S. Those are
pruned once bootstrap finishes, so a user in a normal runlevel cannot
see that they ran at all, and remain-after-exit cannot help because
there is nothing left by then. persist would keep the entry alive
past the prune purely so it stays inspectable.

[troglobit]

@aanderse if you could spare a minute or so, skimming through the PR description at least, that would be very appreciated! 🙇‍♂️

[aanderse]

this is fantastic! i am really happy with what you did here 😁 and all these wonderful new options! somehow you keep adding so much great stuff while really hitting that perfect balance with simplicity 🤩

this format matches what i had with finix already so porting over wasn't that hard. happy to report my laptop is running fine on this branch as of tonight 🚀

PR description is fantastic and all i needed to migrate everything i had 👍

really looking forward to this being merged!

[troglobit]

this is fantastic! i am really happy with what you did here 😁 and all these wonderful new options! somehow you keep adding so much great stuff while really hitting that perfect balance with simplicity 🤩

Thank you for those kind words, I really appreciate that! 😊

this format matches what i had with finix already so porting over wasn't that hard. happy to report my laptop is running fine on this branch as of tonight 🚀

Wow, that was quick! 🤯

PR description is fantastic and all i needed to migrate everything i had 👍

I'll put together a migration guide later on, thank you for the idea!

really looking forward to this being merged!

Going in now!