configure: keep the replacement libsystemd opt-in

Building it by default installs our libsystemd.so.0 in $libdir.  Where
the real one is already present, and contrib/debian/build.sh configures
--prefix=/usr --exec-prefix= on a Debian host, ours outranks it in the
loader cache, and every program linking libsystemd loses
sd_journal_stream_fd and the LIBSYSTEMD_209 symbol versions.  The test
sysroot ran into exactly that, dbus-daemon exited 127 on every restart.

Restore the default to no.  sulogin and watchdogd stay on, they only add
binaries.  distcheck asks for the library so it stays covered.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

.github/CONTRIBUTING.md

@@ -20,7 +20,6 @@ Please take care to ensure you follow the project coding style and the
 commit message format.  If you follow these recommendations you help
 the maintainer(s) and make it easier for them to include your code.
 
-
 Coding Style
 ------------
 
@@ -31,8 +30,7 @@ First of all, lines are allowed to be longer than 72 characters these
 days.  In fact, there exist no enforced maximum, but keeping it around
 100 chars is OK.
 
-The coding style itself is strictly Linux [KNF][].
-
+The coding style itself is strictly [Linux coding style][KNF].
 
 Commit Messages
 ---------------
@@ -41,31 +39,38 @@ Commit messages exist to track *why* a change was made.  Try to be as
 clear and concise as possible in your commit messages, and always, be
 proud of your work and set up a proper GIT identity for your commits:
 
-    git config --global user.name "Jane Doe"
-    git config --global user.email jane.doe@example.com
+```bash
+$ git config --global user.name "Jane Doe"
+$ git config --global user.email jane.doe@example.com
+```
 
 Example commit message from the [Pro Git][gitbook] online book, notice
 how `git commit -s` is used to automatically add a `Signed-off-by`:
 
-    Brief, but clear and concise summary of changes
-    
-    More detailed explanatory text, if necessary.  Wrap it to about 72
-    characters or so.  In some contexts, the first line is treated as
-    the subject of an email and the rest of the text as the body.  The
-    blank line separating the ummary from the body is critical (unless
-    you omit the body entirely); tools like rebase can get confused if
-    you run the two together.
-    
-    Further paragraphs come after blank lines.
-    
-     - Bullet points are okay, too
-    
-     - Typically a hyphen or asterisk is used for the bullet, preceded
-       by a single space, with blank lines in between, but conventions
-       vary here
-    
-    Signed-off-by: Jane Doe <jane.doe@example.com>
+```
+Brief, but clear and concise summary of changes
 
+More detailed explanatory text, if necessary.  Remember, a future
+reader has the diff and can see what it does, the commit message in
+itself should usually talk about the *why* of a change and/or any
+technical limitations and future work.
+
+Wrap the text to about 72 characters or so.  In some contexts, the
+first line is treated as the subject of an email and the rest of the
+text as the body.  The blank line separating the summary from the body
+is critical (unless you omit the body entirely); tools like rebase can
+get confused if you run the two together.
+
+Further paragraphs come after blank lines.
+
+ - Bullet points are okay, too
+
+ - Typically a hyphen or asterisk is used for the bullet, preceded
+   by a single space, with blank lines in between, but conventions
+   vary here
+
+Signed-off-by: Jane Doe <jane.doe@example.com>
+```
 
 Code of Conduct
 ---------------
@@ -73,7 +78,6 @@ Code of Conduct
 It is expected of everyone engaging in the project to, in the words of
 Bill & Ted; [be excellent to each other][conduct].
 
-
-[KNF]:      https://en.wikipedia.org/wiki/Kernel_Normal_Form
-[gitbook]:  https://git-scm.com/book/ch5-2.html
+[KNF]:      https://www.kernel.org/doc/html/v5.8/process/coding-style.html
+[gitbook]:  https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines
 [conduct]:  CODE-OF-CONDUCT.md

.github/SECURITY.md

@@ -5,7 +5,7 @@
 finit is a small project, as such we have no possibility to support older versions.
 The only supported version is the latest released on GitHub:
 
-<https://github.com/troglobit/finit/releases>
+<https://github.com/finit-project/finit/releases>
 
 ## Reporting a Vulnerability
 

.github/workflows/build.yml

@@ -8,14 +8,87 @@ on:
       - '**'
       - '!dev'
   pull_request:
-    branches:
-      - '**'
+    types: [opened, synchronize, reopened, labeled]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
 
 jobs:
+  fuzz:
+    name: fuzz
+    runs-on: ubuntu-latest
+    if: github.event_name != 'push' || github.ref == 'refs/heads/master'
+    steps:
+      - name: Install dependencies
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install pkg-config libconfuse-dev clang libblkid-dev
+          # clang picks the newest gcc tree it finds and needs the
+          # matching libstdc++ headers to link the fuzzer runtime
+          sudo apt-get -y install libstdc++-14-dev || true
+          wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
+          wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
+          tar xf libuev-2.4.1.tar.xz
+          tar xf libite-2.6.2.tar.gz
+          (cd libuev-2.4.1 && ./configure && make -j9 && sudo make install-strip)
+          (cd libite-2.6.2 && ./configure && make -j9 && sudo make install-strip)
+          sudo ldconfig
+      - uses: actions/checkout@v7
+      - name: Configure
+        run: |
+          ./autogen.sh
+          ./configure --prefix=/usr --exec-prefix= --sysconfdir=/etc --localstatedir=/var
+      - name: Build fuzz target
+        run: |
+          clang -fsanitize=fuzzer,address -DLINK_FUZZ_LIBFUZZER -D_GNU_SOURCE \
+                -I libink -I . -o fuzz-msg-parse                              \
+                test/src/fuzz-msg-parse.c libink/*.c
+      # Restores the newest corpus and saves a fresh one, since a cache
+      # entry is immutable once written.  Caches made on a branch are
+      # private to it, so the corpus that accumulates on master is what
+      # pull requests start from, rather than nothing.
+      - name: Restore corpus
+        uses: actions/cache@v6
+        with:
+          path: .fuzz-corpus
+          key: fuzz-corpus-${{ github.run_id }}
+          restore-keys: fuzz-corpus-
+      - name: Fuzz
+        run: |
+          mkdir -p .fuzz-corpus
+          ./fuzz-msg-parse .fuzz-corpus -max_total_time=120 -max_len=4096 \
+                           -print_final_stats=1
+      # Without this the corpus only ever grows, and most of what it
+      # accumulates reaches code some earlier input already reached.
+      - name: Minimise corpus
+        if: always()
+        run: |
+          mkdir -p .fuzz-corpus-min
+          ./fuzz-msg-parse -merge=1 .fuzz-corpus-min .fuzz-corpus
+          rm -rf .fuzz-corpus
+          mv .fuzz-corpus-min .fuzz-corpus
+          echo "corpus: $(ls .fuzz-corpus | wc -l) inputs"
+      - name: Upload crashers
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: fuzz-crashers
+          path: |
+            crash-*
+            leak-*
+            timeout-*
+          if-no-files-found: ignore
+
   build:
     # Verify we can build on latest Ubuntu with both gcc and clang
     name: ${{ matrix.compiler }}
     runs-on: ubuntu-latest
+    # Skip redundant builds for PRs - prefer PR builds over push builds
+    if: github.event_name != 'push' || github.ref == 'refs/heads/master'
     strategy:
       matrix:
         compiler: [gcc, clang]
@@ -26,20 +99,27 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get -y update
-          sudo apt-get -y install pkg-config tree jq libuev-dev libite-dev
-      - uses: actions/checkout@v4
+          sudo apt-get -y install pkg-config tree jq libcap-dev libconfuse-dev libblkid-dev
+          wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
+          wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
+          tar xf libuev-2.4.1.tar.xz
+          tar xf libite-2.6.2.tar.gz
+          (cd libuev-2.4.1 && ./configure && make -j9 && sudo make install-strip)
+          (cd libite-2.6.2 && ./configure && make -j9 && sudo make install-strip)
+          sudo ldconfig
+      - uses: actions/checkout@v7
       - name: Static Finit
         run: |
           ./autogen.sh
           ./configure --prefix= --enable-static
-          make -j3 V=1
+          make -j9 V=1
       - name: Regular Finit
         run: |
           ./configure --prefix=/usr --exec-prefix= --sysconfdir=/etc --localstatedir=/var \
-                      --enable-x11-common-plugin --enable-testserv-plugin --with-watchdog \
-                      --with-keventd
-          make -j3 clean
-          make -j3 V=1
+                      --enable-x11-common-plugin --enable-testserv-plugin \
+                      CFLAGS="-fsanitize=address -ggdb"
+          make -j9 clean
+          make -j9 V=1
       - name: Install to /tmp
         run: |
           DESTDIR=/tmp make install-strip
@@ -61,9 +141,49 @@ jobs:
           sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
       - name: Run Unit Tests
         run: |
-          make check || (cat test/test-suite.log; false)
+          make -j1 check || (cat test/test-suite.log; false)
       - name: Upload Test Results
-        uses: actions/upload-artifact@v4
+        if: always()
+        uses: actions/upload-artifact@v7
         with:
           name: finit-test-${{ matrix.compiler }}
           path: test/*.log
+
+  no-dbus:
+    # The D-Bus support is default-enabled, so the HAVE_DBUS paths in
+    # initctl and finit only bit-rot silently without this leg.
+    name: no-dbus
+    runs-on: ubuntu-latest
+    if: github.event_name != 'push' || github.ref == 'refs/heads/master'
+    steps:
+      - name: Install dependencies
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install pkg-config tree jq libcap-dev libconfuse-dev libblkid-dev
+          wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
+          wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
+          tar xf libuev-2.4.1.tar.xz
+          tar xf libite-2.6.2.tar.gz
+          (cd libuev-2.4.1 && ./configure && make -j9 && sudo make install-strip)
+          (cd libite-2.6.2 && ./configure && make -j9 && sudo make install-strip)
+          sudo ldconfig
+      - uses: actions/checkout@v7
+      - name: Build without D-Bus
+        run: |
+          ./autogen.sh
+          ./configure --prefix=/usr --exec-prefix= --sysconfdir=/etc --localstatedir=/var \
+                      --disable-dbus --enable-testserv-plugin
+          make -j9 V=1
+      - name: Verify no bus artifacts
+        run: |
+          DESTDIR=/tmp make install-strip
+          ! strings /tmp/sbin/initctl | grep -q finit/bus
+          ! strings /tmp/sbin/finit   | grep -q org.finit
+      - name: Enable unprivileged userns (unshare)
+        run: |
+          sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
+      - name: Smoke test
+        run: |
+          make -C test setup-chroot
+          make -j1 -C test check TESTS='start-stop-serv.sh' \
+              || (cat test/test-suite.log; false)

.github/workflows/coverity.yml

@@ -6,6 +6,9 @@ on:
       - 'dev'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 env:
   PROJECT_NAME: finit
   CONTACT_EMAIL: troglobit@gmail.com
@@ -16,7 +19,7 @@ jobs:
   coverity:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Fetch latest Coverity Scan MD5
         id: var
         env:
@@ -26,7 +29,7 @@ jobs:
                --post-data "token=$TOKEN&project=${COVERITY_PROJ}&md5=1" \
                -O coverity-latest.tar.gz.md5
           echo "md5=$(cat coverity-latest.tar.gz.md5)" | tee -a $GITHUB_OUTPUT
-      - uses: actions/cache@v4
+      - uses: actions/cache@v6
         id: cache
         with:
           path: coverity-latest.tar.gz
@@ -52,18 +55,18 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get -y update
-          sudo apt-get -y install pkg-config
-          wget https://github.com/troglobit/libuev/releases/download/v2.4.0/libuev-2.4.0.tar.xz
-          wget https://github.com/troglobit/libite/releases/download/v2.5.2/libite-2.5.2.tar.gz
-          tar xf libuev-2.4.0.tar.xz
-          tar xf libite-2.5.2.tar.gz
-          (cd libuev-2.4.0 && ./configure --prefix=/usr && make && sudo make install-strip)
-          (cd libite-2.5.2 && ./configure --prefix=/usr && make && sudo make install-strip)
+          sudo apt-get -y install pkg-config libcap-dev libconfuse-dev libblkid-dev
+          wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
+          wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
+          tar xf libuev-2.4.1.tar.xz
+          tar xf libite-2.6.2.tar.gz
+          (cd libuev-2.4.1 && ./configure && make -j9 && sudo make install-strip)
+          (cd libite-2.6.2 && ./configure && make -j9 && sudo make install-strip)
           sudo ldconfig
       - name: Configure
         run: |
           ./autogen.sh
-          ./configure --prefix= --enable-x11-common-plugin --with-watchdog --with-keventd
+          ./configure --prefix= --enable-x11-common-plugin
       - name: Build
         run: |
           export PATH=`pwd`/coverity/bin:$PATH
@@ -82,7 +85,7 @@ jobs:
             --form description="${PROJECT_NAME} $(git rev-parse HEAD)" \
             https://scan.coverity.com/builds?project=${COVERITY_PROJ}
       - name: Upload build.log
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverity-build.log
           path: cov-int/build-log.txt

.github/workflows/docs.yml

@@ -0,0 +1,163 @@
+name: Dotty the Documenteer
+
+on:
+  push:
+    branches:
+      - master
+      - 4.x
+    paths:
+      - 'doc/**'
+      - 'README.md'
+      - 'mkdocs.yml'
+      - 'configure.ac'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+    paths:
+      - 'doc/**'
+      - 'README.md'
+      - 'mkdocs.yml'
+      - 'configure.ac'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # Needed for git-revision-date-localized plugin
+
+      - name: Determine docs version
+        id: version
+        run: |
+          version=$(sed -n 's/^AC_INIT(\[Finit\], *\[\([0-9]*\)\..*/\1.x/p' configure.ac)
+          test -n "$version"
+          echo "version=$version" >> $GITHUB_OUTPUT
+
+      - name: Setup Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          pipx install mkdocs
+          pipx inject mkdocs mkdocs-material
+          pipx inject mkdocs pymdown-extensions
+          pipx inject mkdocs mkdocs-callouts
+          pipx inject mkdocs mkdocs-glightbox
+
+      - name: Build documentation
+        run: mkdocs build --clean
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: site
+          path: site/
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+
+    steps:
+      - name: Download site artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: site
+          path: site/
+
+      - name: Checkout pages repo
+        uses: actions/checkout@v7
+        with:
+          repository: finit-project/finit-project.github.io
+          path: pages
+          ssh-key: ${{ secrets.DOCS_DEPLOY_KEY }}
+          persist-credentials: true
+
+      - name: Setup SSH for push
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+
+      - name: Sync site to pages repo
+        run: |
+          rsync -a --delete site/ "pages/$VERSION/"
+
+      - name: Update version index and redirects
+        run: |
+          cd pages/
+
+          # The root holds only version directories and the files
+          # generated below, drop anything else (pre-versioned site)
+          find . -maxdepth 1 ! -name . ! -name .git ! -name CNAME \
+               ! -name '[0-9]*.x' -exec rm -rf {} +
+
+          latest=$(ls -d [0-9]*.x | sort -rV | head -1)
+
+          sep=
+          printf '[' > versions.json
+          for v in $(ls -d [0-9]*.x | sort -rV); do
+              printf '%s{"version": "%s", "title": "%s", "aliases": []}' \
+                     "$sep" "$v" "$v" >> versions.json
+              sep=', '
+          done
+          printf ']\n' >> versions.json
+
+          cat > index.html <<EOF
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <meta http-equiv="refresh" content="0; url=$latest/">
+              <link rel="canonical" href="https://finit-project.github.io/$latest/">
+            </head>
+          </html>
+          EOF
+
+          cat > 404.html <<EOF
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <title>Finit &mdash; page not found</title>
+              <script>
+                var path = window.location.pathname;
+                if (!/^\/[0-9]+\.x(\/|$)/.test(path))
+                  window.location.replace("/$latest" + path);
+              </script>
+            </head>
+            <body>
+              <p>Page not found.  Try the <a href="/$latest/">latest User Guide</a>.</p>
+            </body>
+          </html>
+          EOF
+
+      - name: Commit and push
+        run: |
+          cd pages/
+          if [ -z "$(git status --porcelain)" ]; then
+              exit 0
+          fi
+
+          SRC_REPO="${GITHUB_REPOSITORY}"
+          SRC_REF="${GITHUB_SHA::7}"
+          SRC_URL="https://github.com/${SRC_REPO}/commit/${SRC_REF}"
+
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+          git add -A
+          git commit -m "docs: update from ${SRC_REPO}@${SRC_REF}" \
+                     -m "For details, see ${SRC_URL}"
+          git push

.github/workflows/release.yml

@@ -5,19 +5,27 @@ on:
     tags:
       - '[0-9]+.[0-9]+*'
 
+permissions:
+  contents: write
+
 jobs:
   release:
     name: Build and upload release tarball
     if: startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
-    env:
-      MAKEFLAGS: -j3
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Installing dependencies ...
         run: |
           sudo apt-get -y update
-          sudo apt-get -y install pkg-config jq libuev-dev libite-dev
+          sudo apt-get -y install pkg-config jq libcap-dev libconfuse-dev libblkid-dev
+          wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
+          wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
+          tar xf libuev-2.4.1.tar.xz
+          tar xf libite-2.6.2.tar.gz
+          (cd libuev-2.4.1 && ./configure && make -j9 && sudo make install-strip)
+          (cd libite-2.6.2 && ./configure && make -j9 && sudo make install-strip)
+          sudo ldconfig
       - name: Setting release variables ...
         id: build
         run: |
@@ -36,21 +44,32 @@ jobs:
       - name: Creating Makefiles ...
         run: |
           ./autogen.sh
-          ./configure  --prefix=/usr --exec-prefix= --sysconfdir=/etc --localstatedir=/var \
-                       --enable-x11-common-plugin --enable-testserv-plugin --with-watchdog \
-                       --with-keventd
+          ./configure  --prefix=/usr --exec-prefix= --sysconfdir=/etc  \
+                       --localstatedir=/var --enable-x11-common-plugin \
+                       --enable-testserv-plugin
       - name: Enable unprivileged userns (unshare)
         run: |
           sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
       - name: Build release ...
         run: |
-          make release || (cat test/test-suite.log; false)
+          # Get version for finding distcheck build directory
+          ./configure --version | head -1
+          ver=$(./configure --version | head -1 | awk '{print $NF}')
+          dir=finit-$ver/_build/sub
+
+          make -j1 release || (cat $dir/test/test-suite.log; false)
           ls -lF ../
           mkdir -p artifacts/
           mv ../*.tar.* artifacts/
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: finit-release-test-logs
+          path: finit-*/_build/sub/test/*.log
       - name: Extract ChangeLog entry ...
         run: |
-          awk '/-----*/{if (x == 1) exit; x=1;next}x' ChangeLog.md \
+          awk '/-----*/{if (x == 1) exit; x=1;next}x' doc/ChangeLog.md \
               |head -n -1 > release.md
           cat release.md
       - uses: ncipollo/release-action@v1

.github/workflows/weekly.yml

@@ -7,18 +7,21 @@ on:
     - cron: '0 0 * * 0'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   schedule:
     runs-on: ubuntu-latest
     outputs:
-      run: ${{ steps.check.outputs.run }}
+      run: ${{ steps.schedule.outputs.run }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Check for any commits since last week
         id: schedule
         run: |
           commits="$(git log --format=%H --since='1 week ago')"
-          if [ -n "$commits" ]; then
+          if [ -z "$commits" ]; then
               echo "run=true"  >> $GITHUB_OUTPUT
           else
               echo "run=false" >> $GITHUB_OUTPUT
@@ -31,8 +34,15 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get -y update
-          sudo apt-get -y install pkg-config jq libuev-dev libite-dev
-      - uses: actions/checkout@v4
+          sudo apt-get -y install pkg-config jq libcap-dev libconfuse-dev libblkid-dev
+          wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
+          wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
+          tar xf libuev-2.4.1.tar.xz
+          tar xf libite-2.6.2.tar.gz
+          (cd libuev-2.4.1 && ./configure && make -j9 && sudo make install-strip)
+          (cd libite-2.6.2 && ./configure && make -j9 && sudo make install-strip)
+          sudo ldconfig
+      - uses: actions/checkout@v7
       - name: Base run
         run: |
           ./autogen.sh
@@ -49,3 +59,9 @@ jobs:
           ver=$(/tmp/sbin/initctl -V | awk '/Finit.*/ {print $2;}')
           dir=finit-$ver/_build/sub
           make -j1 distcheck || (cat $dir/test/test-suite.log; false)
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: finit-weekly-test-logs
+          path: finit-*/_build/sub/test/*.log

.gitignore

@@ -52,3 +52,8 @@ GTAGS
 
 # VS Code user settings
 .vscode
+
+# Fuzzing: the target is built by hand with clang, see doc/build.md,
+# and the corpus it grows is a local artefact, not something to ship
+/fuzz-msg-parse
+/.fuzz-corpus/

.globalrc

@@ -1,7 +1,15 @@
 # GNU Global .conf file, see /etc/gtags/gtags.conf for details.
+# This configuration is optimized for the Finit project structure.
+
 default:\
 	:tc=default@/etc/gtags/gtags.conf:\
 	:tc=common:
 
 common:\
-	:skip=tags,TAGS,ID,y.tab.c,y.tab.h,gtags.files,cscope.files,cscope.out,cscope.po.out,cscope.in.out,,{arch}/,autom4te.cache/,*.orig,*.rej,*.bak,*~,#*#,*.swp,*.tmp,*_flymake.*,*_flymake,*.o,*.a,*.so,*.lo,*.zip,*.gz,*.bz2,*.xz,*.lzh,*.Z,*.tgz,*.min.js,*min.css,sysroot/:
+	:skip=tags,TAGS,ID,y.tab.c,y.tab.h,gtags.files,cscope.files,cscope.out,cscope.po.out,cscope.in.out,\
+	{arch}/,autom4te.cache/,\
+	*.orig,*.rej,*.bak,*~,#*#,*.swp,*.tmp,*_flymake.*,*_flymake,\
+	*.o,*.a,*.so,*.lo,*.la,\
+	*.zip,*.gz,*.bz2,*.xz,*.lzh,*.Z,*.tgz,\
+	*.log,*.trs,test-suite.log,stamp-*,\
+	sysroot/:

LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2008-2010  Claudio Matsuoka <cmatsuoka@gmail.com>
-Copyright (c) 2008-2024  Joachim Wiberg <troglobit@gmail.com>
+Copyright (c) 2008-2025  Joachim Wiberg <troglobit@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile.am

@@ -1,7 +1,22 @@
 ACLOCAL_AMFLAGS    = -I m4
-SUBDIRS            = man plugins src system test tmpfiles.d
-doc_DATA           = README.md LICENSE contrib/finit.conf
-EXTRA_DIST         = README.md LICENSE ChangeLog.md contrib/finit.conf
+
+# libink must precede src in SUBDIRS because finit links against
+# libink at build time.  Automake recurses subdirs strictly in
+# declaration order, so the typical "explicit dependency" pattern
+# (foo: bar) doesn't help here — ordering is the only thing that
+# does.  libsystemd is consumed by test/serv only, so its position
+# after src is fine.
+SUBDIRS            = man plugins
+if DBUS
+SUBDIRS           += libink dbus-1
+endif
+SUBDIRS           += src system tmpfiles.d
+
+if KEVENTD
+SUBDIRS           += keventd
+endif
+
+dist_doc_DATA      = README.md LICENSE contrib/finit.conf
 
 if CONTRIB
 SUBDIRS           += contrib
@@ -9,15 +24,29 @@ endif
 if DOC
 SUBDIRS           += doc
 endif
-
-if BASH
-bashdir            = $(BASH_DIR)
-dist_bash_DATA     = initctl
+if LIBSYSTEMD
+SUBDIRS           += libsystemd
 endif
+
+if LIBSYSTEMD
+SUBDIRS           += test
+# Explicit dependency to ensure libsystemd is built before test
+test: libsystemd
+else
+SUBDIRS           += test
+endif
+
 # Compat hook
 install-dev:
 	@make -C src install-pkgincludeHEADERS
 
+# The fuzz target is built by hand with clang (doc/build.md), so it is
+# not in any _PROGRAMS and nothing else would clear it or the corpus
+# it grows.
+distclean-local:
+	-rm -f  $(top_builddir)/fuzz-msg-parse
+	-rm -rf $(top_builddir)/.fuzz-corpus
+
 # Target to run when building a release
 release: distcheck
 	@for file in $(DIST_ARCHIVES); do		\
@@ -34,7 +63,7 @@ release: distcheck
 		printf "$$file.sha256\t"; cat ../$$file.sha256 | cut -f1 -d' ';	\
 	done
 
-DISTCHECK_CONFIGURE_FLAGS = --prefix=/usr --sysconfdir=/etc --localstatedir=/var   \
-			    --enable-testserv-plugin --enable-x11-common-plugin    \
-			    --with-watchdog --with-keventd --with-fstab=/etc/fstab \
+DISTCHECK_CONFIGURE_FLAGS = --prefix=/usr --sysconfdir=/etc --localstatedir=/var \
+			    --enable-testserv-plugin --enable-x11-common-plugin  \
+			    --with-fstab=/etc/fstab --with-libsystemd            \
 			    --with-bash-completion-dir=no

README.md

@@ -1,724 +1,50 @@
-[![License Badge][]][License] [![GitHub Status][]][GitHub] [![Coverity Status][]][Coverity Scan]
-<img align="right" src="img/finit3.png" alt="Finit: Fast Init">
+[![License Badge][]][License] [![Release Badge][]][Release] [![GitHub Status][]][GitHub] [![Coverity Status][]][Coverity Scan]
+<img align="right" src="doc/img/finit3.png" alt="Finit: Fast Init">
 
-* [Introduction](#introduction)
-* [Features](#features)
-* [Runlevels](#runlevels)
-* [Syntax](doc/config.md#syntax)
-  * [Runparts & /etc/rc.local](#runparts--etcrclocal)
-  * [Hooks, Callbacks & Plugins](doc/plugins.md#hooks-callbacks--plugins)
-* [Rebooting & Halting](#rebooting--halting)
-* [Commands & Status](#commands--status)
-* [Tips & Tricks with the kernel cmdline](doc/cmdline.md)
-* [Building](doc/build.md#building)
-  * [Running](doc/build.md#running)
-  * [Recovery](doc/build.md#recovery)
-  * [Debugging](doc/build.md#debugging)
-* [Requirements](#requirements)
-* [Origin & References](#origin--references)
+Finit is a fast, simple alternative to [SysV init](https://en.wikipedia.org/wiki/Init)
+and [systemd](https://systemd.io), designed for small and embedded Linux systems.
+It can also run on desktop and server systems, like [finix][].
 
+> Reverse engineered from the [EeePC fastinit][]  
+> "gaps filled with frog DNA …"  
+> — [Claudio Matsuoka][]
 
-Introduction
-------------
+For detailed information, explore our extensive documentation  
+:books: **<http://finit-project.github.io>**
 
-Fast init for Linux systems.  Reverse engineered from the [EeePC
-fastinit][] by [Claudio Matsuoka][] — "gaps filled with frog DNA …"
+<div align="center">
+  <img src="doc/img/alpine-screenshot2.png" alt="Alpine screenshot"><br/>
+</div>
 
-![Alpine screenshot](img/alpine-screenshot2.png)  
-*Figure 1: Screenshot of Finit booting [Alpine Linux (HowTo)](https://github.com/troglobit/finit/tree/master/contrib/alpine).*
+For working examples, see the :rocket: [contrib/](contrib/) section or these
+tutorials:
 
-Features include:
-
-  * Runlevels, defined per service
-  * One-shot tasks, services (daemons), or [SysV init][4] start/stop scripts
-  * Runparts and `/etc/rc.local` support
-  * Process supervision similar to [systemd][]
-  * Sourcing environment files
-  * Conditions for network/process/custom dependencies
-  * Readiness notification; PID files (native) for synchronizing system
-    startup, support for systemd [sd_notify()][], or [s6 style][] too
-  * Limited support for [tmpfiles.d(5)][] (no aging, attributes, or subvolumes)
-  * Pre/Post script actions
-  * Rudimentary [templating support](doc/config.md#templating)
-  * Tooling to enable/disable services
-  * Built-in getty
-  * Built-in watchdog, with support for hand-over to [watchdogd](https://troglobit.com/watchdogd.html)
-  * Built-in support for Debian/BusyBox `/etc/network/interfaces`
-  * Cgroups v2, both configuration and monitoring in `initctl top`
-  * Plugin support for customization
-  * Proper rescue mode with bundled `sulogin` for protected maintenance shell
-  * Integration with [watchdogd][] for full system supervision
-  * Logging to kernel ring buffer before `syslogd` has started, see the
-    recommended [sysklogd][] project for complete logging integration
-	and how to log to the kernel ring buffer from scripts using `logger`
-
-Focus is on small and embedded systems, although Finit is fully usable
-on server and desktop systems as well.  For working examples, see the
-[contrib/](contrib/) section with tutorials for the following Linux
-distributions:
-
-  * [Void Linux](contrib/void/),
-  * [Alpine Linux](contrib/alpine/), and
-  * [Debian GNU/Linux](contrib/debian/), also works on Ubuntu/Linux Mint
+* :hammer_and_wrench: [Buildroot embedded Linux][br2demo],
+* :package: [Debian GNU/Linux](contrib/debian/),
+* :mountain: [Alpine Linux](contrib/alpine/), and
+* :milky_way: [Void Linux](contrib/void/)
 
 > [!NOTE]
-> Support for various Linux distributions does not mean Finit installs
-> easily on all architectures.  The bundled install scripts are examples
-> for standard installations, tested on amd64 (x86_64) systems.  Custom
-> setups, e.g., for embedded systems, can be found in the following
-> [Buildroot][] based examples: [myLinux][], [Infix][], or the plain
-> [br2-finit-demo](https://github.com/troglobit/br2-finit-demo).
-
-
-Example
--------
-
-This example `/etc/finit.conf` can also be split up in multiple `.conf`
-files in `/etc/finit.d`.  Available, but not yet enabled, services can
-be placed in `/etc/finit.d/available` and enabled by an operator using
-the [initctl](#commands--status) tool.  See the above mentioned Linux
-distributions, or [myLinux][].
-
-> [!TIP]
-> As of Finit v4.4, `.conf` lines can be broken up using the standard
-> UNIX continuation character (`\`), trailing comments are now also
-> supported.  The latter means you need to escape any hashes used in
-> directives and descriptions (`\#`).  For more on this and examples,
-> see the [finit.conf(5)][] manual or [doc/config.md](doc/config.md).
-
-```ApacheConf
-# Fallback if /etc/hostname is missing
-host default
-
-# Runlevel to start after bootstrap, 'S', default: 2
-#runlevel 2
-
-# Support for setting global environment variables, using foo=bar syntax
-# be careful though with variables like PATH, SHELL, LOGNAME, etc.
-#PATH=/usr/bin:/bin:/usr/sbin:/sbin
-
-# Max file size for each log file: 100 kiB, rotate max 4 copies:
-# log => log.1 => log.2.gz => log.3.gz => log.4.gz
-log size=100k count=4
-
-# Services to be monitored and respawned as needed
-service [S12345] env:-/etc/conf.d/watchdog watchdog $WATCHDOG_OPTS $WATCHDOG_DEV -- System watchdog daemon
-service [S12345] env:-/etc/conf.d/syslog syslogd -n $SYSLOGD_OPTS          -- System log daemon
-service [S12345] <pid/syslogd> env:-/etc/conf.d/klogd klogd -n $KLOGD_OPTS -- Kernel log daemon
-service   [2345] env:-/etc/conf.d/lldpd lldpd -d $LLDPD_OPTS               -- LLDP daemon (IEEE 802.1ab)
-
-# The BusyBox ntpd does not use syslog when running in the foreground
-# So we use this trick to redirect stdout/stderr to a log file.  The
-# log file is rotated with the above settings.  The condition declares
-# a dependency on a system default route (gateway) to be set.  A single
-# <!> at the beginning means ntpd does not respect SIGHUP for restart.
-service [2345] log:/var/log/ntpd.log <!net/route/default> ntpd -n -l -I eth0 -- NTP daemon
-
-# For multiple instances of the same service, add :ID somewhere between
-# the service/run/task keyword and the command.
-service :80   [2345] merecat -n -p 80   /var/www -- Web server
-service :8080 [2345] merecat -n -p 8080 /var/www -- Old web server
-
-# Alternative method instead of below runparts, can also use /etc/rc.local
-#sysv [S] /etc/init.d/keyboard-setup       -- Setting up preliminary keymap
-#sysv [S] /etc/init.d/acpid                -- Starting ACPI Daemon
-#task [S] /etc/init.d/kbd                  -- Preparing console
-
-# Hidden from boot progress, using empty `--` description
-#sysv [S] /etc/init.d/keyboard-setup       --
-#sysv [S] /etc/init.d/acpid                --
-#task [S] /etc/init.d/kbd                  --
-
-# Run start scripts from this directory
-# runparts /etc/start.d
-
-# Virtual consoles run BusyBox getty, keep kernel default speed
-tty [12345] /sbin/getty -L 0 /dev/tty1  linux nowait noclear
-tty [2345]  /sbin/getty -L 0 /dev/tty2  linux nowait noclear
-tty [2345]  /sbin/getty -L 0 /dev/tty3  linux nowait noclear
-
-# Use built-in getty for serial port and USB serial
-#tty [12345] /dev/ttyAMA0 noclear nowait
-#tty [12345] /dev/ttyUSB0 noclear
-
-# Just give me a shell, I need to debug this embedded system!
-#tty [12345] console noclear nologin
-```
-
-The `service` stanza, as well as `task`, `run` and others are described
-in full in [doc/config.md](doc/config.md).  Here's a quick overview of
-some of the most common components needed to start a UNIX daemon:
-
-```
-service [LVLS] <COND> 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
-```
-
-Some components are optional: runlevel(s), condition(s) and description,
-making it easy to create simple start scripts and still possible for more
-advanced uses as well:
-
-    service /usr/sbin/sshd -D
-
-Dependencies are handled using [conditions](doc/conditions.md).  One of
-the most common conditions is to wait for basic networking to become
-available:
-
-    service <net/route/default> nginx -- High performance HTTP server
-
-Here is another example where we instruct Finit to not start BusyBox
-`ntpd` until `syslogd` has started properly.  Finit waits for `syslogd`
-to create its PID file, by default `/var/run/syslogd.pid`.
-
-    service [2345] log <!pid/syslogd> ntpd -n -N -p pool.ntp.org
-    service [S12345] syslogd -n -- Syslog daemon
-
-Notice the `log` keyword, BusyBox `ntpd` uses `stderr` for logging when
-run in the foreground.  With `log` Finit redirects `stdout` + `stderr`
-to the system log daemon using the command line `logger(1)` tool.
-
-A service, or task, can have multiple dependencies listed.  Here we wait
-for *both* `syslogd` to have started and basic networking to be up:
-
-    service [2345] log <pid/syslogd,net/route/default> ntpd -n -N -p pool.ntp.org
-
-If either condition fails, e.g. loss of networking, `ntpd` is stopped
-and as soon as it comes back up again `ntpd` is restarted automatically.
-
-**Note:** Make sure daemons *do not* fork and detach themselves from the
-  controlling TTY, usually an `-n` or `-f` flag, or `-D` as in the case
-  of OpenSSH above.  If it detaches itself, Finit cannot monitor it and
-  will instead try to restart it.
-
-
-Features
---------
-
-**Process Supervision**
-
-Start, monitor and restart services should they fail.
-
-
-**Getty**
-
-Finit supports external getty but also comes with a limited built-in
-Getty, useful for really small systems.  A getty sets up the TTY and
-waits for user input before handing over to `/bin/login`, which is
-responsible for handling the actual authentication.
-
-```conf
-tty [12345] /dev/tty1    nowait  linux
-tty [12345] /dev/ttyAMA0 noclear vt100
-tty [12345] /sbin/getty  -L /dev/ttyAMA0 vt100
-```
-
-Users of embedded systems may want to enable automatic serial console
-with 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`.
-
-```conf
-tty [12345] @console linux noclear
-```
-
-Notice the optional `noclear`, `nowait`, and `nologin` flags.  The
-latter is for skipping the login process entirely. For more information,
-see [doc/config.md](doc/config.md#syntax).
-
-
-**Runlevels**
-
-Support for SysV init-style [runlevels][5] is available, in the same
-minimal style as everything else in Finit.  The `[2345]` syntax can be
-applied to service, task, run, and TTY stanzas.
-
-Reserved runlevels are 0 and 6, halt and reboot, respectively just like
-SysV init.  Runlevel 1 can be configured freely, but is recommended to
-be kept as the system single-user runlevel since Finit will not start
-networking here.  The configured `runlevel NUM` from `/etc/finit.conf`
-is what Finit changes to after bootstrap, unless 'single' (or 'S') is
-given on the kernel cmdline, in which case runlevel 1 is started.
-
-All services in runlevel S) are started first, followed by the desired
-run-time runlevel.  Run tasks in runlevel S can be started in sequence
-by using `run [S] cmd`.  Changing runlevels at runtime is done like any
-other init, e.g. <kbd>init 4</kbd>, but also using the more advanced
-`intictl` tool.
-
-
-**Conditions**
-
-As mentioned previously, Finit has an advanced dependency system to
-handle synchronization, called [conditions](doc/conditions.md).  It can
-be used in many ways; depend on another service, network availability,
-etc.
-
-One *really cool* example useful for embedded systems is to run certain
-scripts if a board has a certain feature encoded in its device tree.  At
-bootstrap we run the following `ident` script:
-
-```sh
-#!/bin/sh
-conddir=/var/run/finit/cond/hw/model
-dtmodel=/sys/firmware/devicetree/base/model
-
-if ! test -e $dtmodel; then
-    exit 0
-fi
-
-model=$(cat $dtmodel | tr "[A-Z] " "[a-z]-")
-mkdir -p $conddir && ln -s ../../reconf $conddir/$model
-```
-
-Provided the device tree node exists, and is a string, we can then use
-the condition `<hw/model/foo>` when starting other scripts.  Here is an
-example:
-
-```
-run  [S]                /path/to/ident    --
-task [2] <hw/model/foo> /path/to/foo-init -- Initializing Foo board
-```
-
-> [!TIP]
-> Notice the trick with an empty description to hide the call to `ident`
-> in the Finit progress output.
-
-
-**Plugins**
-
-Plugins can *extend* the functionality of Finit and *hook into* the
-different stages of the boot process and at runtime.  Plugins are
-written in C and compiled into a dynamic library loaded automatically by
-finit at boot.  A basic set of plugins are bundled in the `plugins/`
-directory.
-
-Capabilities:
-
-- **Hooks**  
-  Hook into the boot at predefined points to extend Finit
-- **I/O**  
-  Listen to external events and control Finit behavior/services
-
-Extensions and functionality not purely related to what an `/sbin/init`
-needs to start a system are available as a set of plugins that either
-hook into the boot process or respond to various I/O.
-
-For more information, see [doc/plugins.md](doc/plugins.md).
-
-
-**Automatic Reload**
-
-By default, Finit monitors `/etc/finit.d/` and `/etc/finit.d/enabled/`
-registering any changes to `.conf` files.  To activate a change the user
-must call `initctl reload`, which reloads all modified files, stops any
-removed services, starts new ones, and restarts any modified ones.  If the
-command line arguments of a service have changed, the process will be
-terminated and then started again with the updated arguments. If the arguments
-have not been modified and the process supports SIGHUP, the process will
-receive a SIGHUP rather than being terminated and started.
-
-For some use-cases the extra step of calling `initctl reload` creates an
-unnecessary overhead, which can be removed at build-time using:
-
-    configure --enable-auto-reload
-
-
-**Cgroups**
-
-Finit supports cgroups v2 and comes with the following default groups in
-which services and user sessions are placed in:
-
-     /sys/fs/cgroup
-       |-- init/               # cpu.weight:100
-       |-- system/             # cpu.weight:9800
-       `-- user/               # cpu.weight:100
-
-Finit itself and its helper scripts and services are placed in the
-top-level leaf-node group `init/`, which also is _reserved_.
-
-All run/task/service/sysv processes are placed in their own sub-group
-in `system/`.  The name of each sub-group is taken from the respective
-`.conf` file from `/etc/finit.d`.
-
-All getty/tty processes are placed in their own sub-group in `user/`.
-The name of each sub-group is taken from the username.
-
-A fourth group also exists, the `root` group.  It is also _reserved_ and
-primarily intended for RT tasks.  If you have RT tasks they need to be
-declared as such in their service stanza like this:
-
-    service [...] <...> cgroup.root /path/to/foo args -- description
-
-or
-
-    cgroup.root
-    service [...] <...> /path/to/foo args -- description
-    service [...] <...> /path/to/bar args -- description
-
-See [doc/config.md](doc/config.md#cgroups) for more information, e.g.,
-how to configure per-group limits.
-
-The `initctl` tool has three commands to help debug and optimize the
-setup and monitoring of cgroups.  See the `ps`, `top`, and `cgroup`
-commands for details.
-
-> [!NOTE]
-> Systems that do not support cgroups, specifically version 2, are
-> automatically detected.  On such systems the above functionality is
-> disabled early at boot.
-
-
-Runparts & /etc/rc.local
-------------------------
-
-At the end of the boot, when all bootstrap (`S`) tasks and services have
-started, but not networking, Finit calls its built-in [run-parts(8)][]
-command on any configured `runparts <DIR>` directory.  This happens just
-before changing to the configured runlevel (default 2).  (Networking is
-enabled just prior to changing from single user mode.)
-
-```shell
-runparts /etc/rc.d/
-```
-
-Right after the runlevel change when all services have started properly,
-`/etc/rc.local` is called.
-
-No configuration stanza in `/etc/finit.conf` is required for `rc.local`.
-If it exists and is an executable shell script Finit calls it at the very
-end of the boot, before calling the `HOOK_SYSTEM_UP`.  See more on hooks
-in [doc/plugins.md](doc/plugins.md#hooks).
-
-
-### Limitations
-
-It is not possible to call Finit via signals or use `initctl` in any
-runparts or `/etc/rc.local` script.  This because Finit is single
-threaded and is calling these scripts in a blocking fashion at the end
-of runlevel S, at which point the event loop has not yet been started.
-
-The event loop is the whole thing which Finit is built around, except
-for runlevel S, which remains a slow procession through a lot of set up,
-with a few hooks and blocking call outs to external scripts.
-
-However, not all `initctl` commands are prohibited. Supported commands:
-
- - `inictl cond`: only operate of files in `/run/finit/cond`
- - `initctl enable/disable`: enabled run/task/service is activated on
-   the runlevel change from S to 2
- - `initctl touch/show/create/delete/list`: `create`, provided the
-   non-interactive mode is used, again changes take effect in the
-   runlevel change directly after bootstrap
- - `initctl -f reboot/poweroff/halt`: provided the `-f` flag is used to
-   force direct kernel commands
-
-**Example:** you can set a `usr/` condition in `/etc/rc.local` and have
-a service/task in runlevel 2 depend on it to execute.
-
-
-Runlevels
----------
-
-Basic support for [runlevels][5] is included in Finit from v1.8.  By
-default all services, tasks, run commands and TTYs listed without a set
-of runlevels get a default set `[234]` assigned.  The default runlevel
-after boot is 2.
-
-Finit supports runlevels 0-9, and S, with 0 reserved for halt, 6 reboot
-and S for services to only run at bootstrap.  Runlevel 1 is the single
-user level, where usually no networking is enabled.  In Finit this is
-more of a policy for the user to define.  Normally only runlevels 1-6
-are used, and even more commonly, only the default runlevel is used.
-
-To specify an allowed set of runlevels for a `service`, `run` command,
-`task`, or `tty`, add `[NNN]` to your `/etc/finit.conf`, like this:
-
-```
-service [S12345] syslogd -n -x             -- System log daemon
-run     [S]      /etc/init.d/acpid start   -- Starting ACPI Daemon
-task    [S]      /etc/init.d/kbd start     -- Preparing console
-service [S12345] <pid/syslogd> klogd -n -x -- Kernel log daemon
-
-tty     [12345]  /dev/tty1
-tty     [2]      /dev/tty2
-tty     [2]      /dev/tty3
-tty     [2]      /dev/tty4
-tty     [2]      /dev/tty5
-tty     [2]      /dev/tty6
-```
-
-In this example syslogd is first started, in parallel, and then acpid is
-called using a conventional SysV init script.  It is called with the run
-command, meaning the following task command to start the kbd script is
-not called until the acpid init script has fully completed.  Then the
-keyboard setup script is called in parallel with klogd as a monitored
-service.
-
-Again, tasks and services are started in parallel, while run commands
-are called in the order listed and subsequent commands are not started
-until a run command has completed.  Also, task and run commands are run
-in a shell, so pipes and redirects can be used.
-
-The following examples illustrate this.  Bootstrap task and run commands
-are also removed when they have completed, `initctl show` will not list
-them.
-
-```
-task [S] echo "foo" | cat >/tmp/bar
-run  [S] echo "$HOME" >/tmp/secret
-```
-
-Switching between runlevels can be done by calling init with a single
-argument, e.g. <kbd>init 5</kbd>, or using `initctl runlevel 5`, both
-switch to runlevel 5.  When changing runlevels Finit also automatically
-reloads all `.conf` files in the `/etc/finit.d/` directory.  So if you
-want to set a new system config, switch to runlevel 1, change all config
-files in the system, and touch all `.conf` files in `/etc/finit.d`
-before switching back to the previous runlevel again — that way Finit
-can both stop old services and start any new ones for you, without
-rebooting the system.
-
-
-Rebooting & Halting
--------------------
-
-Traditionally, rebooting and halting a UNIX system is done by changing
-its runlevel.  Finit comes with its own tooling providing: `shutdown`,
-`reboot`, `poweroff`, and `suspend`, but also the `initctl` tool,
-detailed in the next section.
-
-For compatibility reasons Finit listens to the same set of signals as
-BusyBox init.  This is not 100% compatible with SysV init, but clearly
-the more common combination for Finit.  For more details, see
-[doc/signals.md](doc/signals.md).
-
-
-Commands & Status
------------------
-
-Finit also implements a modern API to query status, and start/stop
-services, called `initctl`.  Unlike `telinit` the `initctl` tool does
-not return until the given command has fully completed.
-
-```
-Usage: initctl [OPTIONS] [COMMAND]
-
-Options:
-  -b, --batch               Batch mode, no screen size probing
-  -c, --create              Create missing paths (and files) as needed
-  -f, --force               Ignore missing files and arguments, never prompt
-  -h, --help                This help text
-  -j, --json                JSON output in 'status' and 'cond' commands
-  -1, --once                Only one lap in commands like 'top'
-  -p, --plain               Use plain table headings, no ctrl chars
-  -q, --quiet               Silent, only return status of command
-  -t, --no-heading          Skip table headings
-  -v, --verbose             Verbose output
-  -V, --version             Show program version
-
-Commands:
-  debug                     Toggle Finit (daemon) debug
-  help                      This help text
-  version                   Show program version
-
-  ls | list                 List all .conf in /etc/finit.d
-  create   <CONF>           Create   .conf in /etc/finit.d/available
-  delete   <CONF>           Delete   .conf in /etc/finit.d/available
-  show     <CONF>           Show     .conf in /etc/finit.d/available
-  edit     <CONF>           Edit     .conf in /etc/finit.d/available
-  touch    <CONF>           Change   .conf in /etc/finit.d/available
-  enable   <CONF>           Enable   .conf in /etc/finit.d/available
-  disable  <CONF>           Disable  .conf in /etc/finit.d/enabled
-  reload                    Reload  *.conf in /etc/finit.d (activate changes)
-
-  cond     set   <COND>     Set (assert) user-defined conditions     +usr/COND
-  cond     get   <COND>     Get status of user-defined condition, see $? and -v
-  cond     clear <COND>     Clear (deassert) user-defined conditions -usr/COND
-  cond     status           Show condition status, default cond command
-  cond     dump  [TYPE]     Dump all, or a type of, conditions and their status
-
-  log      [NAME]           Show ten last Finit, or NAME, messages from syslog
-  start    <NAME>[:ID]      Start service by name, with optional ID
-  stop     <NAME>[:ID]      Stop/Pause a running service by name
-  reload   <NAME>[:ID]      Reload service as if .conf changed (SIGHUP or restart)
-                            This allows restart of run/tasks that have already run
-                            Note: Finit .conf file(s) are *not* reloaded!
-  restart  <NAME>[:ID]      Restart (stop/start) service by name
-  signal   <NAME>[:ID] <S>  Send signal S to service by name, with optional ID
-  ident    [NAME]           Show matching identities for NAME, or all
-  status   <NAME>[:ID]      Show service status, by name
-  status                    Show status of services, default command
-
-  cgroup                    List cgroup config overview
-  ps                        List processes based on cgroups
-  top                       Show top-like listing based on cgroups
-
-  plugins                   List installed plugins
-
-  runlevel [0-9]            Show or set runlevel: 0 halt, 6 reboot
-  reboot                    Reboot system
-  halt                      Halt system
-  poweroff                  Halt and power off system
-  suspend                   Suspend system
-
-  utmp     show             Raw dump of UTMP/WTMP db
-```
-
-For services *not* supporting `SIGHUP` the `<!>` notation in the .conf
-file must be used to tell Finit to stop and start it on `reload` and
-`runlevel` changes.  If `<>` holds more [conditions](doc/conditions.md),
-these will also affect how a service is maintained.
-
-> [!NOTE]
-> Even though it is possible to start services not belonging in the
-> current runlevel these services will not be respawned automatically by
-> Finit if they exit (crash).  Hence, if the runlevel is 2, the below
-> Dropbear SSH service will not be restarted if it is killed or exits.
-
-The `status` command is the default, it displays a quick overview of all
-monitored run/task/services.  Here we call `initctl -p`, suitable for
-scripting and documentation:
-
-```
-alpine:~# initctl -p
-PID   IDENT     STATUS   RUNLEVELS     DESCRIPTION
-======================================================================
-1506  acpid     running  [---2345----] ACPI daemon
-1509  crond     running  [---2345----] Cron daemon
-1489  dropbear  running  [---2345----] Dropbear SSH daemon
-1511  klogd     running  [S-12345----] Kernel log daemon
-1512  ntpd      running  [---2345----] NTP daemon
-1473  syslogd   running  [S-12345----] Syslog daemon
-
-alpine:~# initctl -pv
-PID   IDENT     STATUS   RUNLEVELS     COMMAND
-======================================================================
-1506  acpid     running  [---2345----] acpid -f
-1509  crond     running  [---2345----] crond -f -S $CRON_OPTS
-1489  dropbear  running  [---2345----] dropbear -R -F $DROPBEAR_OPTS
-1511  klogd     running  [S-12345----] klogd -n $KLOGD_OPTS
-1512  ntpd      running  [---2345----] ntpd -n $NTPD_OPTS
-1473  syslogd   running  [S-12345----] syslogd -n
-```
-
-The environment variables to each of the services above are read from,
-in the case of Alpine Linux, `/etc/conf.d/`.  Other distributions may
-have other directories, e.g., Debian use `/etc/default/`.
-
-The `status` command takes an optional `NAME:ID` argument.  Here we
-check the status of `dropbear`, which only has one instance in this
-system:
-
-```
-alpine:~# initctl -p status dropbear
-     Status : running
-   Identity : dropbear
-Description : Dropbear SSH daemon
-     Origin : /etc/finit.d/enabled/dropbear.conf
-Environment : -/etc/conf.d/dropbear
-Condition(s):
-    Command : dropbear -R -F $DROPBEAR_OPTS
-   PID file : !/run/dropbear.pid
-        PID : 1485
-       User : root
-      Group : root
-     Uptime : 2 hour 46 min 56 sec
-  Runlevels : [---2345----]
-     Memory : 1.2M
-     CGroup : /system/dropbear cpu 0 [100, max] mem [--.--, max]
-              |- 1485 dropbear -R -F
-              |- 2634 dropbear -R -F
-              |- 2635 ash
-              `- 2652 initctl -p status dropbear
-
-Apr  8 12:19:49 alpine authpriv.info dropbear[1485]: Not backgrounding
-Apr  8 12:37:45 alpine authpriv.info dropbear[2300]: Child connection from 192.168.121.1:47834
-Apr  8 12:37:46 alpine authpriv.notice dropbear[2300]: Password auth succeeded for 'root' from 192.168.121.1:47834
-Apr  8 12:37:46 alpine authpriv.info dropbear[2300]: Exit (root) from <192.168.121.1:47834>: Disconnect received
-Apr  8 15:02:11 alpine authpriv.info dropbear[2634]: Child connection from 192.168.121.1:48576
-Apr  8 15:02:12 alpine authpriv.notice dropbear[2634]: Password auth succeeded for 'root' from 192.168.121.1:48576
-```
-
-
-Requirements
-------------
-
-Finit is capable of running on both desktop/server systems with udev and
-embedded systems that usually come with BusyBox mdev.  Some systems have
-systemd-udev or eudev today instead of the original udev, Finit probes
-for all of them at runtime and expects `/dev/` to be a writable file
-system using `devtmpfs`.  It is also possible to run on a statically set
-up `/dev` if needed.  It is however not a good idea to have both udev
-and mdev installed at the same time, this will lead to unpredictable
-results.
-
-At boot Finit calls either `mdev` or `udevd` to populate `/dev`, this is
-done slightly differently and on systems with udev you might want to add
-the following one-shot task early in your `/etc/finit.conf`:
-
-```conf
-run [S] udevadm settle --timeout=120 -- Waiting for udev
-```
-
-Finit has a built-in Getty for TTYs, but requires a working `/bin/login`
-or `/bin/sh`, if no TTYs are configured in `/etc/finit.conf`.
-
-For a fully operational system `/var`, `/run` and `/tmp` must be set up
-properly in `/etc/fstab` -- which is iterated over at boot.
-
-
-Origin & References
--------------------
-
-This project is based on the [original finit][] by [Claudio Matsuoka][]
-which was reverse engineered from syscalls of the [EeePC fastinit][] —
-"gaps filled with frog DNA …"
-
-Finit is developed and maintained by [Joachim Wiberg][] at [GitHub][6].
-Please file bug reports, clone it, or send pull requests for bug fixes
-and proposed extensions.
-
-
-[1]:                https://en.wikipedia.org/wiki/Process_supervision
-[2]:                https://cr.yp.to/daemontools.html
-[3]:                https://smarden.org/runit/
-[4]:                https://en.wikipedia.org/wiki/Init
-[5]:                https://en.wikipedia.org/wiki/Runlevel
-[6]:                https://github.com/troglobit/finit
-[RFC862]:           https://tools.ietf.org/html/rfc862
-[RFC863]:           https://tools.ietf.org/html/rfc863
-[RFC864]:           https://tools.ietf.org/html/rfc864
-[RFC867]:           https://tools.ietf.org/html/rfc867
-[RFC868]:           https://tools.ietf.org/html/rfc868
-[init]:             https://en.wikipedia.org/wiki/Init
-[upstart]:          https://upstart.ubuntu.com/
-[systemd]:          https://www.freedesktop.org/wiki/Software/systemd/
-[openrc]:           https://www.gentoo.org/proj/en/base/openrc/
-[sd_notify()]:      https://www.freedesktop.org/software/systemd/man/sd_notify.html
-[s6 style]:         https://skarnet.org/software/s6/notifywhenup.html
-[run-parts(8)]:     https://manpages.debian.org/cgi-bin/man.cgi?query=run-parts
-[tmpfiles.d(5)]:    https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html
-[original finit]:   http://helllabs.org/finit/
-[EeePC fastinit]:   https://web.archive.org/web/20071208212450/http://wiki.eeeuser.com/boot_process:the_boot_process
-[Claudio Matsuoka]: https://github.com/cmatsuoka
-[Joachim Wiberg]:   https://troglobit.com
+> Finit can run on various Linux distributions, but the bundled install
+> scripts are examples only. They have been tested on amd64 (x86_64) systems
+> with standard configurations.
+>
+> For embedded systems, see these [Buildroot][]-based examples:
+> [myLinux][], [Infix][], or [br2-finit-demo][].
+
+[finix]:            https://github.com/finix-community/finix
 [Buildroot]:        https://buildroot.org
 [Infix]:            https://kernelkit.github.io
-[finit.conf(5)]:    https://man.troglobit.com/man5/finit.conf.5.html
+[myLinux]:          https://github.com/troglobit/myLinux/
+[br2demo]:          https://troglobit.com/post/2022-12-26-buildroot-demo-of-fastinit-finit/
+[EeePC fastinit]:   https://web.archive.org/web/20071208212450/http://wiki.eeeuser.com/boot_process:the_boot_process
+[Claudio Matsuoka]: https://github.com/cmatsuoka
 [License]:          https://en.wikipedia.org/wiki/MIT_License
 [License Badge]:    https://img.shields.io/badge/License-MIT-teal.svg
-[myLinux]:          https://github.com/troglobit/myLinux/
-[watchdogd]:        https://github.com/troglobit/watchdogd/
-[sysklogd]:         https://github.com/troglobit/sysklogd/
-[GitHub]:           https://github.com/troglobit/finit/actions/workflows/build.yml/
-[GitHub Status]:    https://github.com/troglobit/finit/actions/workflows/build.yml/badge.svg
+[Release]:          https://github.com/finit-project/finit/releases
+[Release Badge]:    https://img.shields.io/github/v/release/finit-project/finit
+[GitHub]:           https://github.com/finit-project/finit/actions/workflows/build.yml/
+[GitHub Status]:    https://github.com/finit-project/finit/actions/workflows/build.yml/badge.svg
 [Coverity Scan]:    https://scan.coverity.com/projects/3545
 [Coverity Status]:  https://scan.coverity.com/projects/3545/badge.svg
+[br2-finit-demo]:   https://github.com/finit-project/br2-finit-demo

check.sh

@@ -1,7 +0,0 @@
-#!/bin/sh
-# Run test suite with the correct configure params
-
-make distclean
-./configure --prefix=/usr --exec-prefix= --sysconfdir=/etc --localstatedir=/var \
-	    --enable-x11-common-plugin --with-watchdog --with-keventd
-make -j17 clean check

configure.ac

@@ -1,7 +1,7 @@
-AC_INIT([Finit], [4.11-rc2], [https://github.com/troglobit/finit/issues],
-	[finit], [https://troglobit.com/projects/finit/])
+AC_INIT([Finit], [5.0-rc1], [https://github.com/finit-project/finit/issues],
+	[finit], [https://http://finit-project.github.io/])
 AC_CONFIG_AUX_DIR(aux)
-AM_INIT_AUTOMAKE([1.11 foreign dist-xz subdir-objects])
+AM_INIT_AUTOMAKE([1.11 foreign subdir-objects])
 AM_SILENT_RULES([yes])
 
 AC_CONFIG_SRCDIR([src/finit.c])
@@ -11,10 +11,14 @@ AC_CONFIG_FILES([Makefile
 	contrib/alpine/Makefile contrib/alpine/finit.d/Makefile contrib/alpine/finit.d/available/Makefile
 	contrib/debian/Makefile contrib/debian/finit.d/Makefile contrib/debian/finit.d/available/Makefile
 	contrib/void/Makefile   contrib/void/finit.d/Makefile   contrib/void/finit.d/available/Makefile
-	doc/Makefile
+	doc/Makefile doc/config/Makefile
+	dbus-1/Makefile
+	libink/Makefile
+	libsystemd/Makefile libsystemd/libsystemd.pc
 	man/Makefile
 	plugins/Makefile
 	src/Makefile
+	keventd/Makefile
 	system/Makefile system/10-hotplug.conf
 	test/test.env test/Makefile
 	test/lib/Makefile test/src/Makefile
@@ -47,8 +51,14 @@ AC_TYPE_UINT32_T
 PKG_PROG_PKG_CONFIG
 
 # Check for required libraries
-PKG_CHECK_MODULES([uev],  [libuev >= 2.2.0])
-PKG_CHECK_MODULES([lite], [libite >= 2.2.0])
+PKG_CHECK_MODULES([uev],  [libuev >= 2.4.1])
+PKG_CHECK_MODULES([lite], [libite >= 2.6.1])
+# 3.3 is the floor: CFGF_KEYSTRVAL, which environment {} and the
+# free-form cgroup keys are built on, does not exist before it.  3.3
+# parses both correctly.  Two workarounds hang off this number, the
+# spurious KEYSTRVAL warning and cfg_parse_buf() losing the file name
+# of a template; grep the XXX notes in src/conf.c before raising it.
+PKG_CHECK_MODULES([confuse], [libconfuse >= 3.3])
 
 # Check for configured Finit features
 AC_ARG_ENABLE(auto_reload,
@@ -71,6 +81,10 @@ AC_ARG_ENABLE(cgroup,
         AS_HELP_STRING([--disable-cgroup], [Disable cgroup v2 support, default: autodetect from /sys/fs/cgroup]),,[
         enable_cgroup=yes])
 
+AC_ARG_ENABLE(libcap,
+        AS_HELP_STRING([--disable-libcap], [Disable Linux capabilities support]),,[
+				enable_libcap=yes])
+
 AC_ARG_ENABLE(redirect,
         AS_HELP_STRING([--disable-redirect], [Disable redirection of service output to /dev/null]),,[
 	enable_redirect=yes])
@@ -83,6 +97,10 @@ AC_ARG_ENABLE(logrotate,
         AS_HELP_STRING([--disable-logrotate], [Disable built-in rotation of /var/log/wtmp]),,[
 	enable_logrotate=yes])
 
+AC_ARG_ENABLE(dbus,
+        AS_HELP_STRING([--disable-dbus], [Disable D-Bus support (libink + Finit object tree)]),,[
+	enable_dbus=yes])
+
 AC_ARG_ENABLE(doc,
         AS_HELP_STRING([--disable-doc], [Disable build and install of doc/ section]),,[
 	enable_doc=yes])
@@ -100,17 +118,18 @@ AC_ARG_ENABLE(all_plugins,
     AS_HELP_STRING([--enable-all-plugins], [Enable all plugins, default: auto]),
 	enable_all_plugins=$enableval, enable_all_plugins=auto)
 AC_PLUGIN([alsa-utils],    [no],  [Save and restore ALSA sound settings using alsactl])
-AC_PLUGIN([dbus],          [no],  [Setup and start system message bus, D-Bus])
+AC_PLUGIN([dbus],          [yes], [Setup and start system message bus, D-Bus])
 AC_PLUGIN([modules-load],  [no],  [Scans /etc/modules-load.d for modules to load])
 AC_PLUGIN([modprobe],      [no],  [Coldplug modules using modalias magic])
 AC_PLUGIN([resolvconf],    [no],  [Setup necessary files for resolvconf])
 AC_PLUGIN([x11-common],    [no],  [Console setup (for X)])
 AC_PLUGIN([netlink],       [yes], [Basic netlink plugin for IFUP/IFDN and GW events. Can be replaced with externally built plugin that links with libnl or similar.])
 AC_PLUGIN([hook-scripts],  [no],  [Trigger script execution from hook points])
-AC_PLUGIN([hotplug],       [yes], [Start udevd or mdev kernel event datamon])
+AC_PLUGIN([hotplug],       [no],  [Start udevd or mdev kernel event datamon])
 AC_PLUGIN([rtc],           [yes], [Save and restore RTC using hwclock])
 AC_PLUGIN([tty],           [yes], [Automatically activate new TTYs, e.g. USB-to-serial])
 AC_PLUGIN([urandom],       [yes], [Setup and save random seed at boot/shutdown])
+AC_PLUGIN([plymouth],      [no],  [Plymouth boot splash integration])
 AC_PLUGIN([testserv],      [no],  [Test plugin to start test serv daemon])
 
 # Check for extra arguments or packages
@@ -143,7 +162,7 @@ AC_ARG_WITH(sysconfig,
 	[sysconfig=$withval], [sysconfig=default])
 
 AC_ARG_WITH(group,
-	AS_HELP_STRING([--with-group=NAME], [Group for /run/finit/socket (initctl), default: root]),
+	AS_HELP_STRING([--with-group=NAME], [Group for /run/finit/socket and /run/finit/bus, default: root]),
 	[group=$withval], [group=root])
 
 AC_ARG_WITH(hostname,
@@ -159,14 +178,21 @@ AC_ARG_WITH(random-seed,
 	[random_seed=$withval], [random_seed=yes])
 
 AC_ARG_WITH(keventd,
-        AS_HELP_STRING([--with-keventd], [Enable built-in keventd, default: no]),, [with_keventd=no])
+        AS_HELP_STRING([--with-keventd], [Enable built-in keventd device manager, default: yes]),, [with_keventd=yes])
+
+AC_ARG_WITH(udev-rules,
+        AS_HELP_STRING([--without-udev-rules], [Skip install of curated udev rules under /lib/udev/rules.d, default: yes when keventd enabled]),, [with_udev_rules=yes])
 
 AC_ARG_WITH(sulogin,
-        AS_HELP_STRING([--with-sulogin@<:@=USER@:>@], [Enable built-in sulogin, optional USER to request password for (default root), default: no.]),[sulogin=$withval],[with_sulogin=no])
+        AS_HELP_STRING([--with-sulogin@<:@=USER@:>@], [Built-in sulogin, optional USER to request password for, default: yes (root)]),[sulogin=$withval],[with_sulogin=yes sulogin=yes])
 
 AC_ARG_WITH(watchdog,
-        AS_HELP_STRING([--with-watchdog@<:@=DEV@:>@], [Enable built-in watchdog, default: /dev/watchdog]),
-	[watchdog=$withval], [with_watchdog=no watchdog=])
+        AS_HELP_STRING([--with-watchdog@<:@=DEV@:>@], [Built-in watchdog, default: yes (/dev/watchdog)]),
+	[watchdog=$withval], [with_watchdog=yes watchdog=yes])
+
+AC_ARG_WITH(libsystemd,
+        AS_HELP_STRING([--with-libsystemd], [Build replacement libsystemd library, default: no]),
+	[with_libsystemd=$withval], [with_libsystemd=no])
 
 AC_ARG_WITH(hook-scripts-path,
         AS_HELP_STRING([--with-hook-scripts-path=DIR], [Base directory for hook scripts, default $libexecdir/finit/hook]),
@@ -199,6 +225,16 @@ AS_IF([test "x$enable_kernel_logging" = "xyes"], [
 AS_IF([test "x$enable_cgroup" = "xyes"], [
         AC_DEFINE(CGROUP2_ENABLED, 1, [Autodetect cgroup v2 support from /sys/fs/cgroup])])
 
+AS_IF([test "x$enable_libcap" = "xyes"], [
+	AC_CHECK_LIB([cap], [cap_from_text], [
+		AC_DEFINE(HAVE_LIBCAP, 1, [Have libcap for Linux capabilities support])
+		LIBS="$LIBS -lcap"
+	], [
+		AC_MSG_WARN([libcap not found, capabilities support disabled])
+		enable_libcap=no
+	])
+])
+
 AS_IF([test "x$enable_fastboot" = "xyes"], [
 	AC_DEFINE(FAST_BOOT, 1, [Skip fsck check on filesystems listed in /etc/fstab])])
 
@@ -217,6 +253,10 @@ AS_IF([test "x$enable_rescue" != "xno"], [
 
 AM_CONDITIONAL(LOGROTATE, [test "x$enable_logrotate" = "xyes"])
 
+AS_IF([test "x$enable_dbus" = "xyes"], [
+	AC_DEFINE(HAVE_DBUS, 1, [Build D-Bus support via libink])])
+AM_CONDITIONAL(DBUS, [test "x$enable_dbus" = "xyes"])
+
 ### With features ##############################################################################
 AS_IF([test "x$bash_dir" = "xyes"], [
 	PKG_CHECK_MODULES([BASH_COMPLETION], [bash-completion >= 2.0],
@@ -262,7 +302,7 @@ AS_IF([test "x$with_heading" != "xno"], [
 AS_IF([test "x$with_group" != "xno"], [
 	AS_IF([test "x$group" = "xyes"], [
 		group=root])])
-AC_DEFINE_UNQUOTED(DEFGROUP, "$group", [For /run/finit/socket])
+AC_DEFINE_UNQUOTED(DEFGROUP, "$group", [For /run/finit/socket and /run/finit/bus])
 
 AS_IF([test "x$with_hostname" != "xno"], [
 	AS_IF([test "x$hostname" = "xyes"], [
@@ -292,7 +332,11 @@ AS_IF([test "x$rtc_file" != "xno"], [
 	AC_DEFINE_UNQUOTED(RTC_FILE, "$rtcfile_path", [Save and restore system time from this file if /dev/rtc is missing.])],[
 	AC_DEFINE_UNQUOTED(RTC_FILE, NULL)])
 
-AS_IF([test "x$with_keventd" != "xno"], [with_keventd=yes])
+AS_IF([test "x$with_keventd" != "xno"], [
+	with_keventd=yes
+	PKG_CHECK_MODULES([blkid], [blkid],, [
+		AC_MSG_ERROR([libblkid (util-linux) is required to build keventd.
+		Install the dev package (e.g. libblkid-dev) or disable keventd with --without-keventd])])])
 
 AS_IF([test "x$with_sulogin" != "xno"], [
 	AS_IF([test "x$sulogin" = "xyes"], [
@@ -308,6 +352,9 @@ AS_IF([test "x$with_watchdog" != "xno"], [
         AC_DEFINE_UNQUOTED(WDT_DEVNODE, "$watchdog", [Built-in watchdog device node])], [
 	watchdog=])
 
+AS_IF([test "x$with_libsystemd" != "xno"], [
+        AC_DEFINE(HAVE_LIBSYSTEMD, 1, [Build replacement libsystemd library support])])
+
 AS_IF([test "x$enable_hook_scripts_plugin" != "xno"], [
 	AS_IF([test "x$hook_scripts_path" = "xyes"], [hook_scripts_path=$libexecdir/finit/hook])
 	AC_EXPAND_DIR(hook_scripts_path, "$hook_scripts_path")
@@ -319,14 +366,16 @@ AS_IF([test "x$with_plugin_path" != "xno"], [
 	AC_DEFINE_UNQUOTED(EXTERNAL_PLUGIN_PATH, "$plugin_path", [Built-in default: /usr/lib/finit/plugins:/usr/local/lib/finit/plugins])])
 
 # Control build with automake flags
-AM_CONDITIONAL(BASH,      [test "x$bash_dir"      != "xno"])
-AM_CONDITIONAL(STATIC,    [test "x$enable_static"  = "xyes"])
-AM_CONDITIONAL(KEVENTD,   [test "x$with_keventd"  != "xno"])
-AM_CONDITIONAL(SULOGIN,   [test "x$with_sulogin"  != "xno"])
-AM_CONDITIONAL(WATCHDOGD, [test "x$with_watchdog" != "xno"])
-AM_CONDITIONAL(DOC,       [test "x$enable_doc"     = "xyes"])
-AM_CONDITIONAL(CONTRIB,   [test "x$enable_contrib" = "xyes"])
-AM_CONDITIONAL(TESTSERV,  [test "x$enable_testserv_plugin" = "xyes"])
+AM_CONDITIONAL(BASH,        [test "x$bash_dir"        != "xno"])
+AM_CONDITIONAL(STATIC,      [test "x$enable_static"    = "xyes"])
+AM_CONDITIONAL(KEVENTD,     [test "x$with_keventd"    != "xno"])
+AM_CONDITIONAL(UDEV_RULES,  [test "x$with_keventd"    != "xno" -a "x$with_udev_rules" != "xno"])
+AM_CONDITIONAL(SULOGIN,     [test "x$with_sulogin"    != "xno"])
+AM_CONDITIONAL(WATCHDOGD,   [test "x$with_watchdog"   != "xno"])
+AM_CONDITIONAL(LIBSYSTEMD,  [test "x$with_libsystemd" != "xno"])
+AM_CONDITIONAL(DOC,         [test "x$enable_doc"       = "xyes"])
+AM_CONDITIONAL(CONTRIB,     [test "x$enable_contrib"   = "xyes"])
+AM_CONDITIONAL(TESTSERV,    [test "x$enable_testserv_plugin" = "xyes"])
 
 # Workaround for as-of-yet unreleased runstatedir support, planned for
 # autoconf 2.70, which some major distros have backported.
@@ -404,11 +453,14 @@ Optional features:
   Install doc/..........: $enable_doc
   Install contrib/......: $enable_contrib
   Bash completion.......: $bash_completion_dir
-  Built-in keventd......: $with_keventd
+  Built-in keventd......: $with_keventd (blkid: $blkid_LIBS)
   Built-in sulogin......: $with_sulogin $sulogin
   Built-in watchdogd....: $with_watchdog $watchdog
   Built-in logrotate....: $enable_logrotate
+  D-Bus support (libink): $enable_dbus
+  Replacement libsystemd: $with_libsystemd
   Use cgroup v2.........: $enable_cgroup
+  Use libcap............: $enable_libcap
   Parse kernel cmdline..: $enable_kernel_cmdline
   Keep kernel logging...: $enable_kernel_logging
   Skip fsck check.......: $enable_fastboot

contrib/Makefile.am

@@ -3,3 +3,8 @@ bin_SCRIPT = service
 docsdir   := @docdir@/contrib
 docs_DATA  = README.md finit.conf procmon.sh
 EXTRA_DIST = $(docs_DATA)
+
+if BASH
+bashdir            = $(BASH_DIR)
+dist_bash_DATA     = initctl
+endif

contrib/README.md

@@ -6,6 +6,7 @@ install and try out Finit on various Linux distributions.
 
 * [Alpine](alpine/)
 * [Debian](debian/)
+* [Void](void/)
 
 If you have ideas on how to simplify, extend, or even add new example
 configurations for other distributions you are most welcome! :)

contrib/alpine/finit.conf

@@ -3,24 +3,34 @@
 
 ## Runlevel to start after bootstrap, runlevel 'S'
 # Default is 2
-#runlevel 2
+#runlevel = 2
 
 # Top-level cgroups and their default settings.  All groups mandatory
 # but more can be added, max 8 groups in total currently.  The cgroup
 # 'root' is also available, reserved for RT processes.  Settings are
 # as-is, only one shorthand 'mem.' exists, other than that it's the
 # cgroup v2 controller default names.
-#cgroup init   cpu.weight:100
-#cgroup user   cpu.weight:100
-#cgroup system cpu.weight:9700
+#cgroup init   { cpu.weight = 100  }
+#cgroup user   { cpu.weight = 100  }
+#cgroup system { cpu.weight = 9700 }
 
 # Task to run if ctrl-alt-del is pressed.  This condition is asserted by
 # Finit upon receiving SIGINT (from the kernel).
-#task <sys/key/ctrlaltdel> [12345789] initctl reboot -- Rebooting system
+#task reboot {
+#	description = "Rebooting system"
+#	runlevel    = "12345789"
+#	conditions  = { "sys/key/ctrlaltdel" }
+#	command     = "initctl reboot"
+#}
 
 # Task to run if the kernel gets a power fail condition is pressed.
 # Asserted by Finit upon receiving SIGPWR (from the kernel).
-#task <sys/pwr/fail> [12345789] initctl poweroff -- Shutting down system
+#task poweroff {
+#	description = "Shutting down system"
+#	runlevel    = "12345789"
+#	conditions  = { "sys/pwr/fail" }
+#	command     = "initctl poweroff"
+#}
 
 ## Bootstrap services and tasks
 # Can be listed here or in /etc/finit.d/*.conf

contrib/alpine/finit.d/available/acpid.conf

@@ -1,3 +1,9 @@
 # Handle PWR button to shutdown/reboot -- useful in Qemu (virt-manager)
 # Depends on syslogd having started. Redirect any output to log.
-service [2345] <pid/syslogd> log acpid -f -- ACPI daemon
+service acpid {
+	description = "ACPI daemon"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	log { }
+	command     = "acpid -f"
+}

contrib/alpine/finit.d/available/crond.conf

@@ -1 +1,7 @@
-service [2345] <pid/syslogd> env:-/etc/conf.d/crond crond -f -S $CRON_OPTS -- Cron daemon
+service crond {
+	description = "Cron daemon"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	envfile     = "-/etc/conf.d/crond"
+	command     = "crond -f -S $CRON_OPTS"
+}

contrib/alpine/finit.d/available/dropbear.conf

@@ -1,2 +1,7 @@
 # Start SSH daemon as soon as basic networking comes up
-service [2345] 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"
+	command     = "dropbear -R -F $DROPBEAR_OPTS"
+}

contrib/alpine/finit.d/available/getty.conf

@@ -1,5 +1,24 @@
 # Consoles to start getty on when system is up
-tty [12345] /dev/ttyS0 noclear
-tty [12345] /dev/tty1  noclear nowait
-tty [2345]  /dev/tty2  noclear nowait
-tty [2345]  /dev/tty3  noclear nowait
+tty ttyS0 {
+	runlevel = "12345"
+	device   = "/dev/ttyS0"
+	noclear  = true
+}
+tty tty1 {
+	runlevel = "12345"
+	device   = "/dev/tty1"
+	noclear  = true
+	nowait   = true
+}
+tty tty2 {
+	runlevel = "2345"
+	device   = "/dev/tty2"
+	noclear  = true
+	nowait   = true
+}
+tty tty3 {
+	runlevel = "2345"
+	device   = "/dev/tty3"
+	noclear  = true
+	nowait   = true
+}

contrib/alpine/finit.d/available/keymap.conf

@@ -1,2 +1,7 @@
 # Oneshot task to run once at bootstrap
-task [S] env:/etc/conf.d/loadkmap zcat $KEYMAP | loadkmap -- Loading keymap
+task keymap {
+	description = "Loading keymap"
+	runlevel    = "S"
+	envfile     = "/etc/conf.d/loadkmap"
+	command     = "zcat $KEYMAP | loadkmap"
+}

contrib/alpine/finit.d/available/lxdm.conf

@@ -1 +1,5 @@
-service [2345] lxdm -- Lightweight Login Manager
+service lxdm {
+	description = "Lightweight Login Manager"
+	runlevel    = "2345"
+	command     = "lxdm"
+}

contrib/alpine/finit.d/available/modules.conf

@@ -1,7 +1,2 @@
 ## Linux kernel modules to load
-#module fbcon
-#module button
-#module evdev
-#module mousedev
-#module 8139cp
-#module softdog
+#modules = { "fbcon", "button", "evdev", "mousedev", "8139cp", "softdog" }

contrib/alpine/finit.d/available/ntpd.conf

@@ -1,2 +1,9 @@
 # Busybox ntpd has no option to use syslog when running in foreground
-service [2345] <pid/syslogd> env:-/etc/conf.d/ntpd log ntpd -n $NTPD_OPTS -- NTP daemon
+service ntpd {
+	description = "NTP daemon"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	envfile     = "-/etc/conf.d/ntpd"
+	log { }
+	command     = "ntpd -n $NTPD_OPTS"
+}

contrib/alpine/finit.d/available/syslogd.conf

@@ -1,4 +1,15 @@
 # Start syslogd as soon as possible, should always run
 # Start klogd as soon as possible, but after syslogd
-service [S12345] env:-/etc/conf.d/syslog syslogd -n $SYSLOGD_OPTS          -- Syslog daemon
-service [S12345] <pid/syslogd> env:-/etc/conf.d/klogd klogd -n $KLOGD_OPTS -- Kernel log daemon
+service syslogd {
+	description = "Syslog daemon"
+	runlevel    = "S12345"
+	envfile     = "-/etc/conf.d/syslog"
+	command     = "syslogd -n $SYSLOGD_OPTS"
+}
+service klogd {
+	description = "Kernel log daemon"
+	runlevel    = "S12345"
+	conditions  = { "pid/syslogd" }
+	envfile     = "-/etc/conf.d/klogd"
+	command     = "klogd -n $KLOGD_OPTS"
+}

contrib/alpine/finit.d/available/watchdog.conf

@@ -1 +1,6 @@
-service [S123456789] env:-/etc/conf.d/watchdog watchdog $WATCHDOG_OPTS $WATCHDOG_DEV -- System watchdog
+service watchdog {
+	description = "System watchdog"
+	runlevel    = "S123456789"
+	envfile     = "-/etc/conf.d/watchdog"
+	command     = "watchdog $WATCHDOG_OPTS $WATCHDOG_DEV"
+}

contrib/debian/finit.conf

@@ -3,24 +3,34 @@
 
 ## Runlevel to start after bootstrap, runlevel 'S'
 # Default is 2
-#runlevel 2
+#runlevel = 2
 
 # Top-level cgroups and their default settings.  All groups mandatory
 # but more can be added, max 8 groups in total currently.  The cgroup
 # 'root' is also available, reserved for RT processes.  Settings are
 # as-is, only one shorthand 'mem.' exists, other than that it's the
 # cgroup v2 controller default names.
-#cgroup init   cpu.weight:100
-#cgroup user   cpu.weight:100
-#cgroup system cpu.weight:9700
+#cgroup init   { cpu.weight = 100  }
+#cgroup user   { cpu.weight = 100  }
+#cgroup system { cpu.weight = 9700 }
 
 # Task to run if ctrl-alt-del is pressed.  This condition is asserted by
 # Finit upon receiving SIGINT (from the kernel).
-#task <sys/key/ctrlaltdel> [12345789] initctl reboot -- Rebooting system
+#task reboot {
+#	description = "Rebooting system"
+#	runlevel    = "12345789"
+#	conditions  = { "sys/key/ctrlaltdel" }
+#	command     = "initctl reboot"
+#}
 
 # Task to run if the kernel gets a power fail condition is pressed.
 # Asserted by Finit upon receiving SIGPWR (from the kernel).
-#task <sys/pwr/fail> [12345789] initctl poweroff -- Shutting down system
+#task poweroff {
+#	description = "Shutting down system"
+#	runlevel    = "12345789"
+#	conditions  = { "sys/pwr/fail" }
+#	command     = "initctl poweroff"
+#}
 
 ## Bootstrap services and tasks
 # Can be listed here or in /etc/finit.d/*.conf

contrib/debian/finit.d/available/acpid.conf

@@ -1,3 +1,10 @@
 # Handle PWR button to shutdown/reboot -- useful in Qemu (virt-manager)
 # Depends on a syslog daemon having started. Redirect any output to log.
-service [2345] <pid/syslogd> env:-/etc/default/acpid log acpid -f $OPTIONS -- ACPI daemon
+service acpid {
+	description = "ACPI daemon"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	envfile     = "-/etc/default/acpid"
+	log { }
+	command     = "acpid -f $OPTIONS"
+}

contrib/debian/finit.d/available/anacron.conf

@@ -1 +1,8 @@
-task [2345] <sys/pwr/ac,pid/syslogd> halt:usr1 env:-/etc/default/anacron anacron -d -q $ANACRON_ARGS -- Anacron jobs
+task anacron {
+	description = "Anacron jobs"
+	runlevel    = "2345"
+	conditions  = { "sys/pwr/ac", "pid/syslogd" }
+	envfile     = "-/etc/default/anacron"
+	stop-signal = "usr1"
+	command     = "anacron -d -q $ANACRON_ARGS"
+}

contrib/debian/finit.d/available/apparmor.conf

@@ -1,2 +1,6 @@
-sysv [S] /etc/init.d/apparmor -- AppArmor initialization
+sysv apparmor {
+	description = "AppArmor initialization"
+	runlevel    = "S"
+	command     = "/etc/init.d/apparmor"
+}
 

contrib/debian/finit.d/available/avahi-daemon.conf

@@ -1 +1,6 @@
-service [2345] env:-/etc/default/avahi-daemon avahi-daemon -s $AVAHI_DAEMON_OPTS -- Avahi mDNS/DNS-SD Stack
+service avahi-daemon {
+	description = "Avahi mDNS/DNS-SD Stack"
+	runlevel    = "2345"
+	envfile     = "-/etc/default/avahi-daemon"
+	command     = "avahi-daemon -s $AVAHI_DAEMON_OPTS"
+}

contrib/debian/finit.d/available/bluetooth.conf

@@ -1,3 +1,9 @@
 # To ignore errors like "org.freedesktop.hostname1", update the env file with
 # "--noplugin=hostname", i.e. append to BLUETOOTHD_OPTS
-service [2345] log:null env:-/etc/default/bluetooth /usr/libexec/bluetooth/bluetoothd -n $BLUETOOTHD_OPTS -- Bluetooth service
+service bluetoothd {
+	description = "Bluetooth service"
+	runlevel    = "2345"
+	envfile     = "-/etc/default/bluetooth"
+	log { file = "/dev/null" }
+	command     = "/usr/libexec/bluetooth/bluetoothd -n $BLUETOOTHD_OPTS"
+}

contrib/debian/finit.d/available/console-setup.conf

@@ -1,2 +1,6 @@
 # Oneshot task to run once at bootstrap
-task [S] /lib/console-setup/console-setup.sh -- Setting up console font and keymap
+task console-setup {
+	description = "Setting up console font and keymap"
+	runlevel    = "S"
+	command     = "/lib/console-setup/console-setup.sh"
+}

contrib/debian/finit.d/available/cron.conf

@@ -1 +1,7 @@
-service [2345] <sys/pwr/ac,pid/syslogd> env:-/etc/default/cron cron -f $EXTRA_OPTS -- Background job processing daemon
+service cron {
+	description = "Background job processing daemon"
+	runlevel    = "2345"
+	conditions  = { "sys/pwr/ac", "pid/syslogd" }
+	envfile     = "-/etc/default/cron"
+	command     = "cron -f $EXTRA_OPTS"
+}

contrib/debian/finit.d/available/elogind.conf

@@ -1,4 +1,9 @@
 # On some systems, bootstrap can be really quick and cause elogind
 # to not start before a user has managed to log in.  To prevent
 # this, add <pid/elogind> as condition to your TTYs in getty.conf
-service [2345] <pid/syslogd> /lib/elogind/elogind -- Login manager
+service elogind {
+	description = "Login manager"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	command     = "/usr/libexec/elogind"
+}

contrib/debian/finit.d/available/getty.conf

@@ -1,7 +1,38 @@
 # Consoles to start getty on when system is up
-tty [12345] /dev/tty1 linux noclear nowait
-tty [2345]  /dev/tty2 linux nowait
-tty [2345]  /dev/tty3 linux nowait
-tty [2345]  /dev/tty4 linux nowait
-tty [2345]  /dev/tty5 linux nowait
-tty [2345]  /dev/tty6 linux nowait
+tty tty1 {
+	runlevel = "12345"
+	device   = "/dev/tty1"
+	term     = "linux"
+	noclear  = true
+	nowait   = true
+}
+tty tty2 {
+	runlevel = "2345"
+	device   = "/dev/tty2"
+	term     = "linux"
+	nowait   = true
+}
+tty tty3 {
+	runlevel = "2345"
+	device   = "/dev/tty3"
+	term     = "linux"
+	nowait   = true
+}
+tty tty4 {
+	runlevel = "2345"
+	device   = "/dev/tty4"
+	term     = "linux"
+	nowait   = true
+}
+tty tty5 {
+	runlevel = "2345"
+	device   = "/dev/tty5"
+	term     = "linux"
+	nowait   = true
+}
+tty tty6 {
+	runlevel = "2345"
+	device   = "/dev/tty6"
+	term     = "linux"
+	nowait   = true
+}

contrib/debian/finit.d/available/keyboard-setup.conf

@@ -1,2 +1,6 @@
 # Oneshot task to run once at bootstrap
-task [S] /lib/console-setup/keyboard-setup.sh -- Setting up console keyboard layout
+task keyboard-setup {
+	description = "Setting up console keyboard layout"
+	runlevel    = "S"
+	command     = "/lib/console-setup/keyboard-setup.sh"
+}

contrib/debian/finit.d/available/lightdm.conf

@@ -1 +1,5 @@
-service [3] lightdm -- Light Display Manager
+service lightdm {
+	description = "Light Display Manager"
+	runlevel    = "3"
+	command     = "lightdm"
+}

contrib/debian/finit.d/available/modules.conf

@@ -1,8 +1,2 @@
 ## Linux kernel modules to load
-#module fbcon
-#module button
-#module evdev
-#module loop
-#module psmouse
-#module mousedev
-#module 8139cp
+#modules = { "fbcon", "button", "evdev", "loop", "psmouse", "mousedev", "8139cp" }

contrib/debian/finit.d/available/plymouth-quit.conf

@@ -1,2 +1,6 @@
 # Need to stop plymouth, or it'll block stdin on tty1
-task [S] /usr/bin/plymouth quit -- Stopping Plymouth Boot Screen
+task plymouth {
+	description = "Stopping Plymouth Boot Screen"
+	runlevel    = "S"
+	command     = "/usr/bin/plymouth quit"
+}

contrib/debian/finit.d/available/rsyslogd.conf

@@ -1,3 +1,8 @@
 # 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"
+}

contrib/debian/finit.d/available/sntpd.conf

@@ -1,2 +1,8 @@
 # Simple NTP client (SNTP)
-service [2345] <net/route/default> env:-/etc/default/sntpd sntpd -n $SNTPD_OPTIONS -- SNTP client
+service sntpd {
+	description = "SNTP client"
+	runlevel    = "2345"
+	conditions  = { "net/route/default" }
+	envfile     = "-/etc/default/sntpd"
+	command     = "sntpd -n $SNTPD_OPTIONS"
+}

contrib/debian/finit.d/available/sshd.conf

@@ -1,2 +1,8 @@
 # Start SSH daemon as soon as basic networking comes up
-service [2345] <net/lo/up> 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"
+}

contrib/debian/finit.d/available/syslogd.conf

@@ -1,2 +1,7 @@
 # Start sysklogd as soon as possible, should always run if enabled
-service [S123456789] env:-/etc/default/syslogd syslogd -F $SYSLOGD_OPTIONS -- System logging daemon
+service syslogd {
+	description = "System logging daemon"
+	runlevel    = "S123456789"
+	envfile     = "-/etc/default/syslogd"
+	command     = "syslogd -F $SYSLOGD_OPTIONS"
+}

contrib/debian/finit.d/available/xdm.conf

@@ -1,4 +1,8 @@
 # Here we use XDM since it has few dependencies (relatively speaking).
 # It is also an example of a service without a -- description.
 # service [3] lxdm -- Lightweight Login Manager
-service [3] xdm -nodaemon -- X Display Manager
+service xdm {
+	description = "X Display Manager"
+	runlevel    = "3"
+	command     = "xdm -nodaemon"
+}

contrib/finit.conf

@@ -1,85 +1,149 @@
 # Sample finit.conf to demonstrate the syntax
 #
-host testbed
+hostname = "testbed"
 
 # Linux kernel modules to load
-module button
-module evdev
-module loop
-module psmouse
+modules = { "button", "evdev", "loop", "psmouse" }
 
 # Top-level cgroups and their default settings.  All groups mandatory
 # but more can be added, max 8 groups in total currently.  The cgroup
 # 'root' is also available, reserved for RT processes.  Settings are
 # as-is, only one shorthand 'mem.' exists, other than that it's the
 # cgroup v2 controller default names.
-cgroup init   cpu.weight:100
-cgroup user   cpu.weight:100
-cgroup system cpu.weight:9700 cpu.max:50000
+cgroup init   { cpu.weight = 100 }
+cgroup user   { cpu.weight = 100 }
+cgroup system { cpu.weight = 9700  cpu.max = 50000 }
 
 # Example extra cgroup
-cgroup maint  cpu.weight:100
+cgroup maint  { cpu.weight = 100 }
 
 # Runlevel to start after bootstrap, runlevel 'S'
-runlevel 2
+runlevel = 2
 
 # Network bringup script
-network service networking start
+network = "service networking start"
 
 # Max file size for each log file: 100 kiB, rotate max 4 copies:
 # log => log.1 => log.2.gz => log.3.gz => log.4.gz
-log size:100k count:4
+log {
+	size  = 100k
+	count = 4
+}
 
 # Virtual consoles to start getty on
-tty /dev/tty1
-tty /dev/tty2
-tty /dev/tty3
+tty tty1 { device = "/dev/tty1" }
+tty tty2 { device = "/dev/tty2" }
+tty tty3 { device = "/dev/tty3" }
 
 # Task to run if ctrl-alt-del is pressed.  This condition is asserted by
 # Finit upon receiving SIGINT (from the kernel).
-task <sys/key/ctrlaltdel> [12345789] initctl reboot -- Rebooting system
+task reboot {
+	description = "Rebooting system"
+	runlevel    = "12345789"
+	conditions  = { "sys/key/ctrlaltdel" }
+	command     = "initctl reboot"
+}
 
 # Task to run if the kernel gets a power fail condition is pressed.
 # Asserted by Finit upon receiving SIGPWR (from the kernel).
-task <sys/pwr/fail> [12345789] initctl poweroff -- Shutting down system
+task poweroff {
+	description = "Shutting down system"
+	runlevel    = "12345789"
+	conditions  = { "sys/pwr/fail" }
+	command     = "initctl poweroff"
+}
 
 # Alternative method instead of runparts
-#task [S] /etc/init.d/keyboard-setup start -- Setting up preliminary keymap
-#task [S] /etc/init.d/acpid start          -- Starting ACPI Daemon
-#task [S] /etc/init.d/kbd start            -- Preparing console
-#run [2] /etc/init.d/networking start      -- Start networking
+#task keyboard-setup {
+#	description = "Setting up preliminary keymap"
+#	runlevel    = "S"
+#	command     = "/etc/init.d/keyboard-setup start"
+#}
+#task acpid {
+#	description = "Starting ACPI Daemon"
+#	runlevel    = "S"
+#	command     = "/etc/init.d/acpid start"
+#}
+#task kbd {
+#	description = "Preparing console"
+#	runlevel    = "S"
+#	command     = "/etc/init.d/kbd start"
+#}
+#run networking {
+#	description = "Start networking"
+#	runlevel    = "2"
+#	command     = "/etc/init.d/networking start"
+#}
 
 # Services to be monitored and respawned as needed
 
-# klgod and syslogd are placed in the maint cgroup
-cgroup.maint
-service [2345] <pid/syslogd> klogd -n     -- Kernel logging server
-service [2345] syslogd -n                 -- Syslog server
+# klogd and syslogd are placed in the maint cgroup.  There is no
+# "current cgroup" to switch in this format, every block names its own.
+service klogd {
+	description = "Kernel logging server"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	cgroup maint {}
+	command     = "klogd -n"
+}
+service syslogd {
+	description = "Syslog server"
+	runlevel    = "2345"
+	cgroup maint {}
+	command     = "syslogd -n"
+}
 
-# gdm in the system cgroup (default when read from it's own .conf file)
-cgroup.system
-service [3] cgroup:cpu.weight:250,mem.max:10M gdm -- GNOME Display Manager
+# gdm gets its own limits inside the system group, which is where
+# services end up when no cgroup block is given.
+service gdm {
+	description = "GNOME Display Manager"
+	runlevel    = "3"
+	cgroup system {
+		cpu.weight = 250
+		memory.max = 10M
+	}
+	command     = "gdm"
+}
 
 # Start SSH daemon with opts from /etc/default/ssh (if available), move
-# to user cgroup with cpu.weight:250.  Default for services is system
-# group.  Default weight in user group is 100 (above).  Max length of
-# cgroup argument is (currently) 63 chars.
-#
-# Notice alternative syntax where current cgroup is only set for this
-# particular service.
-service [2345] cgroup.user:cpu.weight:250,mem.max:10M env:-/etc/default/ssh /usr/sbin/sshd -D $SSHD_OPTS -- OpenSSH daemon
+# to user cgroup with cpu.weight 250.  Default weight in the user group
+# is 100 (above).
+service sshd {
+	description = "OpenSSH daemon"
+	runlevel    = "2345"
+	envfile     = "-/etc/default/ssh"
+	cgroup user {
+		cpu.weight = 250
+		memory.max = 10M
+	}
+	command     = "/usr/sbin/sshd -D $SSHD_OPTS"
+}
 
 # The BusyBox ntpd does not use syslog when running in the foreground
 # So we use this trick to redirect stdout/stderr to a log file.  The
 # log file is rotated with the above settings.  The condition declares
-# a dependency on a system default route (gateway) to be set.  A single
-# <!> at the beginning means ntpd does not respect SIGHUP for restart.
-service [2345] <!net/route/default> log:/var/log/ntpd.log ntpd -n -l -I eth0 -- NTP daemon
+# a dependency on a system default route (gateway) to be set.  ntpd
+# does not respect SIGHUP, so Finit restarts it on reload instead.
+service ntpd {
+	description   = "NTP daemon"
+	runlevel      = "2345"
+	conditions    = { "net/route/default" }
+	reload-signal = "none"
+	log { file = "/var/log/ntpd.log" }
+	command       = "ntpd -n -l -I eth0"
+}
 
 # Run start scripts from this directory
-# runparts /etc/start.d
+#runparts = "/etc/start.d"
 
-# For multiple instances of the same service, add :ID somewhere between
-# the service/run/task keyword and the command.
-service :80   [2345] /sbin/httpd -f -h /http -p 80   -- Web server
-service :8080 [2345] /sbin/httpd -f -h /http -p 8080 -- Old web server
+# For multiple instances of the same service, add :ID to the block title.
+service httpd:80 {
+	description = "Web server"
+	runlevel    = "2345"
+	command     = "/sbin/httpd -f -h /http -p 80"
+}
+service httpd:8080 {
+	description = "Old web server"
+	runlevel    = "2345"
+	command     = "/sbin/httpd -f -h /http -p 8080"
+}

contrib/void/finit.conf

@@ -3,24 +3,34 @@
 
 ## Runlevel to start after bootstrap, runlevel 'S'
 # Default is 2
-#runlevel 2
+#runlevel = 2
 
 # Top-level cgroups and their default settings.  All groups mandatory
 # but more can be added, max 8 groups in total currently.  The cgroup
 # 'root' is also available, reserved for RT processes.  Settings are
 # as-is, only one shorthand 'mem.' exists, other than that it's the
 # cgroup v2 controller default names.
-#cgroup init   cpu.weight:100
-#cgroup user   cpu.weight:100
-#cgroup system cpu.weight:9700
+#cgroup init   { cpu.weight = 100  }
+#cgroup user   { cpu.weight = 100  }
+#cgroup system { cpu.weight = 9700 }
 
 # Task to run if ctrl-alt-del is pressed.  This condition is asserted by
 # Finit upon receiving SIGINT (from the kernel).
-#task <sys/key/ctrlaltdel> [12345789] initctl reboot -- Rebooting system
+#task reboot {
+#	description = "Rebooting system"
+#	runlevel    = "12345789"
+#	conditions  = { "sys/key/ctrlaltdel" }
+#	command     = "initctl reboot"
+#}
 
 # Task to run if the kernel gets a power fail condition is pressed.
 # Asserted by Finit upon receiving SIGPWR (from the kernel).
-#task <sys/pwr/fail> [12345789] initctl poweroff -- Shutting down system
+#task poweroff {
+#	description = "Shutting down system"
+#	runlevel    = "12345789"
+#	conditions  = { "sys/pwr/fail" }
+#	command     = "initctl poweroff"
+#}
 
 ## Bootstrap services and tasks
 # Can be listed here or in /etc/finit.d/*.conf

contrib/void/finit.d/available/acpid.conf

@@ -1,3 +1,7 @@
 # Handle PWR button to shutdown/reboot -- useful in Qemu (virt-manager)
 # Depends on syslogd having started. Redirect any output to log.
-service [2345] acpid -f -- ACPI daemon
+service acpid {
+	description = "ACPI daemon"
+	runlevel    = "2345"
+	command     = "acpid -f"
+}

contrib/void/finit.d/available/crond.conf

@@ -1 +1,6 @@
-service [2345] <pid/syslogd> crond -f -S -c /etc/crontabs -- Cron daemon
+service crond {
+	description = "Cron daemon"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	command     = "crond -f -S -c /etc/crontabs"
+}

contrib/void/finit.d/available/dhcpcd.conf

@@ -1 +1,5 @@
-service [2345] dhcpcd -B -M -- DHCP client
+service dhcpcd {
+	description = "DHCP client"
+	runlevel    = "2345"
+	command     = "dhcpcd -B -M"
+}

contrib/void/finit.d/available/dmeventd.conf

@@ -1 +1,5 @@
-service [S12345] dmeventd -f -- Device mapper event daemon
+service dmeventd {
+	description = "Device mapper event daemon"
+	runlevel    = "S12345"
+	command     = "dmeventd -f"
+}

contrib/void/finit.d/available/getty.conf

@@ -1,4 +1,19 @@
 # Consoles to start Finit built-in getty on when system is up
-tty [12345] /dev/tty1 noclear nowait
-tty [2345]  /dev/tty2 noclear nowait
-tty [2345]  /dev/tty3 noclear nowait
+tty tty1 {
+	runlevel = "12345"
+	device   = "/dev/tty1"
+	noclear  = true
+	nowait   = true
+}
+tty tty2 {
+	runlevel = "2345"
+	device   = "/dev/tty2"
+	noclear  = true
+	nowait   = true
+}
+tty tty3 {
+	runlevel = "2345"
+	device   = "/dev/tty3"
+	noclear  = true
+	nowait   = true
+}

contrib/void/finit.d/available/keymap.conf

@@ -1,2 +1,6 @@
 # Oneshot task to run once at bootstrap
-task [S] zcat /etc/keymap/se.bmap.gz | loadkmap -- Loading keymap
+task keymap {
+	description = "Loading keymap"
+	runlevel    = "S"
+	command     = "zcat /etc/keymap/se.bmap.gz | loadkmap"
+}

contrib/void/finit.d/available/lxdm.conf

@@ -1 +1,5 @@
-service [2345] lxdm -- Lightweight Login Manager
+service lxdm {
+	description = "Lightweight Login Manager"
+	runlevel    = "2345"
+	command     = "lxdm"
+}

contrib/void/finit.d/available/modules.conf

@@ -1,7 +1,3 @@
 ## Linux kernel modules to load
-#module fbcon
-#module button
-#module evdev
-#module mousedev
-#module 8139cp
-module softdog
+# Other candidates: fbcon, button, evdev, mousedev, 8139cp
+modules = { "softdog" }

contrib/void/finit.d/available/ntpd.conf

@@ -1,2 +1,8 @@
 # Silly Busybox ntpd has no option to use syslog when running in foreground
-service [2345] <pid/syslogd> log ntpd -n -N -p pool.ntp.org -- NTP daemon
+service ntpd {
+	description = "NTP daemon"
+	runlevel    = "2345"
+	conditions  = { "pid/syslogd" }
+	log { }
+	command     = "ntpd -n -N -p pool.ntp.org"
+}

contrib/void/finit.d/available/sshd.conf

@@ -1,2 +1,6 @@
 # Start SSH daemon as soon as basic networking comes up
-service [2345] /usr/sbin/sshd -D -- OpenSSH daemon
+service sshd {
+	description = "OpenSSH daemon"
+	runlevel    = "2345"
+	command     = "/usr/sbin/sshd -D"
+}

contrib/void/finit.d/available/syslog.conf

@@ -1,4 +1,13 @@
 # Start syslogd as soon as possible, should always run
 # Start klogd as soon as possible, but after syslogd
-service [S12345] syslogd -n             -- Syslog daemon
-service [S12345] <pid/syslogd> klogd -n -- Kernel log daemon
+service syslogd {
+	description = "Syslog daemon"
+	runlevel    = "S12345"
+	command     = "syslogd -n"
+}
+service klogd {
+	description = "Kernel log daemon"
+	runlevel    = "S12345"
+	conditions  = { "pid/syslogd" }
+	command     = "klogd -n"
+}

contrib/void/finit.d/available/uuidd.conf

@@ -1 +1,7 @@
-service @uuidd:uuidd [2345] uuidd -F -- UUID generation daemon
+service uuidd {
+	description = "UUID generation daemon"
+	runlevel    = "2345"
+	user        = "uuidd"
+	group       = "uuidd"
+	command     = "uuidd -F"
+}

dbus-1/.gitignore

@@ -0,0 +1,2 @@
+/Makefile
+/Makefile.in

dbus-1/Makefile.am

@@ -0,0 +1,6 @@
+EXTRA_DIST          = org.finit.conf
+
+if DBUS
+dbuspolicydir       = $(datadir)/dbus-1/system.d
+dist_dbuspolicy_DATA = org.finit.conf
+endif

dbus-1/org.finit.conf

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE busconfig PUBLIC
+ "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<!--
+  System-bus policy for finit.
+
+  finit (PID 1, root) owns the `org.finit` well-known name.  The
+  policy below lets unprivileged callers introspect, read
+  properties, and query service / condition state, but disallows
+  every state-changing method at the broker.  finit *also* enforces
+  per-method authorisation itself (LINK_METHOD_PRIVILEGED), so
+  defense-in-depth: even if a permissive policy is installed by
+  mistake, finit rejects unprivileged state changes.  It reads the
+  caller from SO_PEERCRED on the local bus, and on the system bus it
+  asks the broker who sent each privileged call, via
+  GetConnectionUnixUser.
+-->
+<busconfig>
+
+  <!-- Only finit (root) may own the org.finit bus name. -->
+  <policy user="root">
+    <allow own="org.finit"/>
+    <allow send_destination="org.finit"/>
+    <allow receive_sender="org.finit"/>
+  </policy>
+
+  <!-- Everyone may introspect, read properties, and call the
+       read-only Manager1 / Cond1 methods.  Signals fan out
+       unconditionally. -->
+  <policy context="default">
+    <allow send_destination="org.finit"
+           send_interface="org.freedesktop.DBus.Introspectable"/>
+    <allow send_destination="org.finit"
+           send_interface="org.freedesktop.DBus.Peer"/>
+    <allow send_destination="org.finit"
+           send_interface="org.freedesktop.DBus.Properties"
+           send_member="Get"/>
+    <allow send_destination="org.finit"
+           send_interface="org.freedesktop.DBus.Properties"
+           send_member="GetAll"/>
+
+    <allow send_destination="org.finit"
+           send_interface="org.finit.Manager1"
+           send_member="ListServices"/>
+    <allow send_destination="org.finit"
+           send_interface="org.finit.Manager1"
+           send_member="GetService"/>
+
+    <allow send_destination="org.finit"
+           send_interface="org.finit.Cond1"
+           send_member="Get"/>
+    <allow send_destination="org.finit"
+           send_interface="org.finit.Cond1"
+           send_member="List"/>
+    <allow send_destination="org.finit"
+           send_interface="org.finit.Cond1"
+           send_member="Dump"/>
+
+    <allow receive_sender="org.finit"/>
+  </policy>
+
+</busconfig>

doc/ChangeLog.md

@@ -3,6 +3,380 @@ Change Log
 
 All relevant changes are documented in this file.
 
+[5.0][UNRELEASED]
+--------------------
+
+### Changes
+
+- keventd is now a full device manager, promoted from the power supply
+  monitor it was in v4, and the device management defaults have swapped:
+  keventd is enabled by default (`--without-keventd` opts out, libblkid is
+  required to build it), while the hotplug plugin, which runs an external
+  `udevd`, `mdevd`, or `mdev`, is now opt-in.  With the plugin enabled,
+  keventd steps back to passive mode and monitors only power supply
+  events, as before.  As the system device manager it replaces mdev,
+  mdevd, and udevd, and handles:
+
+    * udev rules: an engine covering most of the udev(7) grammar --
+      parent-chain matching, `PROGRAM`/`RESULT`, `IMPORT`, `RUN`,
+      `GOTO`/`LABEL`, and the standard substitutions -- reading the usual
+      `udev/rules.d` directories under `/lib`, `/run`, and `/etc` with
+      udev's precedence and masking.  A curated ruleset derived from eudev
+      3.2.14 is installed by default, `--without-udev-rules` skips it.
+      See [Device Manager](keventd.md) for the supported subset and the
+      few deliberate divergences
+
+    * builtins used by the ruleset: `blkid`, `hwdb`, `input_id`, `kmod`,
+      `net_id`, `path_id`, and `usb_id`
+
+    * device nodes with per-subsystem default permissions, persistent
+      symlinks (`/dev/disk/by-uuid`, `by-label`, `by-id`, `by-path`, plus
+      `by-id`/`by-path` for input, serial, sound, v4l, and tape), kernel
+      firmware load requests, and module loading from `MODALIAS`
+
+    * predictable network interface names via the eudev ruleset,
+      `net.ifnames=0` on the kernel command line keeps classic names.
+      **Note:** switching a system over to keventd can rename its NICs
+
+    * coldplug: as device manager keventd starts with `-c`, replaying add
+      events for hardware present at boot.  The `pid/keventd` condition
+      is deferred until the coldplug queue has drained, so services
+      gating on it can assume `/dev` is populated and symlinks are live
+
+    * `keventd -S`, the `udevadm settle` equivalent, asks the running
+      daemon over D-Bus and falls back to polling the kernel's uevent
+      sequence number
+
+    * libudev compatibility: per-device properties in `/run/udev/data`
+      and processed uevents rebroadcast to netlink group 0x4, so
+      libudev-zero consumers, e.g. compositors and libinput, see hotplug
+      events
+
+    * new conditions for the service engine: `dev/<node>` for device
+      nodes, `class/<subsystem>/<name>` for sysfs class devices without a
+      node (LEDs, IIO, DSA ports), and `driver/<name>`, asserted while a
+      driver is bound to at least one device
+
+- Generated `/run/finit/system/*.conf` files for bundled services (keventd,
+  watchdogd, runparts) are now read before `/lib/finit/system/*.conf` instead
+  of after.  Built-ins can now be referenced in `if:` statements from system
+  .conf files and overridden by name from both `/lib/finit/system` and
+  `/etc/finit.d`, the latter is still always read last
+- The `dbus.so` plugin, which starts an external `dbus-daemon`, is now enabled
+  by default.  It does nothing on systems without a `dbus-daemon` installed,
+  and `--disable-dbus-plugin` opts out.  The daemon it used to register from C
+  now lives in `20-dbus.conf`, and the directories it needs in
+  `tmpfiles.d/dbus.conf`, so both can be overridden from `/etc` like any other
+  system file.  Those directories are no longer chowned to `messagebus`,
+  matching how Finit ships directories for other daemons
+- The bundled `sulogin` and `watchdogd` are now built and installed by
+  default, like keventd and the D-Bus support.  `--without-sulogin` and
+  `--without-watchdog` opt out.  Note, Finit starts `watchdogd` by itself
+  when the WDT device node exists
+- The `tty` block takes `passenv`, which the line-based format has had since
+  v4.4 (issue #286) and the block format was missing
+- New `provides` setting for run/task/service/sysv blocks, naming conditions
+  the service asserts in addition to its own `pid/<ident>`.  Lets variants of
+  one service, qualified with `if`, share the barrier condition downstream
+  services wait for, which a block title alone could not express.  Any
+  namespace is allowed, and a second claim on the same condition is refused
+  with a warning naming the owner
+- The `command` setting in a block takes a list of candidates for the same
+  service, `command = { "/lib/systemd/systemd-udevd", "-udevd" }`, and Finit
+  starts the first one it finds.  The line-based format could only express
+  this by repeating the whole stanza per candidate
+- Finit now ships with a built-in brokerless D-Bus implementation, **libink**,
+  exposing the running init system as a peer on its own private bus at
+  `/run/finit/bus`, and -- opportunistically -- registering `org.finit` on the
+  standard system bus when a `dbus-daemon` is reachable.  No external
+  `libdbus`/`sd-bus`/`GIO` dependency.  The bus implements the stock
+  `org.freedesktop.DBus`, `Peer`, `Introspectable`, and `Properties`
+  interfaces.  See [D-Bus Integration](dbus.md) for the full surface, build
+  flag, and `dbus-send`/`dbus-monitor` examples
+- New `org.finit.Manager1` interface at `/org/finit/manager`: `ListServices`,
+  `GetService`, `Start`/`Stop`/`Restart`/`Reload`, `SetRunlevel`, `SetDebug`,
+  `Signal`, `Suspend`, and the `Reboot`/`Halt`/`Poweroff` triplet, which take
+  a timeout argument arming the emergency shutdown bypass like `initctl -t`.
+  Read-only properties `Runlevel`, `PrevRunlevel`, `Version`; signals
+  `ServiceStateChanged (sss)` and `RunlevelChanged (ss)`
+- New `org.finit.Service1` interface at `/org/finit/service/<encoded>`, one
+  object per loaded service, with `Start`/`Stop`/`Restart`/`Reload` for
+  working off an object handle rather than passing the identity string around
+- New `org.finit.Cond1` interface at `/org/finit/cond`: `Get`, `Set`, `Clear`,
+  `List`, `Dump` for [user-defined conditions](conditions.md), with a
+  `ConditionChanged (ss)` signal
+- keventd serves `org.finit.Device1` on its own bus at `/run/keventd/bus`:
+  `Settle`, `Trigger`, `Info`, `RulesReload`, queue-state properties, and a
+  `DeviceProcessed (ss)` signal.  The `udevadm` settle/trigger/info
+  equivalents are thereby bus methods and `keventd -S` asks the running daemon
+  first.  Finit also gained a `Manager1.ConfigReloaded` signal, fired when
+  `initctl reload` completes, for external condition providers and monitoring
+- Privileged D-Bus methods accept root and members of the `--with-group`
+  group; everyone else is refused.  On the local bus the caller's uid and
+  groups come straight from the kernel (`SO_PEERCRED` + `SO_PEERGROUPS`), so
+  the check never blocks PID 1 on an NSS lookup.  Over the system bus the uid
+  is resolved from the broker (`GetConnectionUnixUser`) and privileged methods
+  are root-only.  Read-only methods are open
+- `initctl` now transparently routes through D-Bus when the bus is reachable,
+  with the legacy `INIT_SOCKET` transport as a fallback: `start`, `stop`,
+  `restart`, `reload`, `reload <svc>`, `reboot`, `halt`, `poweroff`,
+  `suspend`, `debug`, `signal`, `runlevel`, and `cond {get,set,clr}` all use
+  the new path.  Two new subcommands show up that have no legacy equivalent:
+
+    * `initctl monitor` -- streams every signal on the bus to the terminal,
+      one line per delivery (`HH:MM:SS iface.member(args)`), until
+      interrupted.  Same idea as `dbus-monitor`, but scoped to Finit and with
+      no address plumbing required.
+
+    * Issuing `initctl cond set/clr` over D-Bus also fires the
+      `Cond1.ConditionChanged` signal, so observers see user-driven state
+      changes the same way they see service-driven ones.
+
+- Restart log now spells out the signal name and flags core dumps,
+  e.g. `killed by SIGKILL` or `killed by SIGSEGV, core dumped`, in place of
+  the bare numeric `by signal: N`.  Gives operators a much stronger breadcrumb
+  when a daemon dies unexpectedly
+
+### Fixes
+
+- Reject a .conf file that declares the same block title twice.  The title is
+  the service identity and libConfuse merges two sections sharing one, so the
+  file loaded as a single service holding a mix of both declarations,
+  silently.  This hit `system/10-hotplug.conf`, where the two `udevd` blocks
+  left only the second command, dropping the service on systems that only have
+  `systemd-udevd`.  The same title in another file is still how a system .conf
+  is overridden
+- Remove stale daemon-owned (`pid:!`) pidfiles after unclean exits.  When a
+  daemon dies via SIGKILL/OOM/segfault, or exits early during startup, its
+  pidfile lingers and can prevent the next instance from starting --
+  `dbus-daemon` for example refuses to start when its pidfile already exists,
+  so Finit's restart loop gives up.  Finit now drops the file when it still
+  names the just-reaped PID and that PID is no longer alive (the liveness
+  check guards against PID reuse).  This is a controlled exception to the
+  long-standing rule that Finit does not touch service-owned pidfiles
+- Fix misspelled `SIGUNKOWN` returned by `sig_name()` for unknown signal
+  numbers, now spelled correctly as `SIGUNKNOWN`.  Surfaced by the new restart
+  log above
+
+[4.17][] - 2026-04-28
+---------------------
+
+### Changes
+
+- Add Plymouth boot splash plugin to manage the `plymouthd` lifecycle across boot,
+  `switch_root`, and shutdown.  Activated by the `splash` kernel command line
+  argument.  By Aaron Andersen
+- Add `tty:` option for run/task/service stanzas to acquire a controlling
+  terminal.  The device is opened as stdin, set as the session's controlling TTY
+  via `TIOCSCTTY`, and `TERM` is set automatically — `linux` for virtual terminals
+  and `vt102` for serial lines.  By Ollie Gutierrez
+- Improve console output atomicity at boot and shutdown: description and status
+  (`[ OK ]` / `[FAIL]`) are emitted in a single write so kernel messages cannot
+  split them.  If output has been scrolled away, the description is re-printed
+  before the final status line.  Console buffer is drained with `tcdrain(2)` and
+  ANSI attributes are reset before handing control back to the kernel at
+  shutdown/reboot
+
+### Fixes
+
+- Fix reverse-dependency condition handling on reload: when a service without
+  SIGHUP support is reloaded, its condition is now cleared immediately so
+  dependents transition to `STOPPING` before `SIGTERM` is sent to the parent,
+  preventing them from crashing with an incremented restart counter
+- Fix `/var/tmp` mode in `tmpfiles.d/var.conf` from `0777` to `1777` (sticky bit)
+  to match `/tmp`, by Aaron Andersen
+- Fix potential memory corruption in config parser: stale pointer captures of
+  `PATH` and `SHELL` at startup could dangle after environment modification;
+  `conf_reset_env()` now reads from the live environment instead, by Vasily Zubko
+- Fix plugin name registration: replace `__FILE__` macro with explicit string
+  literals in all plugin structs and debug messages, preventing subtle build-
+  system–dependent macro expansion issues, by Vasily Zubko
+
+
+[4.16][] - 2026-02-27
+---------------------
+
+### Changes
+
+- Add `initctl switch-root` command and plugin hook point.  Useful for
+  systems requiring early boot tasks like LUKS unlock, LVM activation,
+  or network boot before mounting the real root, by Aaron Andersen
+- Set USER and LOGNAME environment variables when dropping privileges.
+  Fixes issues with software like rootless Podman that determines user
+  identity from environment variables, by Aaron Andersen
+- Add `remain:yes` option for run/task oneshot commands, similar to the
+  systemd `RemainAfterExit=yes`, by Aaron Andersen
+- Clear service conditions on `initctl reload NAME` to ensure dependent
+  services are properly updated
+- Run service `stop:` and `reload:` scripts as non-blocking processes,
+  preventing Finit from stalling on long-running helper scripts
+- Guard shutdown with timer watchdog to detect and debug shutdown hangs
+- Add `~` condition prefix to propagate reload from a dependency to the
+  dependent service.  E.g., `<!~pid/netd>` means not only a regular
+  condition, but when `netd` reloads, restart this service too.  Similar
+  to systemd's directive `PropagatesReloadTo=`, but declared on the
+  consumer side.  Issue #416
+- `tmpfiles`: add support for `-E` and `--exclude-prefix` flags
+  contributed by Aaron Andersen
+
+### Fixes
+- Fix #464: invalid user:group examples in cgroups.md
+- Fix #466: elogind path for Debian-based distros, by Jackie Liu
+- Fix #467: TTY services stuck in restart state after non-zero exit.
+  Throttling logic introduced in v4.15 had duplicate checks causing
+  infinite timer loop, and TTYs lacked default restart timeout
+- Fix #475: clear pid condition on service collection to fix stale
+  deps.  When a service crashes (SIGKILL), the RUNNING → HALTED path
+  bypasses STOPPING where `cond_clear()` is normally called, leaving
+  dependents stuck
+- Fix #476: dependents not restarted after SIGHUP reload of service in
+  dependency chain.  Add `service_step_all()` at end of reload cycle to
+  guarantee convergence after conditions are reasserted.  See also the
+  new `~` condition prefix (above) to propagate reload to dependents
+- Fix #478: fix `<dev/foo>` conditions at boot, conditions that exist
+  before inotify was set up.  Found and fixed by Mattias Walström
+- Fix reload of SIGHUP-capable services incorrectly disrupting their
+  dependents.  E.g., `initctl reload syslogd` would stop dbus, dnsmasq,
+  etc. even though syslogd handles SIGHUP gracefully and its PID persists
+- Only remove managed pidfiles in service cleanup.  For SysV services
+  with `pid:!/path`, the pidfile belongs to the service itself and Finit
+  should not delete it
+- Silence spurious cgroup warnings for short-lived processes where the
+  kernel reaps the child before cgroup assignment completes
+- Fix handling of already-mounted cgroups in `cgroup_init()`, can occur
+  after switch_root or in container environments
+- Improve cgroups documentation clarity, grammar, and examples
+
+
+[4.15][] - 2026-01-01
+---------------------
+
+The Finit project now has a new home page: <https://finit-project.github.io>
+
+### Changes
+- Change default reboot to SOC reset from WDT reset, issue #460
+- Bump required versions of libite (v2.6.2) and libuev (v2.4.1)
+- Allow longer service identifiers (`:id`), up to 64 characters
+- Allow skipping bootstrap wait (180 sec) with Ctrl-C
+- Unlock `initctl` commands start/stop/restart/reload service during bootstrap,
+  shutdown, and reboot.  Also, allow `initctl reload` in bootstrap. This makes
+  it possible to start manual:yes type services at botostrap, for example, which
+  has been a common feature request
+- Add support for `clone3()` syscall with atomic cgroup assignment, from Linux
+  kernel 5.3+.  Eliminates race conditions where forked processes (e.g., logger
+  processes) ended up in wrong cgroups. Falls back to `fork()` on older kernels
+- Add support for cgroup delegation, useful for, e.g., container runtimes
+  creating sub-groups for the container instance's processes
+- Add cgroup leaf name override: `cgroup.system,name:udevd` allows using
+  descriptive names like `/system/udevd/` instead of filename derived names
+  like `/system/10-hotplug/`.  Syntax supports combining with other options:
+  `cgroup.system,name:foo,delegate,cpu.max:10000`
+- Add support for Linux capabilities, allowing services to run with minimal
+  required privileges instead of running as root.  Uses the modern IAB API
+  (Inheritable, Ambient, Bounding) from libcap.  By Aaron Andersen
+- Add support for supplementary groups for services.  Uses the syntax
+  `@user:group,sup1,sup2` to explicitly specify supplementary groups, in
+  addition to reading group membership from `/etc/group`.  By Aaron Andersen
+- Add CPU throttled information to `initctl` output, showing when a service
+  has been throttled due to reaching its CPU quota
+- Add memory field to `initctl --json` status output for cgroup-enabled
+  services
+- Default to user and group `root` (UID 0) for services
+- Always check that service user and group resolve to valid UID/GID pairs,
+  otherwise log error and refuse to start service
+- Hide cursor at boot and shutdown for cleaner visual experience
+- Rename `tty` services early from `init` -> `getty` even though no getty
+  process has been started yet.  This to aid in boot timing detection using
+  tools like `bootchartd` (BusyBox version or bootchart2 project) when Finit
+  only shows *"Please press Enter to activate this console."*
+- Services with `respawn` option (including TTYs) now delay retry on non-zero
+  exit codes instead of immediate respawn.  Prevents busy-loop when service
+  fails repeatedly, which on some systems may have a crippling effect
+
+### Fixes
+- Fix #453: RTC plugin fixes by Ming Liu, Atlas Copco
+- Fix #455: ANSI escape sequences logged by tools using glib logging,
+  caused by use of PTY instead of pipe for stdout/stderr redirection
+- Fix #462: `/dev/pts` mounted with wrong mode (400 instead of 620), causing
+  permission issues with pseudo-terminals
+- getty: fix terminal scrollback issues after login on console TTY.  Mouse
+  scroll wheel and Shift+PgUp/PgDn sometimes would not work properly
+- Fix flickering and artifacts in `initctl top`
+- Fix file descriptor leak in `initctl top`
+- Fix incorrect "max" limit reporting in `initctl [top|cgroup|--json]` output
+  for child cgroups.  Resolves effective limits by walking the cgroup hierarchy
+- Fix issue with running Finit under `bootchartd` (bootchart2 project), always
+  set `PATH` and `SHELL` envs early, before attempting to mount `/proc` et al
+- Always reset ownership and permissions on TTY device nodes before launching getty
+- Ensure mount/unmount skips `noauto` entries
+
+
+[4.14][] - 2025-08-29
+---------------------
+
+Minor bug fix release.
+
+### Changes
+ - Add exit status/signal info when a process dies, by Mattias Berthel
+ - Extend `service kill:SEC` to support up to 300 sec.
+ - Extend `norespawn` debug to cover `service_retry()`
+ - Build *without* libsystemd replacement by default
+
+### Fixes
+ - Fix #449: ALSA plugin fail-to-build-from-source
+ - Fix `sysv` stop command process environment, should be same as start
+ - Fix state machine ordering issue: enter new config generation *after*
+   services disabled in previous generation have been stopped
+
+
+[4.13][] - 2025-07-10
+---------------------
+
+> [!NOTE]
+> This release introduce a bare bones `libsystemd` replacement with an
+> `<systemd/sd-daemon>.h` include file.  Other systemd features are the
+> `reload:script` and `stop:script`, mimicking ExecReload and ExecStop.
+
+### Changes
+ - `initctl signal` command has been renamed to `initctl kill`
+ - Drop xz tarballs from distribution, gzip is good enough
+ - New `tmpfiles` stand-alone program, refactored from the existing
+   tmpfiles.d support in Finit, by Aaron Andersen, PR #439
+    - `--remove` command runs only the `r` and `R` rules
+    - `--create` is used for all other cases (bootstrap)
+ - All `notify:systemd` services now log with `logit` by default.  This
+   because it supports systemd style log severity, leading `"<NUM>"`
+ - Support for quoted arguments to run/task/service options, issue #441
+ - Clear command line arguments after bootstrap, issue #442
+ - Support for `stop:'script [args]'` to stop a sysv/service instead of
+   the common `foo-stop-start.sh stop`, or `SIGTERM`, issue #412
+ - Support for `reload:'script [args]'` to trigger a configuration
+   reload in a service, issue #446
+
+### Fixes
+ - Fix #437: buffer overflow in `initctl status`
+ - Fix #438: support very long command lines in `initctl ps/top`
+ - Fix #440: broken systemd and s6 readiness notification
+ - Fix #443: build warnings, by Ming Liu, Atlas Copco
+ - Fix #444: handle loooooong arguments, by Aaron Andersen
+ - Fix service's redirected stdout/stderr log priority in fallback mode,
+   when neither `logger` or `logit` is available.  This fix also checks
+   for systemd style log severity, leading `"<NUM>"` in log messages
+ - Ensure API socket used by `initctl` is non-blocking (event loop)
+
+
+[4.12][] - 2025-04-28
+---------------------
+
+### Changes
+ - Improve notify:s6 readiness compatibility, by Aaron Andersen
+ - Update `runparts` usage text
+
+### Fixes
+ - Fix variable overloading in urandom plugin
+ - Fix buffer overwrite in urandom plugin, reported by Aaron Andersen
+
+
 [4.11][] - 2025-03-27
 ---------------------
 
@@ -20,6 +394,11 @@ All relevant changes are documented in this file.
    the default `SIGTERM`
  - Fix pre/post/ready/cleanup script execution if service has an
    optional `env:file` (leading `-`)
+ - Fix blocked signals for pre/post/ready/cleanup scripts preventing
+   normal shutdown when a service/sysv is stopped in its setup state
+ - Fix issue where a pre:script creates a PID file in `/run` cause the
+   service to move from setup state to running.  Any `svc_t` in setup,
+   teardown, or cleanup state should be ignored in the pidfile plugin
 
 
 [4.10][] - 2025-03-03
@@ -1779,7 +2158,13 @@ Major bug fix release.
 
 * Initial release
 
-[UNRELEASED]: https://github.com/troglobit/finit/compare/4.11...HEAD
+[UNRELEASED]: https://github.com/finit-project/finit/compare/4.17...HEAD
+[4.17]: https://github.com/finit-project/finit/compare/4.16...4.17
+[4.16]: https://github.com/finit-project/finit/compare/4.15...4.16
+[4.15]: https://github.com/finit-project/finit/compare/4.14...4.15
+[4.14]: https://github.com/finit-project/finit/compare/4.13...4.14
+[4.13]: https://github.com/troglobit/finit/compare/4.12...4.13
+[4.12]: https://github.com/troglobit/finit/compare/4.11...4.12
 [4.11]: https://github.com/troglobit/finit/compare/4.10...4.11
 [4.10]: https://github.com/troglobit/finit/compare/4.9...4.10
 [4.9]:  https://github.com/troglobit/finit/compare/4.8...4.9

doc/Makefile.am

@@ -1,4 +1,12 @@
-docsdir   := @docdir@/doc
-docs_DATA  = config.md conditions.md distro.md plugins.md	\
-	     service.md signals.md svc-machine.png cmdline.md
-EXTRA_DIST = $(docs_DATA)
+SUBDIRS         = config
+EXTRA_DIST      = AUTHORS ChangeLog.md
+
+docsdir        := @docdir@/doc
+dist_docs_DATA  = build.md cmdline.md commands.md conditions.md 	\
+		  dbus.md						\
+		  distro.md example.md features.md index.md initctl.md	\
+		  keventd.md plugins.md requirements.md runlevels.md	\
+		  runparts.md service.md signals.md state-machine.md	\
+		  watchdog.md
+dist_docs_DATA += img/logo.png img/svc-machine.png img/svc-machine.svg	\
+		  img/alpine-screenshot2.png

doc/README.md

@@ -1 +1 @@
-config.md
+index.md

doc/build.md

@@ -1,21 +1,19 @@
 Building Finit
 ==============
 
-* [Introduction](#introduction)
-* [Configure](#configure)
-* [Example](#example)
-* [Running](#running)
-* [Debugging](#debugging)
-
-
-Introduction
-------------
-
 Finit comes with a traditional configure script to control features and
-optional plugins to enable.  It depends on two external libraries:
+optional plugins to enable.  It depends on three external libraries:
 
 - [libuEv][], the event loop
 - [libite][] (-lite), much needed frog DNA
+- [libConfuse][], the parser behind the .conf format
+
+The bundled device manager, keventd, needs a fourth: libblkid from
+[util-linux][].  It reads the filesystem UUID and label off block
+devices, which is what the curated rules name the `/dev/disk/by-uuid/`
+and `/dev/disk/by-label/` symlinks after.  keventd is enabled by
+default, so this is a hard requirement unless you build with
+`--without-keventd`.
 
 > [!IMPORTANT]
 > Most free/open source software packages that use `configure` default
@@ -32,6 +30,8 @@ version of the above mentioned libraries.  Currently required versions:
 
 - libite v2.2.0, or later
 - libuEv v2.2.0, or later
+- libConfuse v3.3, or later
+- libblkid, any version, when keventd is enabled
 
 
 Configure
@@ -58,17 +58,44 @@ Below are a few of the main switches to configure:
   `/proc/cmdline`, this is *not recommended* since Finit may be running as the
   init for container apps that can see the host's `/proc` filesystem
 
+* `--disable-dbus`: Opt out of Finit's built-in D-Bus support, enabled by
+  default.  See [D-Bus Integration](dbus.md) for what it provides.  Not to
+  be confused with `--disable-dbus-plugin` below, which only governs
+  starting an external `dbus-daemon`
+
 * `--enable-alsa-utils-plugin`: Enable the optional `alsa-utils.so` sound plugin.
 
-* `--enable-dbus-plugin`: Enable the optional D-Bus `dbus.so` plugin.
+* `--disable-dbus-plugin`: Drop the `dbus.so` plugin, which launches
+  `dbus-daemon` at boot.  Enabled by default; the plugin does nothing on
+  a system that has no `dbus-daemon` installed, so opting out is only
+  needed to keep init from starting a bus on a system that has one.
+  Unrelated to the built-in bus, see `--disable-dbus` above.
 
 * `--enable-resolvconf-plugin`: Enable the `resolvconf.so` optional plugin.
 
 * `--enable-x11-common-plugin`: Enable the optional X Window `x11-common.so` plugin.
 
-* `--with-sulogin`: Enable bundled `sulogin` program.  Default is to use the
-  system `sulogin(8)`.  The sulogin shipped with Finit *allows password-less*
-  login if the `root` user is disabled or has no password at all.
+* `--without-keventd`: Drop the bundled device manager, for systems that
+  run mdev, mdevd, or udevd instead.  Enabled by default, and the only
+  thing that pulls in libblkid.  See [Bundled Device Manager](keventd.md).
+
+* `--without-sulogin`: Drop the bundled `sulogin`, enabled by default,
+  and use the system `sulogin(8)` instead.  The one shipped with Finit
+  *allows password-less* login if the `root` user is disabled or has no
+  password at all.  `--with-sulogin=USER` prompts for another user's
+  password than `root`'s.
+
+* `--without-watchdog`: Drop the bundled `watchdogd`, enabled by default
+  on `/dev/watchdog`, `--with-watchdog=DEV` selects another device.
+  Finit starts it when the device node exists, see [Watchdog](watchdog.md).
+
+* `--with-libsystemd`: Build the replacement `libsystemd`, which lets
+  programs that use `sd_notify()` talk to Finit without systemd.  Off by
+  default because it installs `libsystemd.so.0` in `$libdir`: on a host
+  that has the real one, ours shadows it in the loader cache and every
+  program linking it, `dbus-daemon` and `udevd` included, loses the
+  symbols it needs.  Safe on a systemd-free system, which is the point
+  of it.
 
 For more configure flags, see <kbd>./configure --help</kbd>
 
@@ -95,8 +122,7 @@ Then configure, build and install:
 
 ```shell
 $ ./configure --prefix=/usr                 --exec-prefix=         \
-              --sysconfdir=/etc             --localstatedir=/var   \
-              --with-keventd                --with-watchdog
+              --sysconfdir=/etc             --localstatedir=/var
 $ make
 .
 .
@@ -124,6 +150,60 @@ Linux config to:
 > `/etc/fstab`.
 
 
+Testing
+-------
+
+`make check` runs the test suite in a private namespace, so it is safe
+on a running system.  It needs `unshare` and, on Ubuntu, unprivileged
+user namespaces enabled:
+
+```shell
+sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
+make check
+```
+
+The D-Bus message parser is the only place in Finit where bytes off a
+socket become pointers, so it also has a fuzz target.  `make check`
+runs it as a fixed sweep, which takes milliseconds and needs nothing
+beyond the normal build.  To fuzz it properly, build it with clang and
+libFuzzer:
+
+```shell
+clang -fsanitize=fuzzer,address -DLINK_FUZZ_LIBFUZZER -D_GNU_SOURCE \
+      -I libink -I . -o fuzz-msg-parse                              \
+      test/src/fuzz-msg-parse.c libink/*.c
+mkdir -p .fuzz-corpus
+./fuzz-msg-parse .fuzz-corpus -max_total_time=300
+```
+
+Give it a corpus directory as above and it saves what it learns there,
+so the next run picks up where this one left off instead of starting
+cold.  Nothing writes to it unless you name it: without the argument
+libFuzzer keeps everything in memory and the run leaves only crashes
+behind.  `make distclean` clears the corpus and the target.
+
+Once a corpus has grown, most of it reaches code some earlier input
+already reached.  Minimise it:
+
+```shell
+./fuzz-msg-parse -merge=1 .fuzz-corpus-min .fuzz-corpus
+rm -rf .fuzz-corpus && mv .fuzz-corpus-min .fuzz-corpus
+```
+
+Run `./configure` first, the target needs the generated `config.h`.
+If the link fails with `cannot find -lstdc++`, install the `libstdc++`
+headers matching the newest GCC on the system, not the default one:
+clang picks the newest tree it finds, and that is the one that needs
+them.  CI runs this target on every pull request, carrying its
+corpus between runs so it reaches deeper over time.
+
+Feed a file back to the target to reproduce a find:
+
+```shell
+./fuzz-msg-parse crash-3f2a...
+```
+
+
 Running
 -------
 
@@ -181,7 +261,11 @@ Notice the `--` separator.
 To debug startup issues, in particular issues with getty/login, add
 the following to your Finit .conf file:
 
-    tty [12345789] notty noclear
+    tty board {
+        runlevel = "12345789"
+        notty    = true
+        noclear  = true
+    }
 
 The `notty` option ensures reusing the stdin/stdout set up by the
 kernel.  Remember, this is only for debugging and would leave your
@@ -196,7 +280,8 @@ it only for debugging start up issues when Finit crashes.
 > None of these options should be enabled on production systems since
 > they can potentially give a user root access.
 
-
-[1]:       ftp://troglobit.com/finit/finit-4.3.tar.gz
+[1]:       https://github.com/finit-project/finit/releases/download/4.3/finit-4.3.tar.gz
 [libuEv]:  https://github.com/troglobit/libuev
 [libite]:  https://github.com/troglobit/libite
+[libConfuse]: https://github.com/libconfuse/libconfuse
+[util-linux]: https://github.com/util-linux/util-linux

doc/cmdline.md

@@ -29,7 +29,7 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
   system bootstrap.
 
   Very useful for selecting different boot modes, e.g. manufacturing test,
-  firmware upgrade, or rescue mode.
+  firmware upgrade, or [rescue mode][rescue].
 
 > [!NOTE]
 > `<boot/...>` conditions cannot be cleared with `initctl`!
@@ -39,10 +39,10 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 
         ./configure --with-config=/etc/finit.conf
 
-   Useful when starting up in various rescue mode, factory, or
+   Useful when starting up in various [rescue mode][rescue], factory, or
    production test setups.  Use the top-level configuration file
-   directive `rcsd /path/to/finit.d` to override the default
-   rcS.d directory.
+   setting `rcsd = "/path/to/finit.d"` to override the default rcS.d
+   directory.
 
 * `finit.debug[=bool]`: Enable finit debug.  This is operated
 	independently of the kernel `debug` setting.  New as of Finit v4.
@@ -75,7 +75,7 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 * `init=/bin/sh`: Bypass system default init and tell kernel to start a
 	shell.  Note, this shell is very limited and does not support
 	signals and has no job control.  Recommend using, and modifying,
-	`rescue` mode instead.
+	[`rescue` mode][rescue] instead.
 
 * `loglevel=<0-7>`, sets the kernel's log level, which is more granular
   than `debug`.  Also, when `loglevel=7`, Finit will *not disable*
@@ -90,12 +90,11 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 * `quiet`: Suppress kernel logging to console, except for warnings and
   errors.  Also, see `loglevel` and `quiet` above.
 
-* `rescue`: Start rescue/maintenance mode.  If your system comes with
-    the bundled `sulogin` program (Finit, or from util-linux/Busybox),
-    you will be given a root login to a maintenance shell.  However, if
-    `sulogin` is missing, the file `/lib/finit/rescue.conf` is read and
-    the system booted in a limited fallback mode.  See [config.md][]
-    for more information.
+* `rescue`: Start [rescue/maintenance mode][rescue].  If your system
+    comes with the bundled `sulogin` program (Finit, or from util-linux,
+    or Busybox), you will be given a root login to a maintenance shell.
+    However, if `sulogin` is missing, the file `/lib/finit/rescue.conf`
+    is read and the system booted in a limited fallback mode.
 
     This option can be disabled with `configure --without-rescue`
 
@@ -105,8 +104,9 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 * `single`, or `S`: Overrides the configured runlevel (default: 2) to go
     to after bootstrap by forcing it to runlevel 1, this is also known
     as single user mode.  Useful to debug startup problems.  All services
-    and TTYs in `[1]` will be started, so a `tty [1] @console nologin`
-    configuration presents you with a root console without login.
+    and TTYs in runlevel 1 will be started, so a `tty` block with
+    `runlevel = "1"`, `device = "@console"`, and `nologin = true`
+    presents you with a root console without login.
 
  * `1-9`, except `6`: override the configured `runlevel`.  Like the `S`
    and `rescue`, giving a single number on the kernel command line tells
@@ -116,5 +116,5 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 
 For more on kernel boot parameters, see the man page [bootparam(7)][].
 
-[config.md]:    config.md#rescue-mode
+[rescue]:       config/rescue.md
 [bootparam(7)]: https://www.man7.org/linux/man-pages/man7/bootparam.7.html

doc/commands.md

@@ -0,0 +1,13 @@
+Rebooting & Halting
+===================
+
+Traditionally, rebooting and halting a UNIX system is done by switching
+to the corresponding runlevel (0 or 6).  Over time this has changed and
+Finit comes with its own tooling providing: `shutdown`, `reboot`,
+`poweroff`, and `suspend`.  These commands are also available from the
+[`initctl`](initctl.md) tool.
+
+For compatibility reasons Finit listens to the same set of signals as
+BusyBox init.  This is not 100% compatible with SysV init, but clearly
+the more common combination for Finit.  For more details, see the
+[Signal](signals.md) section.

doc/conditions.md

@@ -1,37 +1,32 @@
-Finit Conditions
-================
+Conditions
+==========
 
-![The service state machine](svc-machine.png "The service state machine")
-
-* [Introduction](#introduction)
-* [Triggering](#triggering)
-* [Built-in Conditions](#built-in--conditions)
-* [Debugging](#debugging)
-* [Internals](#internals)
-
-
-Introduction
-------------
-
-Conditions are a relatively new addition to Finit, introduced in v3,
-with the intention of providing a mechanism for common synchronization
-problems.  For example:
+Conditions were added to Finit in v3 with the intention of providing a
+mechanism for common synchronization problems.  For example:
 
 - *"wait for service A to start before starting service B"*, or
 - *"wait for basic network access to be available"*
 
-Conditions are similar in syntax to declaring runlevels per service.
-They are specified within angle brackets `<>` and can be applied to any
-of the `service`, `task`, or `run` stanza.  Multiple conditions may be
-specified separated by comma.  Multiple conditions are logically AND'ed
+A condition is named in the `conditions` list of a `service`, `task`, or
+`run` block.  The list may hold several, and they are logically AND'ed
 during evaluation, i.e. all conditions must be satisfied in order for a
-service to run.
+service to run.  In running text, and in `initctl` output, a condition
+is written inside angle brackets, `<pid/syslogd>`.
 
-A special syntax, using a leading `!` in run/task/service conditions,
-denote if a:
+One prefix can be used on a condition:
 
- - service does not support `SIGHUP`
- - run/task should not block runlevel changes (i.e., bootstrap)
+ - `~` -- propagate reload from this dependency, see below
+
+The line-based format also accepts a leading `!` on the list, which is
+not a condition and not a negation.  It is a flag on the block, and it
+means two unrelated things depending on where it sits: a service does
+not support `SIGHUP` (noreload), or a run/task should not block
+runlevel changes, i.e. bootstrap.  Each of those is its own key here:
+
+| Line-based | Block format |
+|---|---|
+| `<!...>` on a service or sysv | `reload-signal = "none"` |
+| `<!...>` on a run or task | `required = false` |
 
 Finit guarantees by default that all run/tasks run (at least) once
 per runlevel.  For most tasks this is a good default, for example
@@ -40,7 +35,12 @@ that are unlikely to happen it is not. (See example below.)
 
 ### Example
 
-    service [2345] <pid/setupd,pid/zebra> /sbin/netd -- Network monitor
+    service netd {
+        description = "Network monitor"
+        runlevel    = "2345"
+        conditions  = { "pid/setupd", "pid/zebra" }
+        command     = "/sbin/netd"
+    }
 
 In this example the Network monitor daemon `netd` is not started until
 both the `pid/setupd` *and* `pid/zebra` conditions are satisfied.  A
@@ -55,15 +55,62 @@ being created, i.e., the service's default readiness notification.
 Another example is `dropbear`, it does not support `SIGHUP`, but we can
 also see optional sourcing of arguments from an environment file:
 
-    service [2345789] <!> env:-/etc/default/dropbear dropbear -F -R $DROPBEAR_ARGS -- Dropbear SSH daemon
+    service dropbear {
+        description   = "Dropbear SSH daemon"
+        runlevel      = "2345789"
+        reload-signal = "none"
+        envfile       = "-/etc/default/dropbear"
+        command       = "dropbear -F -R $DROPBEAR_ARGS"
+    }
 
 Finally, the weird "block runlevel changes" example.  Here we see what
 happens when Finit receives `SIGPWR`, sent from a power daemon like
 [powstatd(8)][].  A condition is asserted and a user can set up their
 own task to act on it.  We do not want this task to block Finit from
-moving to the next runlevel after bootstrap, so we set `<!>`:
+moving to the next runlevel after bootstrap, so we set
+`required = false`:
 
-    task [S0123456789] <!sys/pwr/fail> name:pwrfail initctl poweroff -- Power failure, shutting down
+    task pwrfail {
+        description = "Power failure, shutting down"
+        runlevel    = "S0123456789"
+        conditions  = { "sys/pwr/fail" }
+        required    = false
+        command     = "initctl poweroff"
+    }
+
+
+Propagating Reload in Dependencies
+-----------------------------------
+
+By default, when a service reloads during `initctl reload`, dependent
+services are paused (`SIGSTOP`) and simply resumed (`SIGCONT`) when the
+condition is reasserted.  This is correct for barrier-style dependencies
+like `<pid/syslogd>`, where dependents just need syslogd running and do
+not care if it reloads its config.
+
+For services that need to react when their upstream reloads, the `~`
+prefix propagates the reload from the dependency:
+
+    service svc_b {
+        description = "Needs A (barrier)"
+        conditions  = { "pid/svc_a" }
+        command     = "/sbin/svc_b"
+    }
+
+    service svc_c {
+        description   = "Propagate reload from B"
+        conditions    = { "~pid/svc_b" }
+        reload-signal = "none"
+        command       = "/sbin/svc_c"
+    }
+
+Here, `<~pid/svc_b>` means: propagate a reload of `svc_b` to `svc_c`.
+When `svc_b` reloads, `svc_c` will be restarted, because of
+`reload-signal = "none"`, instead of merely resumed.  If `svc_c`
+supported `SIGHUP`, it would be sent `SIGHUP` instead.
+
+This is similar to systemd's `PropagatesReloadTo=` directive, but
+declared on the consumer side rather than the provider side.
 
 
 Triggering
@@ -89,9 +136,15 @@ User-defined conditions are controlled using the `initctl cond set` and
 
 The purpose of user-defined conditions is to be able to start or stop
 services, or run/task jobs, on external site-dependent stimuli.
-Example:
 
-    service [2345] <usr/foo> alarm --arg foo -- Foo alarm
+**Example:**
+
+    service alarm {
+        description = "Foo alarm"
+        runlevel    = "2345"
+        conditions  = { "usr/foo" }
+        command     = "alarm --arg foo"
+    }
 
 For convenience, prefixing with `usr/` is allowed, but any other slashes
 or period characters are disallowed.  E.g., to trigger the `Foo alarm`,
@@ -114,8 +167,9 @@ Static (one-shot) conditions, like `usr/`, never enter the `flux` state.
 > "touch" or recreate, their PID file on `SIGHUP`.  This can be done by
 > calling `utimensat()` on the PID file.  Provided, of course, that the
 > service supports reloading on `SIGHUP`, otherwise it will be restarted
-> by Finit when they instead exit on the signal.  For such services, use
-> `<!>` to tell Finit the service does not support `SIGHUP`.
+> by Finit when they instead exit on the signal.  For such services,
+> set `reload-signal = "none"` to tell Finit the service does not
+> support `SIGHUP`.
 
 
 Built-in Conditions
@@ -123,25 +177,35 @@ Built-in Conditions
 
 Finit comes with a set of plugins for conditions:
 
- - `devmon` (built-in)
- - `netlink`
- - `pidfile`
+ - `keventd`: provides `<dev/...>`, `<class/...>`, `<driver/...>`, and
+   `<sys/pwr/...>`
+ - `devmon` (built-in fallback for `<dev/...>` without keventd)
+ - `netlink`: provides `<net/...>`
+ - `pidfile`: provides `<pid/...>`
  - `sys`
  - `usr`
 
-The `devmon` (built-in) plugin monitors `/dev` and `/dev/dir` for device
-nodes being created and removed.  It is active only when a run, task, or
-service has declared a `<dev/foo>` or `<dev/dir/bar>` condition.
+The `dev/` conditions are provided by `keventd`, the built-in device
+manager.  When keventd creates a device node in `/dev`, it also asserts
+the corresponding `dev/` condition.  When a device is removed, the
+condition is cleared.  If keventd is not in use (an external device
+manager like udevd is used instead), the `devmon` built-in provides the
+same conditions by monitoring `/dev` and `/dev/dir` with inotify.
 
-The `pidfile` plugin (recursively) watches `/run/` (recursively) for PID
-files created by the monitored services, and sets a corresponding
-condition in the `pid/` namespace.
+keventd also asserts `class/<subsystem>/<name>` for devices that have
+no `/dev` node, e.g. LEDs and DSA switch ports, and `driver/<name>`
+while a driver is bound to at least one device.  See
+[keventd](keventd.md) for details.
+
+The `pidfile` plugin recursively watches `/run/` for PID files created
+by the monitored services, and sets a corresponding condition in the
+`pid/` namespace.
 
 Similarly, the `netlink` plugin provides basic conditions for when an
 interface is brought up/down and when a default route (gateway) is set,
 in the `net/` namespace.
 
-The `sys` and `usr` plugins monitor are passive condition monitors where
+The `sys` and `usr` plugins are passive condition monitors where
 the action is provided by `keventd`, signal handlers, and in the case of
 `usr`, the end-user via the `initctl` tool.
 
@@ -176,6 +240,8 @@ Built-in conditions:
 - `usr/foo`
 - `boot/arg`
 - `dev/node` and `dev/dir/node`
+- `class/<subsystem>/<name>`
+- `driver/<name>`
 
 > [!NOTE]
 > Here, `up` means administratively up, the interface flag `IFF_UP`.
@@ -187,16 +253,16 @@ Composition
 -----------
 
 The `pid/` conditions are generated by the Finit `pidfile.so` plugin and
-composed from a service's `name:` and `:id`.  By default the basename of
-the daemon and the empty string.
+composed from a service's block title and its `:id`.  By default the
+basename of the daemon and the empty string.
 
-| **service**                                        | **condition**    |
-|----------------------------------------------------|------------------|
-| /sbin/foo                                          | pid/foo          |
-| /sbin/bar -p /run/baz.pid                          | pid/bar          |
-| name:lxc :foo lxc-start -n foo -p /run/lxc/foo.pid | pid/lxc:foo      |
-| /usr/bin/dbus-daemon                               | pid/dbus-daemon  |
-| :222 dropbear -p 222                               | pid/dropbear:222 |
+| **service**                                                       | **condition**    |
+|-------------------------------------------------------------------|------------------|
+| `service { command = "/sbin/foo" }`                                | pid/foo          |
+| `service { command = "/sbin/bar -p /run/baz.pid" }`               | pid/bar          |
+| `service lxc:foo { command = "lxc-start -n foo -p /run/lxc/foo.pid" }` | pid/lxc:foo  |
+| `service { command = "/usr/bin/dbus-daemon" }`                     | pid/dbus-daemon  |
+| `service dropbear:222 { command = "dropbear -p 222" }`             | pid/dropbear:222 |
 
 The condition is asserted when `pidfile.so` receives an inotify event
 for a file matching `/run/*.pid`, `/run/**/*.pid`, or `/run/**/pid`,
@@ -206,9 +272,13 @@ When Finit configuration files are changed and the `initctl reload`
 command is called, it is expected of services to touch their PID files
 for Finit to reassert their conditions.
 
+Similarly, when a single service is reloaded with `initctl reload NAME`,
+its conditions are cleared and reasserted, ensuring dependent services
+are properly updated.
+
 Daemons that don't create PID files, or fail to touch them on reload,
-can be worked around by using the `pid:/path/to/file.pid` syntax in
-the service stanza for the daemon.  It is far from optimal since any
+can be worked around by setting `pidfile` and `pidfile-create` in the
+service block for the daemon.  It is far from optimal since any
 synchronization of depending services may fail due to the daemon not
 having reinitialized/created their IPC sockets, or similar.
 
@@ -277,6 +347,8 @@ A condition is always in one of three states:
 All conditions that have not explicitly been set are interpreted as
 being in the `off` state.
 
+![The service state machine](img/svc-machine.png "The service state machine")
+
 When a reconfiguration is requested, Finit transitions all conditions to
 the `flux` state.  As a result, services that depend on a condition are
 sent `SIGSTOP`.  Once the new state of the condition is asserted, the
@@ -287,6 +359,11 @@ This STOP/CONT handling minimizes the number of unnecessary service
 restarts that would otherwise occur because a depending service was sent
 `SIGHUP` for example.
 
+Services with the `~` prefix are an exception to this rule: when their
+conditions return to `on` after being in `flux`, the reload is propagated
+-- the service is reloaded (SIGHUP), or restarted if it has
+`reload-signal = "none"`, instead of simply being resumed.
+
 Therefore, any plugin that supplies Finit with conditions must ensure
 that their state is updated after each reconfiguration.  This can be
 done by binding to the `HOOK_SVC_RECONF` hook.  For an example of how

doc/config/Makefile.am

@@ -0,0 +1,6 @@
+docsdir        := @docdir@/doc/config
+dist_docs_DATA  = cgroups.md env.md files.md index.md limitations.md	\
+		  logging.md rescue.md runlevels.md runparts.md 	\
+		  service-env.md service-opts.md service-sync.md	\
+		  service-wrappers.md services.md sysv.md		\
+		  task-and-run.md templating.md tty.md

doc/config/README.md

@@ -0,0 +1 @@
+index.md

doc/config/capabilities.md

@@ -0,0 +1,201 @@
+Linux Capabilities
+==================
+
+Finit supports Linux capabilities, allowing services to run with minimal
+required privileges instead of running as root. This significantly improves
+system security by following the principle of least privilege.
+
+## Overview
+
+Linux capabilities divide the traditional root privileges into distinct units
+that can be independently granted to processes. For example, a web server only
+needs the capability to bind to privileged ports (< 1024), not full root access.
+
+Finit uses the modern IAB (Inheritable, Ambient, Bounding) API from libcap,
+which is the same approach used by other modern service managers like dinit.
+
+## Basic Usage
+
+Capabilities are specified with the `capabilities` key, alias `caps`:
+
+```conf
+service nginx {
+    description  = "Web server"
+    runlevel     = "2345"
+    user         = "www-data"
+    group        = "www-data"
+    capabilities = { "^cap_net_bind_service" }
+    command      = "/usr/sbin/nginx -g 'daemon off;'"
+}
+```
+
+This example allows nginx to bind to privileged ports (like 80 and 443) while
+running as the unprivileged `www-data` user.
+
+## IAB Format
+
+The capability string uses the IAB (Inheritable, Ambient, Bounding) format
+with the following prefixes:
+
+- `^` **Ambient** (and Inheritable) - **Recommended for most use cases**
+  - Capabilities survive across `exec()` calls
+  - Automatically raised to effective after exec
+  - Example: `^cap_net_bind_service`
+
+- `%` **Inheritable** only
+  - Requires the executed binary to have matching file capabilities
+  - Less common, more complex setup
+  - Example: `%cap_net_admin`
+
+- `!` **Bounding** - Block capability from bounding set
+  - Prevents the service from ever acquiring this capability
+  - Useful for security hardening
+  - Example: `!cap_sys_admin`
+
+Multiple capabilities can be specified as a comma-separated list:
+
+```conf
+capabilities = { "^cap_net_raw", "^cap_net_admin", "^cap_net_bind_service" }
+```
+
+## Common Use Cases
+
+### Web Server (Privileged Ports)
+
+Allow a web server to bind to ports 80 and 443 without running as root:
+
+```conf
+service webserver {
+    runlevel     = "2345"
+    user         = "www-data"
+    group        = "www-data"
+    capabilities = { "^cap_net_bind_service" }
+    command      = "/usr/sbin/nginx -g 'daemon off;'"
+}
+```
+
+### Network Monitoring (Raw Sockets)
+
+Allow packet capture without root privileges:
+
+```conf
+service tcpdump {
+    runlevel     = "2345"
+    user         = "tcpdump"
+    capabilities = { "^cap_net_raw", "^cap_net_admin" }
+    command      = "/usr/sbin/tcpdump -i eth0 -w /var/log/capture.pcap"
+}
+```
+
+### NTP Daemon (System Time)
+
+Allow time synchronization without full root:
+
+```conf
+service ntpd {
+    runlevel     = "2345"
+    user         = "ntp"
+    capabilities = { "^cap_sys_time", "^cap_sys_nice" }
+    command      = "/usr/sbin/ntpd -n"
+}
+```
+
+## Available Capabilities
+
+Common capabilities include (see `man 7 capabilities` for the complete list):
+
+- `cap_chown` - Make arbitrary changes to file UIDs and GIDs
+- `cap_dac_override` - Bypass file read, write, and execute permission checks
+- `cap_dac_read_search` - Bypass file read permission checks
+- `cap_fowner` - Bypass permission checks on operations that normally require filesystem UID
+- `cap_kill` - Bypass permission checks for sending signals
+- `cap_net_admin` - Perform various network-related operations
+- `cap_net_bind_service` - Bind to privileged ports (< 1024)
+- `cap_net_raw` - Use RAW and PACKET sockets
+- `cap_setgid` - Make arbitrary manipulations of process GIDs
+- `cap_setuid` - Make arbitrary manipulations of process UIDs
+- `cap_sys_admin` - Perform system administration operations (very powerful!)
+- `cap_sys_module` - Load and unload kernel modules
+- `cap_sys_nice` - Raise process nice value and change scheduling
+- `cap_sys_time` - Set system clock
+
+## Security Best Practices
+
+1. **Use the minimum required capabilities**
+   - Only grant what the service actually needs
+   - Don't grant `cap_sys_admin` unless absolutely necessary
+
+2. **Specify a user (preferably non-root)**
+   - The `user` setting is **required** for `capabilities` to take effect
+   - For ambient capabilities (`^`), use a non-root user (not `"root"`)
+   - Example: `user = "www-data"`, `user = "nginx"`, `user = "tcpdump"`
+
+3. **Use ambient capabilities (`^`)**
+   - The `^` prefix ensures capabilities survive exec()
+   - Simpler than setting file capabilities on binaries
+
+4. **Block dangerous capabilities**
+   - Use `!` to explicitly block capabilities you don't want
+   - Example: `!cap_sys_admin,!cap_sys_module`
+
+5. **Test with `getpcaps`**
+   - After starting a service, verify its capabilities:
+     ```bash
+     getpcaps $(pidof nginx)
+     ```
+   - Should show only the capabilities you granted
+
+## Verification
+
+After configuring a service with capabilities, verify it works correctly:
+
+```bash
+# Start the service
+initctl start webserver
+
+# Check the process capabilities
+getpcaps $(pidof nginx)
+
+# Should show something like:
+# 12345: cap_net_bind_service=eip
+
+# Verify the user
+ps -o user,pid,cmd -p $(pidof nginx)
+
+# Should show the service running as the specified user
+```
+
+## Requirements
+
+- Linux kernel 4.3+ (for ambient capabilities support)
+- libcap library installed
+- Finit built with `--enable-libcap`, otherwise a `capabilities` list is
+  ignored, with a warning
+
+## Limitations
+
+- `capabilities` requires `user` to be set for it to take effect
+  - Without `user`, the service runs as root with full capabilities and
+    the `capabilities` list is silently ignored
+  - You can use `user = "root"`, but see below about ambient capabilities
+- For ambient capabilities (`^`, recommended), the user **must be non-root**
+  - Using `user = "root"` with `^` capabilities will not work effectively, as ambient
+    capabilities are only added to the effective set when euid ≠ 0
+  - Use inheritable (`%`) or bounding (`!`) capabilities with `user = "root"` if needed
+  - Finit warns about this when reading the .conf file:
+
+        nginx: ambient capabilities ('^') have no effect as root, use a
+        non-root user, or '%' and '!' entries
+- Services without `capabilities` use standard privilege dropping:
+  - Services with a non-root `user` have no special capabilities
+  - Services without `user` run as root with full capabilities
+- Some very old binaries may not work correctly with ambient capabilities
+- File system capabilities are not managed by Finit (use `setcap` for that)
+
+## See Also
+
+- [capabilities(7)](https://man7.org/linux/man-pages/man7/capabilities.7.html) - Linux capabilities overview
+- [cap_iab(3)](https://man7.org/linux/man-pages/man3/cap_iab.3.html) - IAB capability API documentation
+- [setcap(8)](https://man7.org/linux/man-pages/man8/setcap.8.html) - Set file capabilities
+- [getcap(8)](https://man7.org/linux/man-pages/man8/getcap.8.html) - Query file capabilities
+- [capsh(1)](https://man7.org/linux/man-pages/man1/capsh.1.html) - Capability shell wrapper

doc/config/cgroups.md

@@ -0,0 +1,244 @@
+Finit has two `cgroup` blocks for controlling resource allocation:
+
+ 1. **Top-level definition**, at file scope: declares a group such as
+    `init`, `system`, or `user`, and its default settings.
+
+        cgroup system { cpu.weight = 9700 }
+
+ 2. **Joining a group**, inside a service block: names the group this
+    service runs in, and may override settings for itself alone.
+
+        service foo {
+            cgroup maint { memory.max = 1G }
+            command = "/path/to/cmd"
+        }
+
+> [!NOTE]
+> Linux cgroups and details surrounding values are not explained in the
+> Finit documentation.  The Linux admin-guide covers this well:
+> <https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html>
+
+Top-level Cgroup Definition
+----------------------------
+
+**Syntax:** `cgroup NAME { settings }`
+
+    # Top-level cgroups and their default settings.  All groups mandatory
+    # but more can be added, max 8 groups in total currently.  The cgroup
+    # 'root' is also available, reserved for RT processes.  Settings are
+    # as-is, only one shorthand 'mem.' exists, other than that it's the
+    # cgroup v2 controller default names.
+    cgroup init   { cpu.weight = 100  }
+    cgroup user   { cpu.weight = 100  }
+    cgroup system { cpu.weight = 9800 }
+
+Adding an extra cgroup `maint/` will require you to adjust the weight of
+the above three.  We leave `init/` and `user/` as-is reducing weight of
+`system/` to 9700.
+
+    cgroup system { cpu.weight = 9700 }
+
+    # Example extra cgroup 'maint'
+    cgroup maint  { cpu.weight = 100  }
+
+By default, the `system/` cgroup is selected for almost everything.  The
+`init/` cgroup is reserved for the early boot helpers Finit drives
+itself, like udev and mdev.  PID 1 runs in the root cgroup, since a
+cgroup holding processes cannot delegate controllers to its children.
+The `user/` cgroup is for local TTY logins spawned by getty.
+
+Joining a Cgroup
+----------------
+
+**Syntax:** `cgroup NAME { settings }` (inside a service block)
+
+Every block says which group it joins, by name.  An empty block joins
+without changing anything:
+
+    service foo {
+        cgroup maint {}
+        command = "/path/to/foo args"
+    }
+
+    service bar {
+        cgroup maint {}
+        command = "/path/to/bar args"
+    }
+
+Both services run in the `maint/` cgroup.  Settings inside the block
+apply to that service alone:
+
+    service foo {
+        cgroup maint {
+            cpu.max    = 10000
+            memory.max = 655360
+        }
+        command = "/path/to/foo args"
+    }
+
+> [!NOTE]
+> The legacy format has a standalone `cgroup.NAME` line that selects a
+> group for every stanza following it in the file, and a `cgroup:options`
+> form that applies settings to whichever group is current without
+> naming it.  Neither has an equivalent here, by design: a block that
+> joins a group says so itself, so the group cannot depend on what came
+> earlier in the file.
+
+Every cgroup setting maps directly to cgroup v2 syntax, so `cpu.max`
+maps to the file `/sys/fs/cgroup/maint/foo/cpu.max`.  There is no
+filtering, the one exception being the shorthand `mem.`, which expands
+to `memory.`.  If the file is not available, either the controller is
+missing from your Linux kernel, or the name is misspelled.
+
+### Overriding Cgroup Leaf Names
+
+By default, the cgroup leaf directory name is derived from the service
+configuration filename (without the `.conf` extension). For example, a
+service defined in `system/10-hotplug.conf` would create a cgroup at
+`/sys/fs/cgroup/system/10-hotplug/` by default.
+
+To use a more descriptive name (recommended for clarity), set `name`
+inside the cgroup block:
+
+    service udevd {
+        description = "Device event daemon"
+        cgroup system { name = "udevd" }
+        command     = "/lib/systemd/systemd-udevd"
+    }
+
+This creates the cgroup at `/sys/fs/cgroup/system/udevd/` instead.
+
+`name` combines with any other setting:
+
+    service udevd {
+        description = "Device event daemon"
+        cgroup system {
+            name    = "udevd"
+            cpu.max = 10000
+        }
+        command = "/lib/systemd/systemd-udevd"
+    }
+
+Or with delegation:
+
+    service podman {
+        description = "Podman API"
+        runlevel    = "2345"
+        user        = "podman"
+        group       = "podman"
+        cgroup containers {
+            name       = "podman"
+            delegate   = true
+            memory.max = 4G
+        }
+        command = "/usr/bin/podman system service"
+    }
+
+A daemon using `SCHED_RR` currently needs to run outside the default
+cgroups.
+
+    service rt {
+        description = "Real-Time process"
+        cgroup root {}
+        command     = "/path/to/daemon arg"
+    }
+
+Cgroup Delegation
+-----------------
+
+For services that need to create their own child cgroups (container runtimes
+like Docker, Podman, systemd-nspawn, LXC), set `delegate`:
+
+    service dockerd {
+        description = "Docker daemon"
+        runlevel    = "2345"
+        user        = "dockerd"
+        group       = "dockerd"
+        cgroup system { delegate = true }
+        command     = "/usr/bin/dockerd"
+    }
+
+This allows the container runtime to:
+
+- Create child cgroups for containers
+- Manage controller settings for containers
+- Move processes between cgroups
+
+When delegation is enabled, Finit:
+
+1. Creates the service cgroup as a **domain group** (not a leaf)
+2. Enables all available controllers in `cgroup.subtree_control`
+3. Changes ownership of delegation files to the service user
+4. Moves the service process to the cgroup root
+5. Lets the container runtime manage its own subdirectories
+
+**Requirements:**
+
+- The service should specify `user` and `group` for proper ownership
+- Controllers are delegated from the parent cgroup
+
+**Example with additional config:**
+
+    service podman {
+        description = "Podman API"
+        runlevel    = "2345"
+        user        = "podman"
+        group       = "podman"
+        cgroup containers {
+            delegate   = true
+            memory.max = 4G
+        }
+        command = "/usr/bin/podman system service"
+    }
+
+This delegates the cgroup while also setting a 4GB memory limit.
+
+**Container template example:**
+
+Here's a real-world example from [Infix OS](https://github.com/kernelkit/infix)
+for running rootful podman container instances using delegation:
+
+    sysv container:%i {
+        description   = "container %i"
+        runlevel      = "2345"
+        reload-signal = "none"
+        pidfile       = "/run/container:%i.pid"
+        stop-timeout  = 30
+        log { priority = "local1"  identity = "%i" }
+
+        exec-start-pre         = "/usr/sbin/container"
+        exec-start-pre-timeout = 0
+        exec-cleanup           = "/usr/sbin/container"
+        exec-cleanup-timeout   = 0
+
+        cgroup system { delegate = true }
+        command = "container -n %i"
+    }
+
+This template uses `sysv` type with delegation, demonstrating that cgroup
+delegation works with different service types, not just `service`.
+
+**Cgroup structure with delegation:**
+
+Initially, the service process runs directly in the cgroup root:
+
+    /sys/fs/cgroup/system/container@web/
+    ├── cgroup.procs            (service PID - owned by service user)
+    ├── cgroup.subtree_control  (+cpu +memory +io - owned by service user)
+    └── (container children will be created here)
+
+Once the container runtime creates child cgroups (e.g., `libpod-*/`), cgroups v2
+enforces the "no internal processes" rule. When Finit detects this (`EBUSY` error),
+it automatically creates a `supervisor/` subdirectory and moves service-related
+processes there:
+
+    /sys/fs/cgroup/system/container@web/
+    ├── cgroup.procs            (empty)
+    ├── cgroup.subtree_control  (+cpu +memory +io)
+    ├── supervisor/             (service processes)
+    │   └── cgroup.procs        (conmon PIDs, etc.)
+    └── libpod-$HASH/           (container processes)
+        └── cgroup.procs        (container PIDs)
+
+This happens automatically - no configuration needed. Without delegation, the
+cgroup would be a leaf and the container runtime could not create child cgroups.

doc/config/env.md

@@ -0,0 +1,32 @@
+Environment Variables
+---------------------
+
+In Finit v4.3 support for setting environment variables in `finit.conf`,
+and any `*.conf`, was added.  It is worth noting that these are global
+and *shared with all* services -- the only way to have a service-local
+environment is detailed in [Services Environment](service-env.md).
+
+Global environment variables go in an `environment` block, `env` for
+short:
+
+    environment {
+        foo = "bar"
+        baz = "qux"
+    }
+
+On reload of .conf files, all tracked environment variables are cleared
+so if `foo` is removed from `finit.conf`, or any `finit.d/*.conf`
+file, it will no longer be used by Finit or any new (!) started
+run/tasks or services.  The environment of already started processes can
+not be changed.
+
+The only variables reset to sane defaults on .conf reload are:
+
+    PATH=_PATH_STDPATH
+    SHELL=_PATH_BSHELL
+    LOGNAME=root
+    USER=root
+
+It is entirely possible to override these as well from the .conf files,
+but be careful.  Changing SHELL changes the behavior of `system()` and a
+lot of other commands as well.

doc/config/files.md

@@ -0,0 +1,212 @@
+Files & Layout
+==============
+
+Originally Finit was configured using a single file, `/etc/finit.conf`,
+and although still possible to use a single configuration file, today
+the following layout is recommended:
+
+    /
+    |- etc/
+    |  |- finit.d/
+    |  |   |- available/
+    |  |   |  `- my-service.conf
+    |  :   |- enabled/
+    |  :   |  `- my-service.conf -> ../available/my-service.conf
+    |  :   :
+    |  :   |- static-service.conf
+    |  :   `- another-static.conf
+    |  :
+    |  `- finit.conf
+    |- lib
+    |   `- finit/
+    |       `- system/
+    |           |- 10-hotplug.conf
+    |           `- ...
+    `- run/
+        `- finit/
+            |- bus         # Finit's own D-Bus socket, see doc/dbus.md
+            `- system/
+                |- keventd.conf
+                |- runparts.conf
+                |- watchdogd.conf
+                `- ...
+
+Configuration files in `/etc` are provided by the user, or projects like
+[finit-skel](https://github.com/finit-project/finit-skel) and extended by
+the user.
+
+The files in `/run/finit/system/*.conf` are generated by Finit for its
+built-in services: runparts, [watchdog](../watchdog.md), and
+[`keventd`](../keventd.md), if they are enabled.  They are read before
+the other .conf directories, so any later file can reference them in
+`if:` statements and override them by name.
+
+The files in `/lib/finit/system/*.conf` are system critical services and
+setup provided by Finit, e.g. udev/mdev that must run very early at system
+bootstrap.  This system directory was introduced in Finit v4.4 to replace
+the hard-coded services provided by plugins before.
+
+All .conf files in both directories can be either replaced by a system
+administrator or overridden by a file with the same name in
+`/etc/finit.d/`, which is always read last -- copy a .conf there and
+modify it, or symlink it to `/dev/null` to disable it outright.
+
+Services in the `available/` and `enabled/` sub-directories are called
+dynamic services, in contrast to static services -- the only difference
+being where they are installed and if the `initctl` tool can manage them
+with the `enable` and `disable` commands.  An administrator can always
+create files and symlinks manually.
+
+At bootstrap, and `initctl reload`, all .conf files are read, starting
+with `finit.conf`, then `/run/finit/system/*.conf`,
+`/lib/finit/system/*.conf`, `finit.d/*.conf`, and finally all
+`finit.d/enabled/*.conf` files.  Each directory is a unique group,
+where files within each group are sorted alphabetically.
+
+**Example:**
+
+    /run/finit/system/keventd.conf
+    /run/finit/system/runparts.conf
+    /lib/finit/system/10-hotplug.conf
+    /lib/finit/system/90-testserv.conf
+    /etc/finit.d/10-abc.conf
+    /etc/finit.d/20-abc.conf
+    /etc/finit.d/enabled/1-aaa.conf
+    /etc/finit.d/enabled/1-abc.conf
+
+The resulting combined configuration is read in order, each `run`,
+`task`, and `service` added to an ordered list that ensures they are
+started in the same order.  This is important because of the blocking
+properties of `run`.  For an example on the relation of `service` and
+`run`, and dependency handling between them, see
+[Conditional Loading](services.md#conditional-loading), below.
+
+> [!NOTE]
+> The names `finit.conf` and `finit.d/` are only defaults.  They can be
+> changed at compile-time with two `configure` options:
+> `--with-config=/etc/foo.conf` and `--with-rcsd=/var/foo.d`.
+>
+> They can also be overridden from the [kernel command line](../cmdline.md)
+> using: `-- finit.config=/etc/bar.conf` and in that file use the
+> top-level setting `rcsd = "/path/to/finit.d"`.
+
+Filesystem Layout
+-----------------
+
+Finit is most comfortable with a traditional style Linux filesystem
+layout, as specified in the [FHS][]:
+
+    /.
+     |- bin/
+     |- dev/          # Mounted automatically if devtmpfs is available
+     |   |- pts/      # Mounted automatically by Finit if it exists
+     |   `- shm/      # Mounted automatically by Finit if it exists
+     |- etc/
+     |   |- finit.d/
+     |   |   |- available/
+     |   |   `- enabled/
+     |    `- finit.conf
+     |- home/
+     |- lib/
+     |- libexec/
+     |- mnt/
+     |- proc/         # Mounted automatically by Finit if it exists
+     |- root/
+     |- run/          # Mounted automatically by Finit if it exists
+     |   `- lock/     # Created automatically if Finit mounts /run
+     |- sbin/
+     |- sys/          # Mounted automatically by Finit if it exists
+     |- tmp/          # Mounted automatically by Finit if it exists
+     |- usr/
+     `- var/
+         |- cache/
+         |- db/
+         |- lib/
+         |   `- misc/
+         |- lock/
+         |- log/
+         |- run -> ../run
+         |- spool/
+         `- tmp/
+
+Finit starts by mounting the critical file systems `/dev`, `/proc/`, and
+`/sys`, unless they are already mounted.  When all plugins and other,
+core Finit functions, have been set up, all relevant filesystems (where
+`PASS > 0`) are checked and mounted from the selected `fstab`, either
+the default `/etc/fstab`, or any custom one selected from the command
+line, or at build time.
+
+To provide a smooth ride, file system not listed in the given `fstab`,
+e.g. `/tmp` and `/run`, are automatically mounted by Finit, as listed
+above, provided their respective mount point exists.
+
+With all filesystems mounted, Finit calls `swapon`.
+
+> [!TIP]
+> To see what happens when all filesystems are mounted, have a look at
+> the [`bootmisc.so` plugin](../plugins.md).
+
+At shutdown, and after having stopped all services and other lingering
+processes have been killed, filesystems are unmounted in the reverse
+order, and `swapoff` is called.
+
+[FHS]: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
+
+Managing Services
+-----------------
+
+Using `initctl disable my-service` the symlink (above) is removed and
+the service is queued for removal.  Several changes can be made to the
+system, but it is not until `initctl reload` is called that the changes
+are activated.
+
+To add a new static service, drop a `.conf` file in `/etc/finit.d/` and
+run `initctl reload`.  (It is also possible to `SIGHUP` PID 1, or call
+`finit q`, but that has been deprecated with the `initctl` tool).  Finit
+monitors all known active `.conf` files, so if you want to force a
+restart of any service you can touch its corresponding `.conf` file in
+`/etc/finit.d` and call `initctl reload`.  Finit handles all conditions
+and dependencies between services automatically, see the section on
+[Service Synchronization](service-sync.md) for more details.
+
+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 satisfied, 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](../service.md).
+
+Alternate finit.d/
+------------------
+
+**Syntax:** `rcsd = "/path/to/finit.d"`
+
+The Finit rcS.d directory is set at compile time with:
+
+    ./configure --with-rcsd=/etc/finit.d
+
+A system with multiple use-cases may be bootstrapped with different
+configurations, starting with the kernel command line option:
+
+    -- finit.config=/etc/factory.conf
+
+This file in turn can use the `rcsd` directive to tell Finit to use
+another set of .conf files, e.g.:
+
+    rcsd = "/etc/factory.d"
+
+> [!NOTE]
+> This directive is only available from the top-level bootstrap .conf
+> file, usually `/etc/finit.conf`.
+
+Including Finit Configs
+------------------------
+
+**Syntax:** `include("CONF")`
+
+Include another configuration file.  Absolute path required.

doc/config/index.md

@@ -0,0 +1,116 @@
+This section provides an overview of Finit's configuration system. For
+detailed information on specific topics, see the individual sections in
+the navigation menu.
+
+
+Configuration File Syntax
+--------------------------
+
+A `.conf` file is a series of blocks.  Every setting is a key inside
+one, so nothing has to be remembered by position:
+
+```aconf
+service sysklogd {
+    description = "System log daemon"
+    runlevel    = "S123456789"
+    envfile     = "-/etc/default/sysklogd"
+    command     = "syslogd -F $SYSLOGD_ARGS"
+}
+```
+
+Values are quoted strings, bare words, or integers.  Lists use braces,
+and a block may carry a title, which becomes the service identity:
+
+```aconf
+# 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") # include another file
+```
+
+Bare words work wherever a string is expected, so `memory.max = 65M`
+and `restart = always` need no quotes.
+
+### Two conventions
+
+Keys are kebab-case, never `snake_case` or `CamelCase`: `restart-sec`,
+`stop-timeout`, `reboot-watchdog`.
+
+Keys that take a list are plural: `conditions`, `conflicts`,
+`capabilities`, `modules`, `extra-groups`.  Two imperatives keep their
+singular form because they are verbs rather than nouns: `mknod` and
+`include`.
+
+### Short forms
+
+Nine keys have an alias.  An alias may abbreviate the canonical name,
+or preserve the spelling the line-based format used; it never renames.
+
+| Canonical | Alias | Canonical | Alias |
+|---|---|---|---|
+| `description` | `desc` | `manual-start` | `manual` |
+| `conditions` | `cond` | `remain-after-exit` | `remain` |
+| `capabilities` | `caps` | `stop-signal` | `halt` |
+| `modules` | `mod` | `stop-timeout` | `kill` |
+| `envfile` | `env` | | |
+
+### Optional paths
+
+A leading `-` on a path means carry on if it is not there:
+
+```aconf
+service foo {
+    envfile = "-/etc/default/foo"   # skip the file if missing
+    command = "-/usr/sbin/foo"      # skip the whole block if missing
+}
+```
+
+That is the only mark meaning "optional".  Two others mean something
+else: `!` on `runlevel` inverts the set, e.g. `runlevel = "!12345"`,
+and `~` on a condition propagates a reload from the service it names.
+Both are covered where they apply.
+
+
+Both Formats Are Read
+---------------------
+
+Finit also reads the line-based format it has always used, where a
+stanza is a keyword followed by values whose meaning comes from their
+position:
+
+```aconf
+service [S123456789] env:-/etc/default/sysklogd syslogd -F $SYSLOGD_ARGS -- System log daemon
+```
+
+That format still works and is not going away.  It is frozen at the
+Finit 4.x feature set, so new settings appear only in the block format,
+and the documentation is written in blocks throughout.  To convert a
+file, see the [Syntax Migration Guide](migration.md).
+
+There is no new file extension and no marker line.  Every file is still
+`*.conf`, and Finit decides which format a file is in by reading it: if
+it parses as blocks it is a block file, otherwise it goes to the
+line-based parser.  A file is one format or the other, never a mix.
+
+Because the two are told apart before either parser commits, a typo
+reports its own file and line instead of being mistaken for the other
+format:
+
+```
+parse error: /etc/finit.d/foo.conf:3: no such option 'commnad'
+```
+
+The .conf files `/etc/finit.conf` and `/etc/finit.d/*` support many
+settings.  Some are restricted, e.g., only available at bootstrap,
+runlevel `S`.  Read on in [Files & Layout](files.md) for more on how
+to structure your .conf files.
+
+For details on restrictions, see [Limitations](limitations.md).

doc/config/limitations.md

@@ -0,0 +1,21 @@
+Limitations
+===========
+
+As of Finit v4 there are no limitations to where `.conf` settings can be
+placed.  Except for the system/global `rlimit` and `cgroup` top-level
+group declarations, which can only be set from `/etc/finit.conf`, since
+it is the first `.conf` file Finit reads.
+
+Originally, `/etc/finit.conf` was the only way to set up a Finit system.
+Today it is mainly used for bootstrap settings like system hostname,
+early module loading for watchdogd, network bringup and system shutdown.
+These can now also be set in any `.conf` file in `/etc/finit.d`.
+
+There is, however, nothing preventing you from having all configuration
+settings in `/etc/finit.conf`.
+
+> [!IMPORTANT]
+> The default `rcsd`, i.e., `/etc/finit.d`, was previously the Finit
+> [runparts](runparts.md) directory.  Finit >=v4.0 no longer has a
+> default `runparts` directory, make sure to update your setup, or the
+> finit configuration, accordingly.

doc/config/logging.md

@@ -0,0 +1,82 @@
+General Logging
+===============
+
+**Syntax:** `log { size = 200k  count = 5 }`
+
+Log rotation for run/task/services that redirect output to a log file
+with their own `log` block.  Global setting, applies to all services.
+
+The size can be given as bytes, without a specifier, or in `k`, `M`,
+or `G`, e.g. `size = 10M`, or `size = 3G`.  A value of `size = 0` disables
+log rotation.  The default is `200k`.
+
+The count value is recommended to be between 1-5, with a default 5.
+Setting count to 0 means the logfile will be truncated when the MAX
+size limit is reached.
+
+Redirecting Output
+------------------
+
+The `run`, `task`, and `service` blocks take a `log` block of their own,
+redirecting `stderr` and `stdout` of the application to a file or syslog
+using the native `logit` tool.  This is useful for programs that do not
+support syslog on their own, which is sometimes the case when running
+in the foreground.
+
+An empty block means syslog with the defaults, and three keys adjust it:
+
+| Setting | Description |
+|---|---|
+| `file` | Write to this path instead of syslog |
+| `priority` | Syslog `facility.level`, default `daemon.info` |
+| `identity` | Syslog tag, default the basename of the command |
+
+`/dev/console` and `/dev/null` are spelled as the paths they are:
+
+    service foo { log { }                       command = "foo" }  # syslog
+    service foo { log { file = "/var/log/foo" } command = "foo" }  # a file
+    service foo { log { file = "/dev/console" } command = "foo" }  # console
+    service foo { log { file = "/dev/null" }    command = "foo" }  # discard
+
+> [!NOTE]
+> A `log` block at file scope is a different setting -- that one is the
+> global rotation above, and it takes only `size` and `count`.
+
+Log rotation is controlled using the global `log` setting.
+
+**Example:**
+
+    service ntpd {
+        description = "NTP daemon"
+        log {
+            priority = "user.warn"
+            identity = "ntpd"
+        }
+        command = "/sbin/ntpd pool.ntp.org"
+    }
+
+Output Buffering
+----------------
+
+When using the `log` block, Finit redirects the service's stdout and
+stderr to a pipe connected to a logger process.  Programs detect this as
+non-interactive output (i.e., `isatty()` returns false) and typically
+switch from line-buffered to fully-buffered mode.
+
+Most well-behaved daemons explicitly flush their output or use syslog
+directly, so this is rarely an issue.  However, if a service's log
+messages appear delayed or batched, you can force line-buffered output
+by wrapping the command with `stdbuf`:
+
+    service myservice {
+        description = "My service"
+        log { }
+        command = "/usr/bin/stdbuf -oL /path/to/command"
+    }
+
+The `-oL` option forces line-buffered output, and `-o0` forces unbuffered
+output.  See `stdbuf(1)` for details.
+
+> [!NOTE]
+> Using `stdbuf` is rarely necessary. Only use it if you observe actual
+> buffering issues with a specific service.

doc/config/migration.md

@@ -0,0 +1,267 @@
+Syntax Migration Guide
+======================
+
+Finit reads both configuration formats.  Every file is still `*.conf`,
+and the format is detected per file, so a system can be migrated one
+file at a time -- a file is one format or the other, never a mix.
+
+This guide maps each part of a line-based stanza to its block key.
+
+The shape of the change:
+
+    service [S12345] <pid/syslogd> env:-/etc/default/klogd name:klogd klogd -n $KLOGD_OPTS -- Kernel log daemon
+
+becomes
+
+    service klogd {
+        description = "Kernel log daemon"
+        runlevel    = "S12345"
+        conditions  = { "pid/syslogd" }
+        envfile     = "-/etc/default/klogd"
+        command     = "klogd -n $KLOGD_OPTS"
+    }
+
+The block title is the service identity, shown by `initctl`.  Multiple
+instances spell the ID in the title: `service sshd:1 { ... }`.  The
+legacy bare-ID form, `service :80 ...`, has no equivalent -- the title
+carries both name and ID.
+
+Positional parts
+----------------
+
+| Line-based                       | Block key                                             |
+|----------------------------------|-------------------------------------------------------|
+| `service`, `task`, `run`, `sysv` | same, as block type                                   |
+| `[S12345]`                       | `runlevel = "S12345"`                                 |
+| `<pid/a,net/b>`                  | `conditions = { "pid/a", "net/b" }`                   |
+| `<!pid/a>` on service/sysv       | `conditions = { "pid/a" }` + `reload-signal = "none"` |
+| `<!pid/a>` on run/task           | `conditions = { "pid/a" }` + `required = false`       |
+| `@user:group,extra`              | `user`, `group`, `extra-groups = { "extra" }`         |
+| `name:foo :1`                    | block title `foo:1`                                   |
+| the command and arguments        | `command = "..."`                                     |
+| `-- Description text`            | `description = "..."`                                 |
+
+The `!` was a flag on the stanza, not a negation, and meant different
+things for daemons and one-shots; each meaning is now its own key.  A
+`~` prefix on a condition is unchanged: `conditions = { "~pid/a" }`.
+
+Service options
+---------------
+
+| Line-based                       | Block key                                        |
+|----------------------------------|--------------------------------------------------|
+| `env:[-]/path`                   | `envfile = "[-]/path"`                           |
+| `pid:/path`                      | `pidfile = "/path"` + `pidfile-create = true`    |
+| `pid:!/path`                     | `pidfile = "/path"`                              |
+| `pid`                            | `pidfile = true` + `pidfile-create = true`       |
+| `log`                            | `log { }`                                        |
+| `log:/path`                      | `log { file = "/path" }`                         |
+| `log:null`, `log:console`        | `log { file = "/dev/null" }`, `"/dev/console"`   |
+| `log:prio:p,tag:t`               | `log { priority = "p"  identity = "t" }`         |
+| `notify:systemd`                 | `notify = "systemd"`                             |
+| `type:forking`                   | `type = "forking"`                               |
+| `manual:yes`                     | `manual-start = true`                            |
+| `remain:yes`                     | `remain-after-exit = true`                       |
+| `restart:always` / `restart:NUM` | `restart = "always"` / `restart-max = NUM`       |
+| `restart_sec:SEC`                | `restart-sec = SEC`                              |
+| `norestart`                      | `restart = "never"`                              |
+| `respawn`                        | `respawn = true`                                 |
+| `oncrash:reboot`                 | `oncrash = "reboot"`                             |
+| `halt:SIG`                       | `stop-signal = "SIG"`                            |
+| `kill:SEC`                       | `stop-timeout = SEC`                             |
+| `pre:[TMO,]/script`              | `exec-start-pre`, `exec-start-pre-timeout`       |
+| `ready:[TMO,]/script`            | `exec-start-ready`, and its `-timeout`           |
+| `stop:[TMO,]/script`             | `exec-stop`, and its `-timeout`                  |
+| `post:[TMO,]/script`             | `exec-stop-post`, and its `-timeout`             |
+| `reload:[TMO,]/script`           | `exec-reload`, and its `-timeout`                |
+| `cleanup:[TMO,]/script`          | `exec-cleanup`, and its `-timeout`               |
+| `caps:^cap_a,%cap_b`             | `capabilities = { "^cap_a", "%cap_b" }`          |
+| `conflict:a,b`                   | `conflicts = { "a", "b" }`                       |
+| `if:svc` / `if:<cond>`           | `if = "svc"` / `if = "cond"`, no angle brackets  |
+| `tty:/dev/x`                     | `tty = "/dev/x"`                                 |
+| `nowarn`                         | leading `-` on `command` or `envfile`            |
+| `restarttmo:`                    | dropped, was already an alias for `restart_sec:` |
+
+Repeated stanzas
+----------------
+
+The line-based format has no titles, so the same service could be
+declared more than once and Finit would sort out which line applied.
+A block title *is* the identity, and two blocks sharing one in the
+same file are rejected.  The two shapes that relied on the repetition
+convert differently.
+
+**Several candidate binaries for one service.**  The daemon is known
+under more than one name and the stanzas were repeated once per name,
+each with `nowarn` so the ones that were not installed were skipped:
+
+    service nowarn pid:!/run/udevd.pid [S12345789] /lib/systemd/systemd-udevd -- Device event daemon
+    service nowarn pid:!/run/udevd.pid [S12345789] udevd -- Device event daemon
+
+The candidates now go in one block, and Finit starts the first one it
+finds:
+
+    service udevd {
+        description = "Device event daemon"
+        runlevel    = "S12345789"
+        pidfile     = "/run/udevd.pid"
+        command     = { "/lib/systemd/systemd-udevd", "-udevd" }
+    }
+
+**One service gated differently per platform.**  The command is the
+same every time, only `if:` and the conditions differ, e.g. a syslog
+daemon that has to wait for whichever hotplug daemon the system has:
+
+    service if:udevd nowarn env:-/etc/default/sysklogd <run/udevadm:5/success> \
+           [S0123456789] syslogd -F $SYSLOGD_ARGS -- System log daemon
+    service if:mdev  nowarn env:-/etc/default/sysklogd <run/coldplug/success> \
+           [S0123456789] syslogd -F $SYSLOGD_ARGS -- System log daemon
+
+All of these are one service, `syslogd`, and everything downstream
+waits for the one `pid/syslogd` barrier it provides.  That barrier is
+the reason the repetition existed: the title alone spells it, so
+separate titles would rename it.
+
+Give each variant its own title and name the shared barrier with
+`provides`:
+
+    service syslogd:udev {
+        description = "System log daemon"
+        runlevel    = "S0123456789"
+        if          = "udevd"
+        conditions  = { "run/udevadm:5/success" }
+        provides    = "pid/syslogd"
+        envfile     = "-/etc/default/sysklogd"
+        command     = "-syslogd -F $SYSLOGD_ARGS"
+    }
+    service syslogd:mdev {
+        description = "System log daemon"
+        runlevel    = "S0123456789"
+        if          = "mdev"
+        conditions  = { "run/coldplug/success" }
+        provides    = "pid/syslogd"
+        envfile     = "-/etc/default/sysklogd"
+        command     = "-syslogd -F $SYSLOGD_ARGS"
+    }
+
+Whichever variant `if` qualifies asserts `pid/syslogd` on top of its
+own `pid/syslogd:udev`, so downstream blocks need no change.  The `if`
+statements are meant to be mutually exclusive; if two of them do
+qualify, the second claim is refused with a warning and only the first
+variant supplies the barrier.  See [Provided
+Conditions](service-opts.md#provided-conditions).
+
+`initctl` now knows the variants apart, `initctl status syslogd:udev`,
+and a bare `initctl status syslogd` still lists them all.
+
+Splitting the variants across files also works, since the ban on
+duplicate titles is per file, as does leaving that one file in the
+line-based format.  Neither is needed for this shape any more.
+
+Cgroups
+-------
+
+The standalone `cgroup.NAME` line selected a group for every stanza
+after it in the file, and `cgroup:opts` applied settings to whichever
+group was current.  Neither survives: every block names its own group,
+so nothing depends on what came earlier in the file.
+
+    cgroup.maint
+    service [2345] cgroup:cpu.weight:250 foo -- Foo daemon
+
+becomes
+
+    service foo {
+        description = "Foo daemon"
+        runlevel    = "2345"
+        cgroup maint { cpu.weight = 250 }
+        command     = "foo"
+    }
+
+Top-level group declarations keep their name and settings:
+
+    cgroup system cpu.weight:9700 mem.max:10M
+
+becomes
+
+    cgroup system {
+        cpu.weight = 9700
+        memory.max = 10M
+    }
+
+TTYs
+----
+
+The three positional variants become three key choices:
+
+    tty [12345] /dev/ttyS0 115200 noclear vt220
+    tty [12345] /sbin/getty -L ttyS0 115200 vt100
+    tty [12345] notty
+
+become
+
+    tty ttyS0 {
+        runlevel = "12345"
+        device   = "/dev/ttyS0"
+        baud     = 115200
+        term     = "vt220"
+        noclear  = true
+    }
+    tty getty {
+        runlevel = "12345"
+        command  = "/sbin/getty -L ttyS0 115200 vt100"
+    }
+    tty shell {
+        runlevel = "12345"
+        notty    = true
+    }
+
+The bare flags keep their names as booleans: `noclear`, `nowait`,
+`nologin`, `passenv`, `rescue`, e.g. `passenv` becomes
+`passenv = true`.
+
+A `tty` block is named by the device, not the title, so all three above
+show up as `tty:ttyS0` and the like in `initctl`.  The title still has
+to be unique within the file.
+
+Top-level directives
+--------------------
+
+| Line-based                       | Block key                                                |
+|----------------------------------|----------------------------------------------------------|
+| `host NAME`, `hostname NAME`     | `hostname = "NAME"`                                      |
+| `module foo args` (repeated)     | `modules = { "foo args", ... }`                          |
+| `network script args`            | `network = "script args"`                                |
+| `runlevel N`                     | `runlevel = N`                                           |
+| `rcsd /path`                     | `rcsd = "/path"`                                         |
+| `runparts [progress] [sysv] DIR` | `runparts = "DIR"`, `runparts-progress`, `runparts-sysv` |
+| `set KEY=VAL` (repeated)         | `environment { KEY = "VAL" }`                            |
+| `log size:100k count:4`          | `log { size = 100k  count = 4 }`                         |
+| `rlimit [hard\|soft] RES LIM`    | `rlimit { hard.res = LIM }`                              |
+| `readiness none`                 | `readiness = "none"`                                     |
+| `reboot-delay N`                 | `reboot-delay = N`                                       |
+| `reboot-watchdog on`             | `reboot-watchdog = true`                                 |
+| `service-interval SEC`           | `service-interval = SEC`                                 |
+| `shutdown script`                | `shutdown = "script"`                                    |
+| `mknod /dev/x c 1 2`             | `mknod = { "/dev/x c 1 2" }`                             |
+| `include /path`                  | `include("/path")`                                       |
+
+Worth knowing
+-------------
+
+  * Templates work unchanged: `%i` is replaced before the file is
+    parsed, so `service serv:%i { ... }` in a `serv@.conf` behaves
+    exactly like its legacy counterpart.
+  * A list cannot hold comments; the lexer reads entries after a `#`
+    regardless.  Put commented-out candidates above the list.
+  * `${VAR}` in a value is expanded when the file is read, against
+    Finit's environment, and `${VAR:-default}` works too.  An unset
+    variable expands to nothing.  A plain `$VAR` is left alone and
+    reaches the service, which is what keeps `command = "syslogd -F
+    $SYSLOGD_ARGS"` working with an `envfile`.
+  * New settings only appear in the block format.  The first are the
+    [per-service directories](service-opts.md#service-directories),
+    `runtime-dir` and friends.
+
+For the full description of every key, see the rest of the
+[Configuration](index.md) section.

doc/config/rescue.md

@@ -0,0 +1,69 @@
+Rescue Mode
+===========
+
+Finit supports a rescue mode which is activated by the `rescue` option
+on the kernel command line.  See [cmdline docs](../cmdline.md) for how to
+activate it.
+
+This rescue mode can be disabled at configure time using:
+
+    configure --without-rescue
+
+The rescue mode comes in two flavors; *traditional* and *fallback*.
+
+> [!NOTE]
+> In this mode `initctl` will not work.  Use the `-f` flag to force
+> `reboot`, `shutdown`, or `poweroff`.
+
+Traditional
+-----------
+
+This is what most users expect.  A very early maintenance login prompt,
+served by the system `sulogin` program from util-linux, or BusyBox.  If
+that is not found in `$PATH`, the bundled `/libexec/finit/sulogin`
+program is used instead.  If a successful login is made, or if the user
+exits (Ctrl-D), the rescue mode is ended and the system boots up
+normally.
+
+> [!WARNING]
+> The bundled sulogin in Finit can at configure time be given another
+> user than the default (root).  If the sulogin user does not have a
+> password, or __the account is locked__, the user is presented with a
+> prompt: `"Press enter to enter maintenance mode."`, which will open
+> up a root shell *without prompting for password*!
+
+Fallback
+--------
+
+If no `sulogin` program is found, Finit tries to bring up as much of its
+own functionality as possible, yet limiting many aspects, meaning; no
+network, no `fsck` of file systems in `/etc/fstab`, no `/etc/rc.local`,
+no `runparts`, and most plugins are skipped (except those that provide
+functionality for the condition subsystem).
+
+Instead of reading `/etc/finit.conf` et al, system configuration is read
+from `/lib/finit/rescue.conf`, which can be freely modified by the
+system administrator.
+
+The bundled default `rescue.conf` contains nothing more than:
+
+    runlevel = 1
+    tty rescue {
+        runlevel = "12345"
+        rescue   = true
+    }
+
+The `tty` block has `rescue` set, which works similar to the board
+bring-up setting `notty`.  The major difference being that `sulogin`
+is started to query for root/admin password.  If `sulogin` is not found,
+`rescue` behaves like `notty` and gives a plain root shell prompt.
+
+If Finit cannot find `/lib/finit/rescue.conf` it falls back to a
+built-in equivalent, which runs in every runlevel it can:
+
+    tty rescue {
+        runlevel = "12345789"
+        rescue   = true
+    }
+
+There is no way to exit the *fallback* rescue mode.

doc/config/runlevels.md

@@ -0,0 +1,200 @@
+Runlevels
+=========
+
+Finit supports runlevels, but unlike other init systems runlevels are
+declared per service/run/task/sysv command.  When booting up a system
+Finit pass through three phases:
+
+ 1. Setting up the console, parsing any command line options, and other
+    housekeeping tasks like mounting all filesystems, and calling `fsck`
+ 2. Starting all run/task/services in runlevel S, then waiting for all
+    services to have started, and all run/tasks to have completed
+ 3. Go to runlevel 2, or whatever the user has set in the configuration
+
+Available runlevels:
+
+ - `  S`: bootStrap
+ - `  1`: Single user mode
+ - `2-5`: traditional multi-user mode
+ - `  6`: reboot
+ - `7-9`: multi-user mode (extra)
+ - `  0`: shutdown
+
+Runlevel S (bootStrap), is for tasks supposed to run once at boot, and
+services like `syslogd`, which need to start early and run throughout
+the lifetime of your system.
+
+Example:
+
+    task console-setup {
+        runlevel = "S"
+        command  = "/lib/console-setup/console-setup.sh"
+    }
+
+    service rsyslogd {
+        runlevel = "S12345"
+        envfile  = "-/etc/default/rsyslog"
+        command  = "rsyslogd -n $RSYSLOGD_ARGS"
+    }
+
+When bootstrap has completed, Finit moves to runlevel 2.  This can be
+changed in `/etc/finit.conf` with `runlevel = N`, or by a script running
+in runlevel S that calls, e.g., `initctl runlevel 9`.
+The latter is useful if startup scripts detect problems outside of
+Finit's control, e.g., critical services/devices missing or hardware
+problems.
+
+Each runlevel must be allowed to "complete".  Meaning, all services in
+runlevel S must have started and all run/tasks have been started and
+collected (exited).  Finit waits 120 seconds for all run/tasks in S to
+complete before proceeding to 2.
+
+Finit first stops everything that is not allowed to run in 2, and then
+brings up networking.  Networking is expected to be available in all
+runlevels except: S, 1 (single user level), 6, and 0.  Networking is
+enabled either by `network = "script"`, or if you have an
+`/etc/network/interfaces` file, Finit calls `ifup -a` -- at the very
+least the loopback interface is brought up.
+
+> [!NOTE]
+> When moving from runlevel S to 2, all run/task/services that were
+> constrained to runlevel S only are dropped from bookkeeping.  So when
+> reaching the prompt, `initctl` will not show these run/tasks.  This is
+> a safety mechanism to prevent bootstrap-only tasks from accidentally
+> being run again.  E.g., `console-setup.sh` above.
+
+Runlevel Configuration
+----------------------
+
+**Syntax:** `runlevel = N`
+
+The system runlevel to go to after bootstrap (S) has completed.  `N` is
+the runlevel number 0-9, where 6 is reserved for reboot and 0 for halt.
+Completed in this context means all services have been started and all
+run/tasks have been started and collected.
+
+It is recommended to keep runlevel 1 as single-user mode, because
+Finit disables networking in this mode.
+
+*Default:* 2
+
+> [!NOTE]
+> Only read and executed in runlevel S (bootstrap).
+
+Networking
+----------
+
+**Syntax:** `network = "PATH"`
+
+Script or program to bring up networking, with optional arguments.
+
+Deprecated.  We recommend using dedicated task/run blocks per runlevel,
+or `/etc/network/interfaces` if you have a system with `ifupdown`, like
+Debian, Ubuntu, Linux Mint, or an embedded BusyBox system.
+
+> [!NOTE]
+> Only read and executed in runlevel S (bootstrap).
+
+System Hostname
+---------------
+
+**Syntax:** `hostname = "NAME"`
+
+Set system hostname to NAME, unless `/etc/hostname` exists in which case
+the contents of that file is used.
+
+Deprecated.  We recommend using `/etc/hostname` instead.
+
+> [!NOTE]
+> Only read and executed in runlevel S (bootstrap).
+
+Kernel Modules
+--------------
+
+**Syntax:** `modules = { "MODULE [ARGS]", ... }`, alias `mod`
+
+Load kernel modules, each with optional arguments.  Similar to the
+`insmod` command line tool.
+
+    modules = { "button", "evdev", "softdog" }
+
+> [!NOTE]
+> A list cannot hold comments; the lexer reads the entries after a `#`
+> regardless.  Put commented-out candidates above the list.
+
+Deprecated, there is both a `modules-load.so` and a `modprobe.so` plugin
+that can handle module loading better.  The former supports loading from
+`/etc/modules-load.d/`, the latter uses kernel modinfo to automatically
+load (or coldplug) every required module.  Hotplug module loading is
+handled by [keventd](../keventd.md), the built-in device manager.  On
+systems using the hotplug plugin with BusyBox mdev instead, add to
+`/etc/mdev.conf`:
+
+    $MODALIAS=.*  root:root       0660    @modprobe -b "$MODALIAS"
+
+> [!NOTE]
+> Only read and executed in runlevel S (bootstrap).
+
+Resource Limits
+---------------
+
+**Syntax:** `rlimit { RESOURCE = LIMIT }`, with `soft.` or `hard.` prefix
+
+Set the hard or soft limit for a resource, or both if the prefix is
+omitted.  `RESOURCE` is the lower-case `RLIMIT_` string constants from
+`setrlimit(2)`, without prefix.  E.g. to set `RLIMIT_CPU`, use `cpu`.
+
+LIMIT is an integer that depends on the resource being modified, see
+[setrlimit(2)](https://man7.org/linux/man-pages/man2/setrlimit.2.html),
+or the kernel `/proc/PID/limits` file, for details.  Finit versions
+before v3.1 used `infinity` for `unlimited`, which is still supported,
+albeit deprecated.
+
+    rlimit {
+        hard.as   = 8388608    # no more than 8MB of address space
+        soft.core = unlimited  # core dumps may be arbitrarily large
+        cpu       = 10         # soft & hard = 10 sec
+    }
+
+`rlimit` can be set globally, in `/etc/finit.conf`, or locally per
+each `/etc/finit.d/*.conf` read.  I.e., a set of task/run/service
+blocks can share the same rlimits if they are in the same .conf.
+
+Miscellaneous Settings
+----------------------
+
+**Syntax:** `reboot-delay = 0-60`
+
+Optional delay at reboot (or shutdown or halt) to allow kernel
+filesystem threads to complete after calling `sync(2)` before
+rebooting.  This applies primarily to filesystems that do not
+have a reboot notifier implemented.  At the point of writing,
+the only known filesystems affected are: ubifs, jffs2.
+
+*Default:* 0 (disabled)
+
+When enabled (non-zero), this delay runs after file systems have been
+unmounted and the root filesystem has been remounted read-only, and
+sync(2) has been called, twice.
+
+> "On Linux, sync is only guaranteed to schedule the dirty blocks for
+> writing; it can actually take a short time before all the blocks are
+> finally written.
+
+**Syntax:** `reboot-watchdog = true|false`
+
+Controls whether the system should reboot via the watchdog timer (WDT)
+or directly via the SoC/kernel.  When enabled, Finit will:
+
+ 1. Send `SIGPWR` to the registered watchdog daemon before shutdown
+ 2. Send `SIGTERM` to the watchdog daemon and wait up to 10 seconds
+    for the watchdog to trigger a hardware reset
+
+When disabled (default), Finit skips the watchdog reboot logic and
+calls the kernel's `reboot(2)` syscall directly for a clean SoC reboot.
+
+*Default:* off (reboot via SoC)
+
+> [!NOTE]
+> This setting only affects reboots.  The watchdog daemon will still
+> run and monitor the system during normal operation.

doc/config/runparts.md

@@ -0,0 +1,52 @@
+Run-parts Scripts
+-----------------
+
+**Syntax:** `runparts = "DIR"`
+
+Call [run-parts(8)][] on `DIR` to run start scripts.  All executable
+files in the directory are called, in alphabetic order.  The scripts in
+this directory are executed at the very end of runlevel `S`.
+
+A common use-case for runparts scripts is to create and enable/disable
+services, which Finit will then apply when changing runlevel from S to
+whatever the next runlevel is set to be (default 2).  E.g., generate a
+`/etc/chrony.conf` and call `initctl enable chronyd`.
+
+**Options:**
+
+ - `runparts-progress = true`: display the progress of each script being
+   executed
+ - `runparts-sysv = true`: run only SysV style scripts, i.e., `SNNfoo`,
+   or `KNNbar`, where `NN` is a number (0-99).
+
+If global debug mode is enabled, the `runparts` program is also called
+with the debug flag.
+
+**Limitations:**
+
+Scripts called from `runparts`, or hook scripts (see below), are limited
+in their interaction with Finit.  Like a standalone `run` block and
+the `/etc/rc.local` shell script, Finit waits for their completion
+before continuing.  None of them can issue commands to start, stop, or
+restart other services.  Also, ensure all your services and programs
+either terminate or start in the background or you will block Finit.
+
+> [!NOTE]
+> `runparts` scripts are only read and executed in runlevel S.  See
+> [hook scripts](../plugins.md#hooks) for other ways to run scripts at
+> certain points during the complete lifetime of the system.
+
+**Recommendations:**
+
+It can be beneficial to use `01-name`, `02-othername`, etc., to ensure
+the scripts are started in that order, e.g., if there is a dependency
+order between scripts.  Symlinks to existing daemons can also be used,
+but make sure they daemonize (background) themselves properly, otherwise
+Finit will lock up.
+
+If `S[0-9]foo` and `K[0-9]bar` style naming is used, the executable will
+be called with an extra argument, `start` and `stop`, respectively.
+E.g., `S01foo` will be called as `S01foo start`.  Of course, `S01foo`
+and `K01foo` may be a symlink to `another/directory/foo`.
+
+[run-parts(8)]: http://manpages.debian.org/cgi-bin/man.cgi?query=run-parts

doc/config/service-env.md

@@ -0,0 +1,34 @@
+Service Environment
+-------------------
+
+Finit supports sourcing environment variables from `/etc/default/*`, or
+similar `--with-sysconfig=DIR`.  This is a common pattern from SysV init
+scripts, where the start-stop script is a generic script for the given
+service, `foo`, and the options for the service are sourced from the
+file `/etc/default/foo`.  Like this:
+
+* `/etc/default/foo`:
+
+        FOO_OPTIONS=--extra-arg="bar" -s -x
+
+* `/etc/finit.conf`:
+
+        service foo {
+            description = "Example foo daemon"
+            runlevel    = "2345"
+            envfile     = "-/etc/default/foo"
+            command     = "foo -n $FOO_OPTIONS"
+        }
+
+Here the service `foo` is started with `-n`, to make sure it runs in the
+foreground, and the with the options found in the environment file.  With
+the `ps` command we can see that the process is started with:
+
+    foo -n --extra-arg=bar -s -x
+
+> [!NOTE]
+> The leading `-` on `envfile` determines if Finit should treat a
+> missing environment file as blocking the start of the service or not.
+> When `-` is used, a missing environment file does *not* block the
+> start.  The same mark works on `command`, where it means carry on if
+> the binary is missing.

doc/config/service-opts.md

@@ -0,0 +1,331 @@
+Service Options
+===============
+
+The `run`, `task`, `tty`, `service` and `sysv` blocks take settings as
+keys.  This section lists them with their limitations.
+
+The name of a service, shown by the `initctl` tool, is the block title.
+It defaults to the basename of the executable if the title is omitted:
+
+    service sshd {
+        command = "/usr/sbin/sshd -D"
+    }
+
+For multiple instances of a service, with the same name, add an
+identifier after a colon to prevent Finit from replacing previous
+instances:
+
+    service ssdp:eth1 { command = "ssdpd eth1" }
+    service ssdp:eth2 { command = "ssdpd eth2" }
+
+The [`initctl`](../initctl.md) tool will list these two services as:
+
+ - ssdp:eth1
+ - ssdp:eth2
+
+Conflicting services that must be prevented from starting, use the
+`conflicts` key:
+
+    service udevd { command = "udevd" }
+    run mdev {
+        runlevel  = "S"
+        conflicts = { "udevd" }
+        command   = "mdev -s"
+    }
+
+The list may name several, and an instance is named the same way it is
+declared:
+
+    service abc:1 { command = "abc 1" }
+    service abc:2 { command = "abc 2" }
+    service cde   { conflicts = { "abc:1", "abc:2" }  command = "cde" }
+
+If a service should not be automatically started, set `manual-start`.
+It can then be started at any time with `initctl start <service>`:
+
+    service lldpd {
+        manual-start = true
+        command      = "/usr/sbin/lldpd -d"
+    }
+
+Other run/task/service settings are:
+
+  * `capabilities` -- see the [Linux Capabilities](capabilities.md) section
+  * `cgroup NAME {}` -- see the [Cgroups](cgroups.md) section
+  * `envfile` -- see the [Service Environment](service-env.md) section
+  * `log {}` -- see [Redirecting Output](logging.md#redirecting-output)
+  * `tty` -- see [Controlling TTY](tty.md#controlling-tty-for-services)
+  * `notify` -- see [Service Synchronization](service-sync.md)
+  * `if` -- see [Conditional Execution](services.md#conditional-execution)
+  * `type = "forking"` -- see description of the [service](services.md) block
+  * a leading `-` on `command` -- see
+    [Conditional Loading](services.md#conditional-loading)
+
+Command Candidates
+------------------
+
+The `command` setting may list several candidates for the same
+service, in which case Finit starts the first one it finds:
+
+    service udevd {
+        command = { "/lib/systemd/systemd-udevd", "-udevd" }
+    }
+
+A candidate that is not installed is skipped without a warning, that
+is the point of listing more than one.  The leading `-` is read from
+the candidate that wins, or from the last one when none are found, so
+a block with a single command behaves as it always has.
+
+The candidates are alternative spellings of one service, not a
+fallback for a service that fails to start.  Finit chooses when the
+.conf file is read and does not revisit the choice.
+
+A [`tty`](tty.md) block takes the same list, where the candidates are
+the getty to run:
+
+    tty ttyAMA0 {
+        command = { "/sbin/agetty -L ttyAMA0 115200 vt100",
+                    "/sbin/getty -L 115200 /dev/ttyAMA0 vt100" }
+    }
+
+Provided Conditions
+-------------------
+
+A service always asserts `pid/<ident>` for itself, named after the
+block title.  `provides` names conditions it asserts in addition to
+that one:
+
+    service syslogd:udev {
+        if       = "udevd"
+        provides = "pid/syslogd"
+        command  = "syslogd -F"
+    }
+
+This is what lets variants of one service, picked apart by
+[`if`](services.md#conditional-execution), share the barrier that
+everything downstream waits for.  Each variant has its own title, so
+each is its own service to `initctl`, while the condition they publish
+stays the same.
+
+Any namespace works, `pid/`, `usr/`, `service/`, since the point is
+publishing a name existing configuration already waits on.  A value
+without a namespace separator is not a condition and is rejected.  The
+list holds at most four.
+
+A provided condition is asserted and cleared with the service, exactly
+like its own, so stopping the provider clears the barrier.
+
+Two services cannot supply the same condition.  The second claim is
+refused, with the owner named:
+
+    finit.conf: second: provides condition <usr/barrier> already registered by service first, ignoring
+
+The service itself still registers and runs, only the claim is
+dropped.  Which one is "first" is .conf load order, so it follows the
+file names, see [Files & Layout](files.md).
+
+A real identity outranks a claim on it.  `provides = "pid/sshd"` in a
+system that also runs a service titled `sshd` loses to that service,
+because `pid/<ident>` is how Finit tracks the service itself.
+
+`initctl cond dump` names the owner of every condition, which for a
+provided one is the service that claimed it:
+
+    $ initctl cond dump
+    PID    IDENT         STATUS  CONDITION
+    1234   syslogd:udev  on      <pid/syslogd>
+    1234   syslogd:udev  on      <pid/syslogd:udev>
+
+Duplicate Titles
+----------------
+
+The title is the service identity, so two blocks sharing a title in
+one file are two declarations of one service.  The parser underneath
+merges them without a word, leaving a single service holding a mix of
+both, so Finit rejects the file and names the title:
+
+    /etc/finit.d/hotplug.conf:12: found duplicate title 'udevd'
+
+Nothing from a rejected file is loaded and the rest of the
+configuration is unaffected.
+
+The same title in *another* file is fine.  That is how a system .conf
+is overridden, the later file wins, see [Files & Layout](files.md).
+
+Two shapes need a single identity and used to be written as repeated
+declarations.  One is a service with several candidate binaries, which
+is now a [command list](#command-candidates).  The other is a service
+gated differently per platform, e.g. a syslog daemon waiting for
+whichever hotplug daemon the system happens to have.  For that one,
+give each variant its own file, or keep them as one-liners in the
+line-based format, which has no titles.  The [migration
+guide](migration.md) works through it.
+
+Restarting
+----------
+
+Services are automatically started, restarted, and stopped, depending
+on the configuration and conditions.  Within the confines of that the
+following settings are available:
+
+  * `restart-max = NUM` -- number of times Finit tries to restart a
+    crashing service, default: 10.  When this limit is reached the
+    service is marked *crashed* and must be restarted manually with
+    `initctl restart NAME`
+  * `restart-sec = SEC` -- number of seconds before Finit tries to
+    restart a crashing service.  The default is 2 seconds for the first
+    half of `restart-max` attempts, then a back-off to 5 seconds -- with
+    the default `restart-max` that is the first five retries.  The
+    greater of this configured value and the back-off is used
+  * `restart = "always"` -- no upper limit on the number of times Finit
+    tries to restart a crashing service
+  * `restart = "never"` -- do not restart on failures.  `false` is
+    accepted as a synonym, and `true` selects the default policy
+  * `respawn = true` -- bypasses the `restart` mechanism completely,
+    allowing endless restarts.  Exiting is treated as normal work
+    rather than failure, so the service is restarted at once instead of
+    being counted and delayed.  This is how a `tty` behaves; it is not
+    what `service` was designed for, so it is not the default
+  * `remain-after-exit = true` -- for `run` and `task` only.  Prevents
+    the task from re-running on runlevel re-entry and ensures the
+    `exec-stop-post` script runs when the task is explicitly stopped or
+    leaves its valid runlevels.  This is systemd's `RemainAfterExit=`.
+    See [Task and Run](task-and-run.md) for more details
+  * `oncrash = "reboot"` -- when all retries have failed, and the
+    service has *crashed*, the system is rebooted
+  * `oncrash = "script"` -- similarly, but instead of rebooting, call
+    the `exec-stop-post` script with exit code `crashed`, see below
+
+Service directories
+-------------------
+
+Five settings ask Finit to create a directory for the service before it
+starts, owned by its `user` and `group`, mode 0755.  The value is a
+directory name, resolved under a fixed base -- absolute paths and `..`
+are refused:
+
+| Setting | Base | Environment variable |
+|---|---|---|
+| `runtime-dir` | `/run` | `RUNTIME_DIRECTORY` |
+| `state-dir` | `/var/lib` | `STATE_DIRECTORY` |
+| `cache-dir` | `/var/cache` | `CACHE_DIRECTORY` |
+| `logs-dir` | `/var/log` | `LOGS_DIRECTORY` |
+| `config-dir` | `/etc` | `CONFIGURATION_DIRECTORY` |
+
+Each resolved path is exported to the process environment under the
+listed name, the same names systemd uses for `RuntimeDirectory=` and
+friends.  As in systemd, `config-dir` is the odd one out: it is created
+but never chowned.
+
+Each takes a matching `-mode`, e.g. `runtime-dir-mode = 0700`, default
+0755.  Modes are octal, with the leading zero.
+
+The mode of the named directory is locked down again on every start.
+Its contents are left alone as long as the owner is right; if the owner
+has drifted, everything under it is chowned back.
+
+The runtime directory is removed again when the service stops, after
+any `exec-stop-post` script has run; `/run` is a tmpfs so it would not
+survive a reboot anyway.  The other four persist.  A completed `run` or
+`task` counts as stopped, unless `remain-after-exit` keeps it alive
+until stopped for real.  `runtime-dir-preserve` adjusts this, same
+values as systemd's `RuntimeDirectoryPreserve=`:
+
+  * `"no"` -- removed when the service stops, the default
+  * `"restart"` -- kept across restarts, removed on a real stop
+  * `"yes"` -- never removed
+
+This is what lets a service drop privileges and still create, and
+later touch, its own PID file:
+
+    service ntpd {
+        user        = "ntp"
+        group       = "ntp"
+        runtime-dir = "ntpd"
+        pidfile     = "/run/ntpd/ntpd.pid"
+        command     = "/usr/sbin/ntpd -n -p /run/ntpd/ntpd.pid"
+    }
+
+These settings exist only in the block format.
+
+Stopping and reloading
+----------------------
+
+When stopping a service, either manually or when moving to another
+runlevel, Finit starts by sending `SIGTERM` to let the process shut
+down gracefully.  If it has not been collected within 3 seconds,
+`SIGKILL` follows.  Both ends of that are configurable:
+
+  * `stop-signal = "SIGPWR"` -- send this instead of `SIGTERM`
+  * `stop-timeout = 10` -- seconds to wait before `SIGKILL`, 1-300
+
+Some services need more than a signal:
+
+  * `exec-stop = "script [args]"` -- run instead of sending the stop
+    signal, and instead of `stop` for `sysv`
+  * `exec-reload = "script [args]"` -- run instead of sending `SIGHUP`.
+    Like systemd, Finit sets `$MAINPID` as a convenience to scripts,
+    which in effect also allows `exec-reload = "kill -HUP $MAINPID"`
+
+If a daemon cannot be reloaded with a signal at all, say so and Finit
+restarts it instead:
+
+    service dropbear {
+        reload-signal = "none"
+        command       = "/usr/sbin/dropbear -R -F"
+    }
+
+`SIGHUP` is the default and the only other accepted value, with or
+without the `SIG` prefix and in any case.
+
+Scripts
+-------
+
+Services, including the `sysv` variant, support six lifecycle scripts:
+
+  * `exec-start-pre` -- called before the sysv/service is started
+  * `exec-start-ready` -- called when the sysv/service is ready
+  * `exec-stop` -- called instead of the stop signal
+  * `exec-stop-post` -- called after the sysv/service has stopped
+  * `exec-reload` -- called instead of `SIGHUP`
+  * `exec-cleanup` -- called when run/task/sysv/service is removed
+
+Each takes a matching `-timeout`, in seconds, 0-3600, after which Finit
+kills the script.  It defaults to the `stop-timeout` value and can be
+disabled by setting it to zero:
+
+    service foo {
+        exec-start-pre         = "/etc/foo/pre.sh"
+        exec-start-pre-timeout = 10
+        command                = "/usr/sbin/foo"
+    }
+
+These scripts run as the same user and group as the service itself,
+with any `envfile` sourced.  They are executed from the `$HOME` of the
+given user.  The scripts are not called with any argument, but get a
+set of environment variables:
+
+  * `SERVICE_IDENT=foo:1`
+  * `SERVICE_NAME=foo`
+  * `SERVICE_ID=1`
+
+The `exec-stop-post` script is called with an additional set of
+environment variables.  Yes, the text is correct, the naming was an
+accident:
+
+ - `EXIT_CODE=[exited,signal,crashed]`: normal exit, signaled, or
+   crashed
+ - `EXIT_STATUS=[num,SIGNAME]`: set to one of exit status code from
+   the program, if it exited normally, or the signal name (`HUP`,
+   `TERM`, etc.) if it exited due to signal
+
+When a run/task/sysv/service is removed (disable + reload) it is first
+stopped and then removed from the runlevel.  The `exec-stop-post`
+script always runs when the process has stopped, and `exec-cleanup`
+runs when the block has been removed from the runlevel.
+
+> [!IMPORTANT]
+> These script actions are intended for setup, cleanup, and readiness
+> notification.  A script that outlives its timeout is killed, so pick
+> one that suits the work, or set it to zero to opt out and take
+> responsibility for the script terminating.

doc/config/service-sync.md

@@ -0,0 +1,81 @@
+Service Synchronization
+=======================
+
+Finit was created for fast booting systems.  Faster than a regular SysV
+Init based system at the time.  Early on the need for a guaranteed start
+order of services (daemons) arose.  I.e., service `A` must be guaranteed
+to have started (and be ready!) before `B`.  The model that was chosen
+to determine this was very simple: PID files.
+
+Early on in UNIX daemons were controlled with basic IPC like signals,
+and the way for a user to know that a daemon was ready to respond to
+signals (minimally having set up its signal handler), was to tell the
+user;
+
+> "Hey, you can send signals to me using the PID in this file:
+> `/var/run/daemon.pid`".
+
+Since most systems run fairly unchanged after boot, Finit could rely on
+the PID file for `A` being created before launching `B`.  This method
+has worked well for a long time, and for systems based on Open Source it
+was easy to either add PID file support to a daemon without support for
+it, or fix ordering issues (PID file created before signal handler is
+set up) in existing daemons.
+
+However, with the advent of other Init systems (Finit is rather old),
+most notably systemd and s6, other methods for signaling "readiness"
+arrived and daemons were adapted to these new schemes to a larger
+extent.
+
+As of Finit v4.4 partial support for systemd and s6 style readiness
+notification is available, and the native PID file mode of operation is,
+as of Finit v4.6 optional, by default it is still enabled, but this can
+be changed in `finit.conf`:
+
+    readiness = "none"
+
+This will be made the default in Finit 5.0.  In this mode of operation,
+every service needs to explicitly declare their readiness notification,
+like this:
+
+    service watchdogd { notify = "pid"      command = "watchdogd" }
+    service foo       { notify = "systemd"  command = "foo"       }
+    service bar       { notify = "s6"       command = "bar"       }
+    service qux       { notify = "none"     command = "qux"       }
+
+The `notify = "none"` setting is for completeness in systems which run
+in `readiness = "pid"` mode (default).  Services declared with
+`notify = "none"` will transition to ready as soon as Finit has started
+them, e.g., `service/qux/ready`.
+
+To synchronize two services the following condition can be used:
+
+    service watchdogd {
+        notify  = "pid"
+        command = "watchdogd"
+    }
+
+    service stress-ng {
+        conditions = { "service/watchdogd/ready" }
+        command    = "stress-ng --cpu 8"
+    }
+
+For the full list of conditions, see [Finit Conditions](../conditions.md).
+
+> [!NOTE]
+> On `initctl reload` conditions are set in "flux", while figuring out
+> which services to stop, start or restart.  Services that need to be
+> restarted have their `ready` condition removed before Finit issue a
+> SIGHUP (if they support that), or stop-starting them.  A daemon is
+> expected to reassert its readiness, e.g. systemd style daemons to
+> write `READY=1\n`.
+>
+> However, the s6 notify mode does not support this because in s6 you
+> are expected to close your notify descriptor after having written
+> `\n`.  This means s6 style daemons currently must be stop-started.
+> (Declare the service with `reload-signal = "none"`.)
+>
+> For default, PID file style readiness notification, daemons are
+> expected to either create their PID files, or touch it using
+> `utimensat()` to reassert readiness.  Triggering both the `<pid/>`
+> and `<.../ready>` conditions.

doc/config/service-wrappers.md

@@ -0,0 +1,36 @@
+Service Wrapper Scripts
+=======================
+
+If your service requires to run additional commands, executed before the
+service is actually started, like the systemd `ExecStartPre`, you can
+use a wrapper shell script to start your service.
+
+The Finit service `.conf` file can be put into `/etc/finit.d/available`,
+so you can control the service using `initctl`.  Then use the path to
+the wrapper script in the Finit `.conf` service block.  The following
+example employs a wrapper script in `/etc/start.d`.
+
+**Example:**
+
+* `/etc/finit.d/available/program.conf`:
+
+        service program {
+            description   = "Example Program"
+            runlevel      = "235"
+            reload-signal = "none"
+            command       = "/etc/start.d/program"
+        }
+
+* `/etc/start.d/program:`
+
+        #!/bin/sh
+        # Prepare the command line options
+        OPTIONS="-u $(cat /etc/username)"
+
+        # Execute the program
+        exec /usr/bin/program $OPTIONS
+
+> [!NOTE]
+> The example sets `reload-signal = "none"` to say the program does not
+> support `SIGHUP`.  Finit then stop/starts the service instead of
+> signalling it at restart/reload events.

doc/config/services.md

@@ -0,0 +1,356 @@
+Services
+========
+
+**Syntax:** `service NAME { command = "/path/to/daemon ARGS" }`
+
+Service, or daemon, to be monitored and automatically restarted if it
+exits prematurely.  Finit tries to restart services that die, by default
+10 times before giving up and marking them as *crashed*.  After which
+they have to be manually restarted with `initctl restart NAME`.  The
+limits controlling this are configurable, see
+[Service Options](service-opts.md).
+
+> [!TIP]
+> To allow endless restarts, see [`respawn`](service-opts.md#restarting)
+  
+For daemons that support it, we recommend appending `--foreground`,
+`--no-background`, `-n`, `-F`, or similar command line argument to
+prevent them from forking off a sub-process in the background.  This is
+the most reliable way to monitor a service.
+
+However, not all daemons support running in the foreground, or they may
+start logging to the foreground as well, these are forking daemons and
+are supported using the same syntax as forking `sysv` services, by
+naming the file to watch with `pidfile`.  There is an alternative that
+may be more intuitive, where Finit can also guess the PID file based on
+the daemon's command name:
+
+    service ntpd {
+        description = "NTP daemon"
+        type        = "forking"
+        command     = "ntpd"
+    }
+
+This example lets BusyBox `ntpd` daemonize itself.  Finit uses the
+basename of the binary to guess the PID file to watch for the PID:
+`/var/run/ntpd.pid`.  If Finit guesses wrong, name the file yourself
+with `pidfile = "/path/to/file.pid"`.
+
+The file belongs to the service: Finit reads it but does not create or
+remove it.  That is the default, and `pidfile-create = true` is what
+asks Finit to write the file instead.  The one exception is *stale*
+cleanup — if the service dies without removing its own pidfile
+(SIGKILL, OOM, segfault), and the file still names the just-reaped
+PID, Finit removes it before the next retry.  This prevents daemons
+that refuse to start on an existing pidfile (e.g. `dbus-daemon`)
+from getting stuck in a crash-restart loop.
+
+**Example:**
+
+In the case of `ospfd` (below), we omit the `-d` flag (daemonize) to
+prevent it from forking to the background:
+
+    service ospfd {
+        description = "OSPF daemon"
+        runlevel    = "2345"
+        conditions  = { "pid/zebra" }
+        command     = "/sbin/ospfd"
+    }
+
+`runlevel` denotes the runlevels `ospfd` is allowed to run in, it is
+optional and defaults to level 2-4 if omitted.
+
+`conditions` lists what must be asserted before starting `ospfd`.  In
+this example Finit waits for another service, `zebra`, to have created
+its PID file in `/var/run/quagga/zebra.pid`.  Finit watches *all* files
+in `/var/run`, for each file named `*.pid`, or `*/pid`, Finit opens it
+and finds the matching `NAME:ID` using the PID.
+
+A condition may be prefixed with `~` to propagate a reload of the
+upstream service to this one, rather than merely pausing and resuming
+it:
+
+    conditions = { "~pid/zebra" }
+
+If `ospfd` cannot be reloaded with `SIGHUP` at all, that is a property
+of `ospfd` and not of the condition, so it is said directly:
+
+    reload-signal = "none"
+
+The legacy format spells that second one as a `!` leading the condition
+list, which is not accepted here.  For details, see the
+[Finit Conditions](../conditions.md) document.
+
+Some services do not maintain a PID file and rather than patching each
+application Finit provides a workaround.  With `pidfile-create` Finit
+creates the file when starting and removes it when stopping.  The path
+comes from `pidfile`, which takes three forms:
+
+    pidfile = true              # /var/run/<command basename>.pid
+    pidfile = "bar"             # a bare name, /var/run/bar.pid
+    pidfile = "/run/bar.pid"    # an explicit path
+
+Such a file is also used by the Finit condition subsystem, so another
+service, run or task can depend on `pid/bar`.  Here foo is not started
+until bar has:
+
+    service bar {
+        description    = "Bar Service"
+        pidfile        = "/run/bar.pid"
+        pidfile-create = true
+        command        = "bar"
+    }
+
+    service foo {
+        description = "Foo Service"
+        conditions  = { "pid/bar" }
+        command     = "foo"
+    }
+
+Needless to say, it is better if `bar` creates its own PID file when it
+has completed starting up and is ready for service.
+
+As an alternative "readiness" notification, Finit supports both systemd
+and s6 style notification.  This is enabled with the `notify` key:
+
+  * `notify = "systemd"` -- tells Finit the service uses the `sd_notify()`
+    API to signal PID 1 when it has completed its startup and is ready
+    to service events.  The [sd_notify()][] API expects `NOTIFY_SOCKET`
+    to be set to the socket where the application can send `"READY=1\n"`
+    when it is starting up or has processed a `SIGHUP`.
+  * `notify = "s6"` -- puts Finit in s6 compatibility mode.  Compared to the
+    systemd notification, [s6 expect][] compliant daemons to send `"\n"`
+    and then close their socket.  Finit takes care of "hard-wiring" the
+    READY state as long as the application is running, events across any
+    `SIGHUP`.  Since s6 can give its applications the descriptor number
+    (must be >3) on then command line, Finit provides the following
+    syntax (`%n` is replaced by Finit with then descriptor number):
+
+        service mdevd {
+            runlevel = "S12345789"
+            notify   = "s6"
+            command  = "mdevd -O 4 -D %n"
+        }
+
+[sd_notify()]: https://www.freedesktop.org/software/systemd/man/sd_notify.html
+[s6 expect]:   https://skarnet.org/software/s6/notifywhenup.html
+
+When a service is ready, either by Finit detecting its PID file, or
+their respective readiness mechanism has been triggered, Finit creates
+then service's ready condition which other services can depend on:
+
+    $ initctl -v cond get service/mdevd/ready
+    on
+
+This can be used to synchronize the start of another run/task/service:
+
+    task mdevd-coldplug {
+        runlevel   = "S"
+        conditions = { "service/mdevd/ready" }
+        user       = "root"
+        group      = "root"
+        command    = "mdevd-coldplug"
+    }
+
+Finit waits for `mdevd` to notify it, before starting `mdevd-coldplug`.
+Notice how both start in runlevel S, and the coldplug task only runs in
+S.  When the system moves to runlevel 2 (the default), coldplug is no
+longer part of the running configuration (`initctl show`), this is to
+ensure that coldplug is not called more than once.
+
+>  For a detailed description of conditions, and how to debug them,
+>  see the [Finit Conditions](../conditions.md) document.
+
+
+Non-privileged Services
+-----------------------
+
+Every `run`, `task`, or `service` can also list the privileges the
+command should be executed with, using `user`, `group` and
+`extra-groups`, all optional:
+
+    run hello {
+        runlevel = "2345"
+        user     = "joe"
+        group    = "users"
+        command  = "logger \"Hello world\""
+    }
+
+Finit reads the user's supplementary group membership from `/etc/group`
+automatically.  Any groups the user belongs to will be inherited by
+the service.
+
+To specify additional supplementary groups beyond those in
+`/etc/group`, list them in `extra-groups`:
+
+    service caddy {
+        user         = "caddy"
+        group        = "caddy"
+        extra-groups = { "ssl-cert" }
+        command      = "/usr/bin/caddy run"
+    }
+
+This runs the `caddy` service as user `caddy`, with primary group
+`caddy`, inheriting any groups `caddy` is a member of in `/etc/group`,
+plus the additional `ssl-cert` group.  This is useful when a service
+needs access to resources owned by groups not listed in `/etc/group`.
+
+For multiple instances of the same command, e.g. a DHCP client or
+multiple web servers, add `:ID` to the block title, like this:
+
+    service httpd:80 {
+        description = "Web server"
+        runlevel    = "2345"
+        command     = "httpd -f -h /http -p 80"
+    }
+
+    service httpd:8080 {
+        description = "Old web server"
+        runlevel    = "2345"
+        command     = "httpd -f -h /http -p 8080"
+    }
+
+Without the `:ID` the latter will overwrite the former and only the old
+web server would be started and supervised.
+
+> [!NOTE]
+> The line-based format also accepts a bare ID, `service :80 ...`,
+> deriving the name from the command.  There is no block equivalent:
+> the title carries both name and ID.
+
+
+Conditional Loading
+-------------------
+
+Finit supports conditional loading of blocks.  The following example is
+taken from the `system/10-hotplug.conf` file in the Finit distribution.
+Here we only show a simplified subset.
+
+Starting with the udev daemon, which goes by two names depending on
+how it was built.  Both are candidates for the same service:
+
+    service udevd {
+        pidfile = "udevd"
+        command = { "/lib/systemd/systemd-udevd", "-udevd" }
+    }
+
+When loading the .conf file Finit looks for
+`/lib/systemd/systemd-udevd`, and if that is not there it moves on to
+`udevd`.  A candidate that is not installed is expected, so no warning
+is logged for the ones that are skipped.  The leading `-` on the last
+one says it is also fine if none of them are found, in which case the
+block is dropped quietly and no service named `udevd` exists.
+
+> [!NOTE]
+> This needs to be one block.  The title is the service identity, so
+> two blocks titled `udevd` in the same file are two declarations of
+> one service, which Finit rejects.  See [Duplicate
+> titles](service-opts.md#duplicate-titles).
+
+    run udevadm:1 {
+        runlevel   = "S"
+        if         = "udevd"
+        conditions = { "pid/udevd" }
+        command    = "-udevadm settle -t 0"
+    }
+
+This block is only loaded if we know of a service named `udevd`.  Again,
+we do not warn if `udevadm` is not found, execution will also stop here
+until the PID condition is asserted, i.e., Finit detecting udevd has
+started.
+
+    run mdev {
+        description = "Populating device tree"
+        runlevel    = "S"
+        conflicts   = { "udevd" }
+        command     = "-mdev -s"
+    }
+
+If `udevd` is not available, we try to run `mdev`, but if that is not
+found, again we do not warn.
+
+Conditional loading can also be negated, so the previous block can be
+written as:
+
+    run mdev {
+        description = "Populating device tree"
+        runlevel    = "S"
+        if          = "!udevd"
+        command     = "-mdev -s"
+    }
+
+The reason for using `conflicts` in this example is that a conflict can
+be resolved.  Blocks naming a conflict are rechecked at runtime.
+
+
+Conditional Execution
+---------------------
+
+Similar to conditional loading of blocks there is conditional runtime
+execution.  This can be confusing at first, since Finit already has a
+condition subsystem, but this is more akin to the qualification to a
+runlevel.  E.g., a task with `runlevel = "123"` is qualified to run
+only in runlevel 1, 2, and 3.  It is not considered for other
+runlevels.
+
+Conditional execution qualify a run/task/service based on a condition.
+Consider this (simplified) example from the Infix operating system:
+
+    run startup {
+        runlevel   = "S"
+        conditions = { "pid/sysrepo" }
+        command    = "confd -b --load startup-config"
+    }
+
+    run failure {
+        runlevel   = "S"
+        if         = "usr/fail-startup"
+        conditions = { "pid/sysrepo" }
+        command    = "confd --load failure-config"
+    }
+
+The two run blocks reside in the same .conf file so Finit runs them in
+true sequence.  If loading the file `startup-config` fails confd sets
+the condition `usr/fail-startup`, thus allowing the next one to load
+`failure-config`.
+
+Notice the critical difference between the `conditions` list and `if`.
+The former is a condition for starting; the latter is a condition to
+check whether a run/task/service is qualified to even be considered.
+`if` has a negation of its own, `!`, which is unrelated to anything in
+the `conditions` list.
+
+What `if` compares against depends on the value.  A namespace
+separator makes it a condition, anything else is a service name:
+
+| `if` | Asks |
+|---|---|
+| `"udevd"` | is a service by this name known? |
+| `"usr/foo"` | was this condition set? |
+
+Both are questions about whether the block belongs in the running
+configuration at all, usually answered from what bootstrap established.
+A statement is all of one kind or the other, so the block is rejected
+if you mix them.
+
+> [!NOTE]
+> `if` qualifies, it does not track.  A condition asserted or cleared
+> later does not start or stop the service by itself -- that is what
+> the `conditions` list is for.
+
+Conditional execution can also be negated, so provided the file loaded
+did the opposite, i.e., set a condition on success, the previous block
+can be written as:
+
+    run failure {
+        runlevel   = "S"
+        if         = "!usr/startup-ok"
+        conditions = { "pid/sysrepo" }
+        command    = "confd ..."
+    }
+
+Variants of one service are often qualified this way, one per platform,
+and they usually have to supply the same barrier to whatever waits for
+them.  Each variant needs its own title, since a title is an identity,
+and the shared barrier is named with `provides`.  See [Provided
+Conditions](service-opts.md#provided-conditions).

doc/config/sysv.md

@@ -0,0 +1,103 @@
+SysV Init Compatibility
+=======================
+
+It is not possible to run unmodified SysV init systems with Finit.  This
+was never the intention and is not the strength of Finit.  However, it
+comes with a few SysV Init compatibility features to ease the transition
+from a serialized boot process.
+
+SysV Init Scripts
+-----------------
+
+**Syntax:** `sysv NAME { command = "/path/to/init-script" }`
+
+> [!NOTE]
+> Conditions, runlevels, and the other settings a `sysv` block takes
+> are described in [Service Options](service-opts.md).
+
+A `sysv` block is a supervised daemon, like `service`, but started and
+stopped through a SysV style init script instead of a command line.  The
+intention is to reuse existing setup and init scripts from Linux
+distributions.
+  
+When entering an allowed runlevel, Finit calls `init-script start`, when
+entering a disallowed runlevel, Finit calls `init-script stop`, and if
+the Finit .conf, where the `sysv` block is declared, is modified, Finit
+calls `init-script restart` on `initctl reload`.  Similar to how
+`service` blocks work.
+
+Forking services started with `sysv` scripts can be monitored by Finit
+by declaring the PID file to look for: `pidfile = "/path/to/file.pid"`.
+Finit does not create that file, it watches it for the resulting
+forked-off PID.  That is the default; `pidfile-create = true` asks Finit
+to write it instead.  The same applies to forking daemons with no way to
+run in the foreground, see [Services](services.md).
+
+> [!TIP]
+> See also [SysV Init Compatibility](#sysv-init-compatibility).
+
+Run-parts
+---------
+
+For a directory with traditional start/stop scripts that should run, in
+order, at bootstrap, Finit provides the `runparts` setting.  It runs
+in runlevel S, at the very end of it (before calling `/etc/rc.local`)
+making it perfect for most scenarios.
+
+For syntax details, see the [Run-parts Scripts](runparts.md) section.
+Here is an example take from a Debian installation:
+
+    runparts = "/etc/rc2.d"
+
+Files in these directories are usually named `SNNfoo` and `KNNfoo`,
+which Finit knows about and automatically appends the correct argument:
+
+    /bin/sh -c /etc/rc2.d/S01openbsd-inetd start
+
+or
+
+    /bin/sh -c /etc/rc0.d/K01openbsd-inetd stop
+
+Files that do not match this pattern are started similarly but without
+the extra command line argument.
+
+Start/Stop Scripts
+------------------
+
+For syntax details, see [SysV Init Scripts](#sysv-init-scripts), above.
+Here follows an example taken from a Debian installation:
+
+    sysv inetd {
+        description = "OpenBSD inet daemon"
+        runlevel    = "2345"
+        conditions  = { "pid/syslogd" }
+        command     = "/etc/init.d/openbsd-inetd"
+    }
+
+The init script header could be parsed to extract `Default-Start:` and
+other parameters for the `sysv` command to Finit.  There is currently no
+way to detail a generic syslogd dependency in Finit, so `Should-Start:`
+in the header must be mapped to the condition system in Finit using an
+absolute reference, here we depend on the sysklogd project's syslogd.
+
+`/etc/rc.local`
+---------------
+
+One often requested feature, early on, was a way to run a site specific
+script to set up, e.g., static routes or firewall rules.  A user can add
+a `task` or `run` command in the Finit configuration for this, but for
+compatibility reasons the more widely know `/etc/rc.local` is used if
+it exists, and is executable.  It is called very late in the boot process
+when the system has left runlevel S, stopped all old and started all new
+services in the target runlevel (default 2).
+
+> [!NOTE]
+> In Finit releases before v4.5 this script blocked Finit execution and
+> made it as good as impossible to call `initctl` during that time.
+
+`init q`
+--------
+
+When `/sbin/finit` is installed as `/sbin/init`, it is possible to use
+`init q` to reload the configuration.  This is the same as calling
+`initctl reload`.

doc/config/task-and-run.md

@@ -0,0 +1,101 @@
+run (sequence)
+--------------
+
+**Syntax:** `run NAME { command = "/path/to/cmd ARGS" }`
+
+> Conditions, runlevels, and the other settings a `run` block takes are
+> described in [Service Options](service-opts.md).
+
+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.  Useful when serialization is
+required.
+
+> [!WARNING]
+> Try to avoid the `run` command.  It blocks much of the functionality
+> in Finit, like (re)starting other (perhaps crashing) services while a
+> `run` task is executing.  Use other synchronization mechanisms
+> instead, like conditions.
+
+Incomplete list of unsupported `initctl` commands in `run` tasks:
+
+ - `initctl runlevel N`, setting runlevel
+ - `initctl reboot`
+ - `initctl halt`
+ - `initctl poweroff`
+ - `initctl suspend`
+
+To prevent `initctl` from calling Finit when enabling and disabling
+services from inside a `run` task, use the `--force` option.  See
+also the `--quiet` and `--batch` options.
+
+task (parallel)
+---------------
+
+**Syntax:** `task NAME { command = "/path/to/cmd ARGS" }`
+
+> A `task` block takes the same settings as `run`, see
+> [Service Options](service-opts.md).
+
+One-shot like 'run', but starts in parallel with the next command.
+  
+Both `run` and `task` commands are run in a shell, so basic pipes and
+redirects can be used:
+
+    task bar {
+        runlevel = "S"
+        command  = "echo \"foo\" | cat >/tmp/bar"
+    }
+
+Please note, `;`, `&&`, `||`, and similar are *not supported*.  Any
+non-trivial constructs are better placed in a separate shell script.
+
+
+remain-after-exit
+-----------------
+
+By default, a `run` or `task` will re-run each time its runlevel is
+entered, and its `exec-stop-post` script does not run on completion.
+
+With `remain-after-exit`, the task runs once and does not re-run on
+runlevel re-entry:
+
+    task firewall {
+        description       = "Firewall setup"
+        runlevel          = "2345"
+        remain-after-exit = true
+        command           = "/usr/sbin/setup-firewall"
+    }
+
+This has the following effects:
+
+  * The task does not re-run on runlevel re-entry
+  * The `exec-stop-post` script runs when:
+    - The task is explicitly stopped (`initctl stop NAME`)
+    - The task leaves its valid runlevels (e.g., runlevel change)
+
+This is useful for tasks that set up persistent state where:
+
+  * Cleanup should only happen on explicit stop or when leaving valid runlevels
+  * The setup should not be re-run on every runlevel entry
+
+**Example:** Setting up firewall rules with cleanup on shutdown:
+
+```
+task firewall {
+    description       = "Firewall setup"
+    runlevel          = "2345"
+    remain-after-exit = true
+    exec-stop-post    = "/usr/sbin/teardown-firewall"
+    command           = "/usr/sbin/setup-firewall"
+}
+```
+
+The firewall rules are created once.  The `exec-stop-post` script runs when
+entering runlevel 0 (halt) or 6 (reboot), or on explicit stop.
+
+> [!NOTE]
+> The `remain-after-exit` setting is not supported for bootstrap-only
+> tasks (tasks with only runlevel S).  Bootstrap tasks are deleted
+> immediately after completion, and their `exec-stop-post` scripts never
+> run.  A warning is logged if `remain-after-exit` is used on such tasks.

doc/config/templating.md

@@ -0,0 +1,43 @@
+Templating
+==========
+
+Finit comes with rudimentary support for templating, similar to that of
+systemd.  Best illustrated with an example:
+
+    $ initctl show avahi-autoipd@
+    service avahi-autoipd:%i {
+        description = "ZeroConf for %i"
+        command     = "avahi-autoipd --syslog %i"
+    }
+
+To enable ZeroConf for, e.g., `eth0`, use
+
+    $ initctl enable avahi-autoipd@eth0.conf
+
+The enabled symlink will be set up to `avahi-autoipd@.conf` and every
+instance of `%i` will be replaced with `eth0` before the file is
+parsed, so it works in the block title, in any value, and in the
+command line alike.  Inspect the result with `initctl show
+avahi-autoipd:eth0`, and check a running instance with:
+
+```
+$ initctl status avahi-autoipd:eth0
+     Status : running
+   Identity : avahi-autoipd:eth0
+Description : ZeroConf for eth0
+     Origin : /etc/finit.d/enabled/avahi-autoipd@eth0.conf
+Environment : -/etc/default/avahi-autoipd-eth0
+    Command : avahi-autoipd $AVAHI_AUTOIPD_ARGS eth0
+   PID file : /run/avahi-autoipd.eth0.pid
+        PID : 4190
+       User : root
+      Group : root
+     Uptime : 24 sec
+   Restarts : 0 (0/10)
+  Runlevels : [---2345-789]
+     Memory : 20.0k
+     CGroup : /system/avahi-autoipd@eth0 cpu 0 [100, max] mem [0, max]
+              └─ 4190 avahi-autoipd: [eth0] bound 169.254.1.9  
+
+Jul  8 11:51:42 infix-c0-ff-ee finit[1]: Starting avahi-autoipd:eth0[4190]
+```

doc/config/tty.md

@@ -0,0 +1,167 @@
+TTYs and Consoles
+=================
+
+**Syntax:** `tty NAME { device = DEV }` -- built-in getty  
+  `tty NAME { command = "CMD ARGS" }` -- external getty  
+  `tty NAME { notty = true }`, or `{ rescue = true }` -- bare shell, no device
+
+The block title NAME is what `initctl` shows.  The three variants differ
+in what they open: `device` runs the built-in getty on that TTY, and DEV
+may be the special keyword `@console`, expanded from
+`/sys/class/tty/console/active`, useful on embedded systems.  `command`
+hands the TTY to an external getty.  `notty` opens nothing at all.
+
+`command` may name several candidates, `{ "agetty ...", "getty ..." }`,
+and Finit runs the first one it finds.  See [Command
+Candidates](service-opts.md#command-candidates).
+
+Settings common to all three:
+
+| Setting | Alias | Description |
+|---|---|---|
+| `runlevel` | | Runlevels to run in, e.g. `"12345"` |
+| `conditions` | `cond` | Conditions to wait for |
+| `noclear` | | Do not clear the TTY after each session |
+| `nowait` | | Do not wait for Enter before the login prompt |
+| `nologin` | | Skip login, give a shell straight away |
+| `passenv` | | Pass the environment on to `login`, built-in getty only |
+
+The `device` variant takes two more:
+
+| Setting | Description |
+|---|---|
+| `baud` | Baud rate, default 0, i.e., keep kernel default |
+| `term` | `$TERM` value, e.g. `"vt220"` |
+
+> A `tty` block inherits runlevel, condition (and other feature)
+> parsing from the `service` block.  So TTYs can run in one or many
+> runlevels and depend on any condition supported by Finit.  This is
+> useful e.g. to depend on `<pid/elogind>` before starting a TTY.
+
+**Example:**
+
+    tty ttyAMA0 {
+        runlevel = "12345"
+        device   = "/dev/ttyAMA0"
+        baud     = 115200
+        term     = "vt220"
+        noclear  = true
+    }
+
+The second `tty` syntax variant is for using an external getty, like
+agetty or the BusyBox getty.
+
+The third variant is for board bringup and the `rescue` boot mode.  No
+device node is required, the same output the kernel uses is reused for
+stdio.  With `notty` a shell is started (`nologin`, `noclear`, and
+`nowait` are implied); with `rescue` the bundled
+`/libexec/finit/sulogin` presents a bare-bones root login prompt.  If
+the root (uid:0, gid:0) user does not have a password set, no rescue is
+possible.  For more information, see the [Rescue Mode](rescue.md)
+section.
+
+By default, the first two syntax variants *clear* the TTY and *wait* for
+the user to press enter before starting getty.
+
+**Example:**
+
+    tty getty {
+        runlevel = "12345"
+        command  = "/sbin/getty -L 115200 /dev/ttyAMA0 vt100"
+    }
+
+    tty agetty {
+        runlevel = "12345"
+        command  = "/sbin/agetty -L ttyAMA0 115200 vt100"
+        nowait   = true
+    }
+
+The `noclear` setting disables clearing the TTY after each session.
+Clearing the TTY when a user logs out is usually preferable.
+  
+The `nowait` setting 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.
+
+The `nologin` setting disables getty and `/bin/login`, and gives the
+user a root (login) shell on the given TTY immediately.
+Needless to say, this is a rather insecure option, but can be very
+useful for developer builds, during board bringup, or similar.
+
+Embedded systems may want to enable automatic `DEV` by supplying the
+special `@console` device.  This works regardless whether the system
+uses `ttyS0`, `ttyAMA0`, `ttyMXC0`, or anything else.  Finit figures
+it out by querying sysfs: `/sys/class/tty/console/active`.  Leave
+`baud` out to keep the kernel default.
+
+> Most systems get by fine by just using `console`, which will evaluate
+> to `/dev/console`.  If you have to use `@console` to get any output,
+> you may have some issue with your kernel config.
+
+**Example:**
+
+    tty console {
+        runlevel = "12345"
+        device   = "@console"
+        term     = "vt220"
+        noclear  = true
+    }
+
+On really bare bones systems, or for board bringup, Finit can give you a
+shell prompt as soon as bootstrap is done, without opening any device
+node:
+
+    tty board {
+        runlevel = "12345789"
+        notty    = true
+    }
+
+This should of course not be enabled on production systems.  Because it
+may give a user root access without having to log in.  However, for
+board bringup and system debugging it can come in handy.
+
+One can also use a `service` block to start a stand-alone shell:
+
+    service shell {
+        runlevel = "12345"
+        command  = "/bin/sh -l"
+    }
+
+Controlling TTY for Services
+----------------------------
+
+The `tty` setting gives a `run`, `task`, or `service` a controlling
+terminal on the given device.  The device is opened, set as the
+controlling terminal for the session (after `setsid()`), and connected to
+the process's stdin, stdout, and stderr.  A default `TERM` environment
+variable is set based on the device type: `vt102` for serial lines and
+`linux` for virtual terminals.
+
+The value may be a device node like `/dev/ttyS0`, or the special
+keyword `@console` (see above).  Note that `@console` expands only to
+the first console, not all.
+
+When `tty` is combined with a `log` block, stdout and stderr are
+redirected to the log sink instead of the TTY, but stdin remains
+connected to the TTY device.
+
+> The `tty` setting is for `run`, `task`, and `service` blocks only.
+> A `tty` block (for getty/login) is a different thing entirely, see
+> above.
+
+**Example:**
+
+    service foo {
+        description = "Foo on serial console"
+        runlevel    = "2345"
+        tty         = "/dev/ttyS0"
+        command     = "/usr/sbin/foo"
+    }
+
+    task setup {
+        description = "Board bringup on console"
+        runlevel    = "S"
+        tty         = "@console"
+        command     = "my-setup-script"
+    }

doc/dbus.md

@@ -0,0 +1,375 @@
+D-Bus Integration
+=================
+
+Finit ships with a built-in, brokerless [D-Bus][] implementation, **libink**
+(`-link`), that exposes the running init system as a peer on its own private
+bus, and optionally on the system bus when `dbus-daemon` is available.
+Everything `initctl` does is also reachable from any generic D-Bus tooling —
+`dbus-send`, `dbus-monitor`, `gdbus`, language bindings, dashboards,
+monitoring agents, etc.
+
+> [!NOTE]
+> D-Bus support is enabled by default, opt out at build time with
+> `--disable-dbus`, see [Building](build.md) for details.  When disabled,
+> `initctl` keeps using the legacy `INIT_SOCKET` transport and Finit
+> exposes no bus.
+
+Bus address
+-----------
+
+| Bus                    | Address                                     |
+|------------------------|---------------------------------------------|
+| Local (always)         | `unix:path=/run/finit/bus`                  |
+| System (opportunistic) | `unix:path=/var/run/dbus/system_bus_socket` |
+
+The bundled device manager serves its own `org.finit.Device1` the same
+way on `unix:path=/run/keventd/bus`, see [keventd](keventd.md); one
+socket per daemon, no forwarding between them.
+
+The **local** bus is brokerless: clients connect straight to Finit over a
+Unix-domain socket using the standard D-Bus SASL EXTERNAL handshake.  No
+`dbus-daemon` is required, which makes it suitable for embedded systems that
+don't ship one.
+
+The socket is `0660`, owned by `root` and the group given to
+`--with-group` at build time, the same gate as `/run/finit/socket` that
+`initctl` falls back on.  The bus reaches every operation `initctl`
+does, so restricting one and not the other would leave the door open.
+Members of that group may use it, see [Authorization](#authorization).
+
+Finit accepts at most 64 concurrent local-bus peers; further
+connections are refused until one disconnects.  Match rules given to
+`AddMatch` support the `type`, `interface`, `member`, and `path` keys;
+`arg0` and its variants are not implemented.
+
+For the system bus a standard busconfig policy ships in
+`dbus-1/org.finit.conf`, installed to `$datadir/dbus-1/system.d`: only
+root may own `org.finit`, unprivileged callers reach introspection,
+properties, and the read-only methods.
+Finit also enforces per-method authorization itself, so a permissive
+policy installed by mistake does not open state-changing methods.
+
+The **system** bus is best-effort: Finit probes for a running `dbus-daemon`
+and, when reachable, claims the well-known name `org.finit` so that standard
+tooling sees Finit just like any other system service:
+
+```sh
+dbus-send --system --print-reply --dest=org.finit /org/finit/manager \
+          org.finit.Manager1.ListServices
+
+dbus-monitor --system "sender='org.finit'"
+```
+
+If no system bus is present (the common case on embedded targets), this step
+is silently skipped.
+
+Object tree
+-----------
+
+```
+/
+├── org/
+│   └── finit/
+│       ├── manager                          Manager1
+│       ├── cond                             Cond1
+│       └── service/
+│           ├── keventd                      Service1 (one per service)
+│           ├── sshd
+│           └── …
+└── org/freedesktop/DBus                     Standard well-known interfaces
+```
+
+Every node implements the usual stock interfaces:
+
+| Interface                             | Purpose                                   |
+|---------------------------------------|-------------------------------------------|
+| `org.freedesktop.DBus`                | `Hello`, `AddMatch`, `RemoveMatch` — on `/org/freedesktop/DBus` only |
+| `org.freedesktop.DBus.Peer`           | `Ping`, `GetMachineId`                    |
+| `org.freedesktop.DBus.Introspectable` | `Introspect()` — XML description          |
+| `org.freedesktop.DBus.Properties`     | `Get`, `GetAll`; nothing is writable      |
+
+Note: `Hello`, `AddMatch`, and `RemoveMatch` are answered on the canonical
+`/org/freedesktop/DBus` object only, as per the D-Bus specification.
+
+`org.finit.Manager1`
+--------------------
+
+Lives at **`/org/finit/manager`**.  Owns the global init operations
+and the service registry.
+
+### Methods
+
+| Method                       | In sig | Out sig | Priv. | Notes                                                     |
+|------------------------------|--------|---------|-------|-----------------------------------------------------------|
+| `ListServices`               | —      | `as`    | no    | Returns identities (`name`, `name:id`) of loaded services |
+| `GetService`                 | `s`    | `o`     | no    | Resolves an identity to its `Service1` object path        |
+| `Start`                      | `s`    | —       | yes   | Start the service(s) matching the identity                |
+| `Stop`                       | `s`    | —       | yes   | Stop the service(s) matching the identity                 |
+| `Restart`                    | `s`    | —       | yes   | Restart (stop + start) the service(s)                     |
+| `Reload`                     | —      | —       | yes   | Re-read all `*.conf` and apply changes                    |
+| `SetRunlevel`                | `u`    | —       | yes   | Transition to runlevel `u` (0–9)                          |
+| `SetDebug`                   | —      | —       | yes   | Toggle Finit's runtime debug flag                         |
+| `Signal`                     | `su`   | —       | yes   | Send signal `u` (1–31) to services matching identity `s`  |
+| `Suspend`                    | —      | —       | yes   | `sync()` + suspend-to-RAM                                 |
+| `Reboot`, `Halt`, `Poweroff` | `u`    | —       | yes   | Trigger the corresponding shutdown sequence; the argument arms the emergency fallback timer (seconds, 0 = none) |
+
+Edge cases follow the legacy `initctl` protocol: `Suspend` and the
+reboot family reply `WrongRunlevel` during bootstrap and shutdown,
+`SetRunlevel` is a warning + no-op in runlevel 0/6 and records the
+level for the end of bootstrap in runlevel S, and `Signal` fails for
+stopped services.  One deliberate divergence: a `SetRunlevel` argument
+outside 0–9 returns `InvalidArgs`, where the legacy protocol
+acknowledges silently.
+
+### Properties
+
+All read-only strings; observable via `Properties.Get` and
+`Properties.GetAll`.
+
+| Property       | Type | Returns                                                |
+|----------------|------|--------------------------------------------------------|
+| `Runlevel`     | `s`  | Current runlevel as a digit (`"2"`, `"3"`, …) or `"S"` |
+| `PrevRunlevel` | `s`  | Previous runlevel, same encoding, `"N"` when none      |
+| `Version`      | `s`  | Finit's version string (`PACKAGE_VERSION`)             |
+
+### Signals
+
+| Signal                | Body                                   | Fires when             |
+|-----------------------|----------------------------------------|------------------------|
+| `ServiceStateChanged` | `sss` — identity, old state, new state | Service transitions    |
+| `RunlevelChanged`     | `ss`  — old level, new level           | System runlevel change |
+| `ConfigReloaded`      | —                                      | `initctl reload` completed; providers of generation-file conditions re-assert |
+
+State names emitted by `ServiceStateChanged` are stable wire strings:
+`halted`, `done`, `dead`, `cleanup`, `teardown`, `stopping`, `setup`,
+`paused`, `waiting`, `starting`, `running`.  `RunlevelChanged` levels
+use the same encoding as the `Runlevel` property: digits, `"S"`, `"N"`.
+
+`org.finit.Service1` (per-service objects)
+------------------------------------------
+
+Lives at **`/org/finit/service/<encoded>`**, one object per loaded service.
+`<encoded>` is the service identity (name, or `name:id` for templated
+services) put through systemd-style `_HH` hex escaping — ASCII alphanumerics
+and `_` pass through, anything else becomes `_HH` where `HH` is the hex byte.
+Use `Manager1.GetService(identity)` to look up the exact path rather than
+constructing it by hand.
+
+| Method    | In sig | Out sig | Priv. | Notes                                                       |
+|-----------|--------|---------|-------|-------------------------------------------------------------|
+| `Start`   | —      | —       | yes   | Equivalent to `Manager1.Start(<identity>)` for this service |
+| `Stop`    | —      | —       | yes   | …                                                           |
+| `Restart` | —      | —       | yes   | …                                                           |
+| `Reload`  | —      | —       | yes   | Send the service's `reload-signal`, default `SIGHUP`; restart when set to `"none"` |
+
+### Properties
+
+All read-only; observable via `Properties.Get` and `Properties.GetAll`.
+
+| Property        | Type | Returns                                                        |
+|-----------------|------|----------------------------------------------------------------|
+| `Identity`      | `s`  | Service identity, `name` or `name:id`                          |
+| `Name`          | `s`  | Program name (basename of the command)                         |
+| `State`         | `s`  | Current status, same vocabulary as `initctl status`            |
+| `Pid`           | `u`  | Current PID, 0 when not running                                |
+| `RestartCount`  | `u`  | Restarts since the last stable run                             |
+| `Runlevels`     | `u`  | Allowed runlevels as a bitmask, bit N = runlevel N, bit 10 = S |
+| `Description`   | `s`  | The service's `description` string                             |
+| `Command`       | `s`  | Full command line, arguments included                          |
+| `Conditions`    | `s`  | Declared conditions, raw `.conf` form                          |
+| `Type`          | `s`  | Unit type: `service`, `task`, `run`, `sysv`, `tty`, `free`     |
+| `Origin`        | `s`  | Source `.conf` file, empty for built-ins                       |
+| `Environment`   | `s`  | The service's `env` setting, raw                               |
+| `PidFile`       | `s`  | Declared PID file, raw (`!` prefix included)                   |
+| `User`          | `s`  | User the service runs as                                       |
+| `Group`         | `s`  | Group the service runs as                                      |
+| `Uptime`        | `u`  | Seconds since start, 0 when not running                        |
+| `ExitStatus`    | `u`  | Raw `waitpid(2)` status from the last exit                     |
+| `RestartsTotal` | `u`  | Restarts over the service's lifetime                           |
+| `RestartMax`    | `u`  | Restart limit before the service is blocked                    |
+| `Starts`        | `u`  | Times started, for `manual-start` units                        |
+| `ManualStart`   | `b`  | `manual-start` set in the `.conf`                              |
+| `Forking`       | `b`  | Daemon forks to background                                     |
+| `Started`       | `b`  | Run/task completed successfully                                |
+
+On every state transition the object also emits the standard
+`org.freedesktop.DBus.Properties.PropertiesChanged` signal: `State`
+in the changed dictionary, `Pid` and `RestartCount` invalidated (call
+`Get` for fresh values).
+
+The per-service surface lets generic tooling supply an object handle
+once and then invoke methods on it, instead of repeatedly passing the
+identity string.
+
+`org.finit.Cond1`
+-----------------
+
+Lives at **`/org/finit/cond`**.  Exposes Finit's
+[condition system](conditions.md) to bus clients.
+
+### Methods
+
+| Method  | In sig | Out sig | Priv. | Notes                                                        |
+|---------|--------|---------|-------|--------------------------------------------------------------|
+| `Get`   | `s`    | `s`     | no    | Returns `"on"`, `"off"`, or `"flux"` for the named condition |
+| `Set`   | `s`    | —       | yes   | Assert a `usr/<name>` condition                              |
+| `Clear` | `s`    | —       | yes   | Deassert a `usr/<name>` condition                            |
+| `List`  | —      | `as`    | no    | Names of all known conditions                                |
+| `Dump`  | —      | `a(ss)` | no    | `(name, state)` pairs for everything `List` returns          |
+
+Note: non-`usr/*` paths are rejected with `InvalidArgs` -- system
+conditions belong to Finit's state machine.
+
+A service consuming such a condition:
+
+    service alarm {
+        description = "Foo alarm"
+        runlevel    = "2345"
+        conditions  = { "usr/data-ready" }
+        command     = "alarm --arg foo"
+    }
+
+asserted from any bus client with `Cond1.Set string:"data-ready"`, see
+the examples below.
+
+### Signals
+
+| Signal             | Body                   | Fires when                            |
+|--------------------|------------------------|---------------------------------------|
+| `ConditionChanged` | `ss` — name, new state | A condition is asserted or deasserted |
+
+Authorization
+-------------
+
+Privileged methods accept `root`, and any caller belonging to the group given
+to `--with-group` at build time.  That is the same set the socket mode already
+admits, so the two gates agree instead of the socket letting the group in and
+every method turning it away.
+
+On the **local** bus the kernel settles this at `connect()`: `SO_PEERCRED`
+gives Finit the caller's uid and `SO_PEERGROUPS` its group set, both straight
+from the kernel.  Finit matches the group against `--with-group` itself, so
+the check never touches NSS -- `getpwuid`/`getgrouplist` can block on a slow
+LDAP or SSSD backend, and PID 1 must never block.  Because the group set is
+the caller's real credentials, privilege escalation through the bus is
+impossible.
+
+On the **system** bus one connection carries every caller, so `SO_PEERCRED`
+describes `dbus-daemon` rather than whoever asked.  Finit asks the bus driver
+`GetConnectionUnixUser` about the message sender and holds the call until the
+answer arrives -- nothing blocks, the reply comes back through the same event
+loop as everything else.  The broker does not report the caller's groups in
+that reply, so **privileged methods over the system bus are root-only**; group
+membership is honoured on the local bus only.  Lifting that is future work,
+see `libink/README.md`.
+
+Answers are cached per sender.  A bus never reuses a unique name while it
+runs, so an answer holds for as long as that bus does; Finit empties the cache
+when the broker goes away, since a new one numbers its clients from scratch.
+A caller Finit cannot identify is refused, so the failure mode is a denial
+rather than an escalation.
+
+When a privileged method is rejected the error name is exactly
+`org.freedesktop.DBus.Error.AccessDenied`, and the body carries a short reason
+string.
+
+`initctl` integration
+---------------------
+
+`initctl` transparently routes through D-Bus when the bus socket is present,
+and falls back to the legacy `INIT_SOCKET` transport otherwise.  Concretely,
+the following subcommands use the bus first:
+
+| Subcommand                 | Method                                           |
+|----------------------------|--------------------------------------------------|
+| `initctl start`            | `Manager1.Start(svc)`                            |
+| `initctl stop`             | `Manager1.Stop(svc)`                             |
+| `initctl restart`          | `Manager1.Restart(svc)`                          |
+| `initctl reload`           | `Manager1.Reload()`                              |
+| `initctl reload S`         | `Service1.Reload()` (per-svc)                    |
+| `initctl reboot`           | `Manager1.Reboot(timeout)`                       |
+| `initctl halt`             | `Manager1.Halt(timeout)`                         |
+| `initctl poweroff`         | `Manager1.Poweroff(timeout)`                     |
+| `initctl suspend`          | `Manager1.Suspend()`                             |
+| `initctl debug`            | `Manager1.SetDebug()`                            |
+| `initctl signal` (or `kill`) | `Manager1.Signal(svc, signo)`                  |
+| `initctl runlevel`         | `Properties.Get(Manager1.Runlevel/PrevRunlevel)` |
+| `initctl cond set/get/clear` | `Cond1.{Set,Get,Clear}`, `clr` is an alias     |
+
+Two `initctl` subcommands are pure D-Bus features without legacy equivalents:
+
+* `initctl monitor` — subscribes to every signal on the local bus and prints
+  one line per delivery (with timestamp, interface and member).  Same idea as
+  `dbus-monitor`, but scoped to Finit and with no need to pass `--address`.
+
+* `initctl cond` emits the standard `Cond1.ConditionChanged` signal as a side
+  effect, so subscribers observe user-driven state changes the same way they
+  observe service-driven ones.
+
+Examples
+--------
+
+The examples below use `dbus-send` and `dbus-monitor`, which ship as part of
+the [dbus][] reference implementation; they're widely packaged and don't pull
+in any extra runtime.  Any tool that speaks D-Bus over an AF_UNIX socket works
+equally well — `gdbus`, Python's `jeepney`/`dasbus`, etc. — substitute their
+syntax for setting the bus address.  The wire protocol is the compatibility
+surface: Finit's own **libink** is an internal implementation detail, external
+clients should use any standard D-Bus library.
+
+When `org.finit` is registered on the system bus you can replace
+`--address=unix:path=/run/finit/bus` with `--system` in any example below.
+
+List the running services:
+
+```sh
+dbus-send --address=unix:path=/run/finit/bus \
+          --type=method_call --print-reply --dest=org.finit \
+          /org/finit/manager \
+          org.finit.Manager1.ListServices
+```
+
+Read the current runlevel via the Properties interface:
+
+```sh
+dbus-send --address=unix:path=/run/finit/bus \
+          --type=method_call --print-reply --dest=org.finit \
+          /org/finit/manager \
+          org.freedesktop.DBus.Properties.Get \
+          string:org.finit.Manager1 string:Runlevel
+```
+
+Subscribe to every state change on the manager object:
+
+```sh
+dbus-monitor --address=unix:path=/run/finit/bus \
+             "type='signal',interface='org.finit.Manager1'"
+```
+
+Or use `initctl monitor`, which does the same without any address
+plumbing.
+
+Restart a service by its object path:
+
+```sh
+dbus-send --address=unix:path=/run/finit/bus \
+          --type=method_call --dest=org.finit \
+          /org/finit/service/sshd \
+          org.finit.Service1.Restart
+```
+
+Trigger a `usr/`-condition assertion that wakes any dependent service:
+
+```sh
+dbus-send --address=unix:path=/run/finit/bus \
+          --type=method_call --dest=org.finit \
+          /org/finit/cond \
+          org.finit.Cond1.Set string:"data-ready"
+```
+
+The `--dest=org.finit` argument is informational on the local
+brokerless bus — Finit accepts any destination because there's no
+broker to route by name — but `dbus-send` requires it syntactically.
+
+[dbus]:  https://gitlab.freedesktop.org/dbus/dbus
+[D-Bus]: https://dbus.freedesktop.org/doc/dbus-specification.html

doc/distro.md

@@ -1,80 +1,139 @@
 Distro Recommendations
 ======================
 
-By default Finit uses the following directories for configuration files:
+Finit supports two directory layouts for managing service configurations:
+
+1. **Simple layout** - all configuration files directly in `/etc/finit.d/`
+2. **Distro layout** - separate `available/` and `enabled/` directories
+
+The distro layout is recommended for distributions that need clear
+separation between installed and enabled services, and want to use the
+`initctl enable/disable` commands for service management.
+
+## Simple Layout
+
+Finit supports using a flat directory structure:
 
 ```
     /etc/
-      |-- finit.d/              -- Regular (enabled) services
+      |-- finit.d/              -- All enabled services
       |    |-- lighttpd.conf
       |     `- *.conf
       |-- finit.conf            -- Bootstrap tasks and services
       :
 ```
 
-To enable a service one simply drops a small configuration file in the
-`/etc/finit.d/` directory.  This practice works with systems that
-keep disabled services elsewhere, or generates them as needed from some
-other tool.
+In this layout, you enable a service by placing its `.conf` file in
+`/etc/finit.d/` and disable it by removing the file. This works well for
+embedded systems or custom setups where services are managed by other tools
+or generated dynamically.
 
-Distributions, however, may want a clearer separation of enabled and
-available (installed but not enabled) services.  They may even want to
-customize the directories used, for brand labeling or uniformity.
+> [!NOTE] No tooling support
+> The `initctl enable/disable` commands **do not work** with this layout.
+> You must manually manage files in `/etc/finit.d/`.
 
-To that end Finit allows for a sub-directory `/etc/finit.d/available/`
-where installed but disabled services can reside.  Adding a symlink to a
-configuration in this sub-directory enables the service, but it will not
-be started.
+## Distro Layout
 
-To change the default configuration directory and configuration file
-names the Finit `configure` script offers the following two options at
-build time:
+Distributions typically want clearer separation between available (installed)
+and enabled services. Finit supports this through the `available/` and
+`enabled/` subdirectories:
+
+```
+    /etc/
+      |-- finit.d/
+      |    |-- available/      -- Installed but disabled services
+      |    |    |-- httpd.conf
+      |    |    |-- ntpd.conf
+      |    |    `-- sshd.conf
+      |    |-- enabled/        -- Enabled services (symlinks)
+      |    |     `- sshd.conf  -- Symlink to ../available/sshd.conf
+      |-- finit.conf           -- Bootstrap tasks and services
+      :
+```
+
+In this layout:
+- **available/** contains all installed service configurations
+- **enabled/** contains symlinks to configurations that should start at boot
+- Services are enabled/disabled by creating/removing symlinks
+
+> [!IMPORTANT] Recommended
+> This is the recommended layout.  In fact, the `initctl enable/disable`
+> commands **require** this layout with both `available/` and `enabled/`
+> directories and will not work without it.
+
+## Managing Services with initctl
+
+When using the distro layout, the `initctl` tool provides convenient commands
+for managing service configurations:
+
+```
+   list              List all .conf in /etc/finit.d/
+   enable   <CONF>   Enable .conf by creating symlink in enabled/
+   disable  <CONF>   Disable .conf by removing symlink from enabled/
+   reload            Reload *.conf in /etc/finit.d/ (activate changes)
+```
+
+Example usage:
+
+```bash
+# Enable sshd (creates enabled/sshd.conf -> ../available/sshd.conf)
+initctl enable sshd
+
+# Disable httpd (removes enabled/httpd.conf symlink)
+initctl disable httpd
+
+# Apply changes (reload configuration and start/stop services)
+initctl reload
+```
+
+The `.conf` suffix is optional - `initctl` adds it automatically if missing.
+
+> [!NOTE] Remember `initctl reload`
+> Changes made with `enable`/`disable` take effect only after running
+> `initctl reload`, unless Finit was built with `--enable-auto-reload`
+> which automatically detects and applies configuration changes.
+
+### Service Overrides
+
+The `initctl` tool only operates on symlinks in the `enabled/` directory.
+If you place a regular (non-symlink) `.conf` file directly in the parent
+directory (e.g., `/etc/finit.d/`), `initctl` will ignore it. This allows
+you to create system-level overrides that cannot be accidentally disabled
+by package management tools.
+
+## Customizing Directory Paths
+
+Distributions can customize the directory names and locations at build time
+using the Finit `configure` script:
 
 ```sh
 ./configure --with-rcsd=/etc/init.d --with-config=/etc/init.d/init.conf
 ```
 
-> [!IMPORTANT]
-> Remember `--prefix` et al as well, the default is likely *not* what
-> you want.  See the [build docs][1] for details.
+This changes the default `/etc/finit.d/` to `/etc/init.d/` and moves the
+bootstrap configuration file accordingly.
 
-The resulting directory structure is depicted below.  Please notice how
-`/etc/finit.conf` now resides in the same sub-directory as a non-symlink
-`/etc/init.d/init.conf`:
+> [!IMPORTANT] Remember to set `--prefix`
+> Remember to set `--prefix` and related options appropriately. The default
+> prefix is `/usr/local`, which is likely not what you want for a system
+> init. See the [build documentation][1] for details.
+
+Example with custom paths:
 
 ```
     /etc/
       |-- init.d/
-      |    |-- available/      -- Regular (disabled) services
+      |    |-- available/      -- Installed services
       |    |    |-- httpd.conf
       |    |    |-- ntpd.conf
       |    |    `-- sshd.conf
-      |    |-- sshd.conf       -- Symlink to available/sshd.conf
+      |    |-- enabled/        -- Enabled services (symlinks)
+      |    |     `- sshd.conf  -- Symlink to ../available/sshd.conf
       |     `- init.conf       -- Bootstrap tasks and services
       :
 ```
 
-To facilitate the task of managing configurations, be it a service,
-task, run, or other stanza, the `initctl` tool has a a few built-in
-commands:
-
-```
-   list              List all .conf in /etc/finit.d/
-   enable   <CONF>   Enable   .conf in /etc/finit.d/available/
-   disable  <CONF>   Disable  .conf in /etc/finit.d/[enabled/]
-   reload            Reload  *.conf in /etc/finit.d/ (activates changes)
-```
-
-To enable a service like `sshd.conf`, above, use
-
-    initctl enable sshd
-
-The `.conf` suffix is not needed, `initctl` adds it implicitly if it is
-missing.  The `disable` command works in a similar fashion.
-
-Note, however, that `initctl` only operates on symlinks and it always
-requires the `available/` sub-directory.  Any non-symlink in the parent
-directory, here `/etc/init.d/`, will be considered a system override by
-`initctl`.
+Notice how both the service directory and bootstrap configuration file now
+use the custom `/etc/init.d/` path specified at build time.
 
 [1]: build.md#configure

doc/example.md

@@ -0,0 +1,214 @@
+Configuration Example
+=====================
+
+This example `/etc/finit.conf` can also be split up in multiple `.conf`
+files in `/etc/finit.d`.  Available, but not yet enabled, services can
+be placed in `/etc/finit.d/available` and enabled by an operator using
+the [initctl](initctl.md) tool.
+
+See the [contrib/][contrib] directory on GitHub for examples, or take a
+peek at systems using Finit, like [Infix OS][infix] and [myLinux][].
+
+> [!TIP]
+> A block spans as many lines as it needs, so no continuation character is
+> called for.  For the full syntax, see the [finit.conf(5)][] manual or the
+> [Configuration](config/index.md) section.
+
+```ApacheConf
+# Fallback if /etc/hostname is missing
+hostname = "default"
+
+# Runlevel to start after bootstrap, 'S', default: 2
+#runlevel = 2
+
+# Global environment variables, be careful though with variables like
+# PATH, SHELL, LOGNAME, etc.
+#environment {
+#    PATH = "/usr/bin:/bin:/usr/sbin:/sbin"
+#}
+
+# Max file size for each log file: 100 kiB, rotate max 4 copies:
+# log => log.1 => log.2.gz => log.3.gz => log.4.gz
+log {
+    size  = 100k
+    count = 4
+}
+
+# Services to be monitored and respawned as needed
+service watchdog {
+    description = "System watchdog daemon"
+    runlevel    = "S12345"
+    envfile     = "-/etc/conf.d/watchdog"
+    command     = "watchdog $WATCHDOG_OPTS $WATCHDOG_DEV"
+}
+service syslogd {
+    description = "System log daemon"
+    runlevel    = "S12345"
+    envfile     = "-/etc/conf.d/syslog"
+    command     = "syslogd -n $SYSLOGD_OPTS"
+}
+service klogd {
+    description = "Kernel log daemon"
+    runlevel    = "S12345"
+    conditions  = { "pid/syslogd" }
+    envfile     = "-/etc/conf.d/klogd"
+    command     = "klogd -n $KLOGD_OPTS"
+}
+service lldpd {
+    description = "LLDP daemon (IEEE 802.1ab)"
+    runlevel    = "2345"
+    envfile     = "-/etc/conf.d/lldpd"
+    command     = "lldpd -d $LLDPD_OPTS"
+}
+
+# The BusyBox ntpd does not use syslog when running in the foreground
+# So we use this trick to redirect stdout/stderr to a log file.  The
+# log file is rotated with the above settings.  The condition declares
+# a dependency on a system default route (gateway) to be set.  ntpd
+# does not respect SIGHUP, so Finit restarts it on reload instead.
+service ntpd {
+    description   = "NTP daemon"
+    runlevel      = "2345"
+    conditions    = { "net/route/default" }
+    reload-signal = "none"
+    log { file = "/var/log/ntpd.log" }
+    command       = "ntpd -n -l -I eth0"
+}
+
+# For multiple instances of the same service, add :ID to the block title.
+service merecat:80 {
+    description = "Web server"
+    runlevel    = "2345"
+    command     = "merecat -n -p 80 /var/www"
+}
+service merecat:8080 {
+    description = "Old web server"
+    runlevel    = "2345"
+    command     = "merecat -n -p 8080 /var/www"
+}
+
+# Alternative method instead of below runparts, can also use /etc/rc.local
+#sysv keyboard-setup {
+#    description = "Setting up preliminary keymap"
+#    runlevel    = "S"
+#    command     = "/etc/init.d/keyboard-setup"
+#}
+
+# Hidden from boot progress, using an empty description
+#sysv acpid {
+#    description = ""
+#    runlevel    = "S"
+#    command     = "/etc/init.d/acpid"
+#}
+
+# Run start scripts from this directory
+#runparts = "/etc/start.d"
+
+# Virtual consoles run BusyBox getty, keep kernel default speed
+tty tty1 {
+    runlevel = "12345"
+    command  = "/sbin/getty -L 0 /dev/tty1 linux"
+    nowait   = true
+    noclear  = true
+}
+tty tty2 {
+    runlevel = "2345"
+    command  = "/sbin/getty -L 0 /dev/tty2 linux"
+    nowait   = true
+    noclear  = true
+}
+tty tty3 {
+    runlevel = "2345"
+    command  = "/sbin/getty -L 0 /dev/tty3 linux"
+    nowait   = true
+    noclear  = true
+}
+
+# Use built-in getty for serial port and USB serial
+#tty ttyAMA0 { runlevel = "12345"  device = "/dev/ttyAMA0"  noclear = true  nowait = true }
+#tty ttyUSB0 { runlevel = "12345"  device = "/dev/ttyUSB0"  noclear = true }
+
+# Just give me a shell, I need to debug this embedded system!
+#tty console { runlevel = "12345"  device = "@console"  noclear = true  nologin = true }
+```
+
+The `service` block, as well as `task`, `run` and others are described in
+full in the [Services Syntax](config/services.md) section.
+
+Here's a quick overview of some of the most common components needed to start
+a UNIX daemon:
+
+```
+service NAME {                              <-- Supervised program (daemon)
+    description = "Example daemon"          <-- Optional description
+    runlevel    = "2345"                    <-- Optional runlevels
+    conditions  = { "net/route/default" }   <-- Optional conditions
+    envfile     = "-/etc/default/daemon"    <-- Optional env. file
+    log { }                                 <-- Redirect output to log
+    command     = "daemon ARGS"             <-- Path to daemon, and its arguments
+}
+```
+
+Only `command` is required, which makes simple cases short while leaving
+room for more advanced uses:
+
+    service sshd {
+        command = "/usr/sbin/sshd -D"
+    }
+
+Dependencies are handled using [conditions](conditions.md).  One of
+the most common conditions is to wait for basic networking to become
+available:
+
+    service nginx {
+        description = "High performance HTTP server"
+        conditions  = { "net/route/default" }
+        command     = "nginx"
+    }
+
+Here is another example where we instruct Finit to not start BusyBox
+`ntpd` until `syslogd` has started properly.  Finit waits for `syslogd`
+to create its PID file, by default `/var/run/syslogd.pid`.
+
+    service ntpd {
+        runlevel      = "2345"
+        conditions    = { "pid/syslogd" }
+        reload-signal = "none"
+        log { }
+        command       = "ntpd -n -N -p pool.ntp.org"
+    }
+
+    service syslogd {
+        description = "Syslog daemon"
+        runlevel    = "S12345"
+        command     = "syslogd -n"
+    }
+
+Notice the empty `log` block, BusyBox `ntpd` uses `stderr` for logging
+when run in the foreground.  With it Finit redirects `stdout` +
+`stderr` to the system log daemon using the command line `logger(1)`
+tool.
+
+A service, or task, can have multiple dependencies listed.  Here we wait
+for *both* `syslogd` to have started and basic networking to be up:
+
+    service ntpd {
+        runlevel   = "2345"
+        conditions = { "pid/syslogd", "net/route/default" }
+        log { }
+        command    = "ntpd -n -N -p pool.ntp.org"
+    }
+
+If either condition fails, e.g. loss of networking, `ntpd` is stopped
+and as soon as it comes back up again `ntpd` is restarted automatically.
+
+> [!NOTE]
+> Make sure daemons do *not* fork and detach themselves from the controlling
+> TTY, usually an `-n` or `-f` flag, or `-D` as in the case of OpenSSH above.
+> If it detaches itself, Finit cannot monitor it and will instead try to
+> restart it.
+
+[finit.conf(5)]: https://man.troglobit.com/man5/finit.conf.5.html
+[infix]:         https://kernelkit.github.io
+[myLinux]:       https://github.com/troglobit/myLinux/
+[contrib]:       https://github.com/finit-project/finit/tree/master/contrib

doc/extra.css

@@ -0,0 +1,11 @@
+.md-header__topic:first-child {
+    font-weight: 500;
+    font-style: italic;
+}
+
+.md-header__title {
+    font-size: 1.1rem;
+    font-style: italic;
+    font-weight: 500;
+    line-height: 2.6rem;
+}

doc/features.md

@@ -0,0 +1,334 @@
+Finit Features
+==============
+
+This page highlights some of Finit's key features with examples and usage
+scenarios. For complete documentation, configuration syntax, and advanced
+options, see the [Configuration](config/index.md) section.
+
+**Process Supervision**
+
+Start, monitor and restart services should they fail.
+
+
+**Getty**
+
+Finit supports external getty but also comes with a limited built-in
+Getty, useful for really small systems.  A getty sets up the TTY and
+waits for user input before handing over to `/bin/login`, which is
+responsible for handling the actual authentication.
+
+```conf
+tty tty1   { runlevel = "12345"  device = "/dev/tty1"     term = "linux"  nowait = true }
+tty ttyAMA0 { runlevel = "12345"  device = "/dev/ttyAMA0"  term = "vt100"  noclear = true }
+tty getty   { runlevel = "12345"  command = "/sbin/getty -L /dev/ttyAMA0 vt100" }
+```
+
+Users of embedded systems may want to enable automatic serial console
+with the special `@console` device.  This works regardless whether the
+system uses `ttyS0`, `ttyAMA0`, `ttyMXC0`, or anything else.  Finit
+figures it out by querying sysfs: `/sys/class/tty/console/active`.
+
+```conf
+tty console { runlevel = "12345"  device = "@console"  term = "linux"  noclear = true }
+```
+
+Notice the optional `noclear`, `nowait`, and `nologin` flags.  The
+latter is for skipping the login process entirely. For more information,
+see the [TTY and Consoles](config/tty.md) section.
+
+
+**Runlevels**
+
+Support for SysV init-style [runlevels][5] is available, in the same
+minimal style as everything else in Finit.  The `runlevel` setting
+applies to service, task, run, and tty blocks alike.
+
+Reserved runlevels are 0 and 6, halt and reboot, respectively just like
+SysV init.  Runlevel 1 can be configured freely, but is recommended to
+be kept as the system single-user runlevel since Finit will not start
+networking here.  The configured `runlevel` from `/etc/finit.conf`
+is what Finit changes to after bootstrap, unless 'single' (or 'S') is
+given on the kernel cmdline, in which case runlevel 1 is started.
+
+All services in runlevel S are started first, followed by the desired
+run-time runlevel.  Run tasks in runlevel S can be started in sequence
+by using a `run` block with `runlevel = "S"`.  Changing runlevels at
+runtime is done like any other init, e.g. <kbd>init 4</kbd>, but also
+using the more advanced [`initctl`](initctl.md) tool.
+
+
+**Conditions**
+
+As mentioned previously, Finit has an advanced dependency system to
+handle synchronization, called [conditions](conditions.md).  It can
+be used in many ways; depend on another service, network availability,
+etc.
+
+One *really cool* example useful for embedded systems is to run certain
+scripts if a board has a certain feature encoded in its device tree.  At
+bootstrap we run the following `ident` script:
+
+```sh
+#!/bin/sh
+conddir=/var/run/finit/cond/hw/model
+dtmodel=/sys/firmware/devicetree/base/model
+
+if ! test -e $dtmodel; then
+    exit 0
+fi
+
+model=$(cat $dtmodel | tr "[A-Z] " "[a-z]-")
+mkdir -p $conddir && ln -s ../../reconf $conddir/$model
+```
+
+Provided the device tree node exists, and is a string, we can then use
+the condition `<hw/model/foo>` when starting other scripts.  Here is an
+example:
+
+```
+run ident {
+    description = ""
+    runlevel    = "S"
+    command     = "/path/to/ident"
+}
+task foo-init {
+    description = "Initializing Foo board"
+    runlevel    = "2"
+    conditions  = { "hw/model/foo" }
+    command     = "/path/to/foo-init"
+}
+```
+
+> [!TIP]
+> Notice the trick with an empty description to hide the call to `ident`
+> in the Finit progress output.
+
+
+**Plugins**
+
+Plugins can *extend* the functionality of Finit and *hook into* the
+different stages of the boot process and at runtime.  Plugins are
+written in C and compiled into a dynamic library loaded automatically by
+finit at boot.  A basic set of plugins are bundled in the `plugins/`
+directory.
+
+Capabilities:
+
+- **Hooks**  
+  Hook into the boot at predefined points to extend Finit
+- **I/O**  
+  Listen to external events and control Finit behavior/services
+
+Extensions and functionality not purely related to what an `/sbin/init`
+needs to start a system are available as a set of plugins that either
+hook into the boot process or respond to various I/O.
+
+For more information, see the [Plugins](plugins.md) section.
+
+
+**Automatic Reload**{ #automatic-reload }
+
+By default, Finit monitors `/etc/finit.d/` and `/etc/finit.d/enabled/`
+registering any changes to `.conf` files.  To activate a change the user
+must call `initctl reload`, which reloads all modified files, stops any
+removed services, starts new ones, and restarts any modified ones.  If the
+command line arguments of a service have changed, the process will be
+terminated and then started again with the updated arguments. If the arguments
+have not been modified and the process supports SIGHUP, the process will
+receive a SIGHUP rather than being terminated and started.
+
+For some use-cases the extra step of calling `initctl reload` creates an
+unnecessary overhead, which can be removed at build-time using:
+
+    configure --enable-auto-reload
+
+
+**Linux Capabilities**
+
+Finit supports Linux capabilities, allowing services to run with minimal
+required privileges instead of running as root. This improves security by
+following the principle of least privilege.
+
+```conf
+service nginx {
+    runlevel     = "2345"
+    user         = "www-data"
+    group        = "www-data"
+    capabilities = { "^cap_net_bind_service" }
+    command      = "/usr/sbin/nginx -g 'daemon off;'"
+}
+```
+
+In this example, nginx runs as the unprivileged `www-data` user but retains
+the ability to bind to privileged ports (80, 443) through the
+`cap_net_bind_service` capability.
+
+The `capabilities` list uses the IAB (Inheritable, Ambient, Bounding) format:
+- `^` = Ambient (recommended) - capabilities survive exec()
+- `%` = Inheritable only - requires file capabilities
+- `!` = Bounding - block from acquiring capability
+
+Multiple capabilities can be specified as comma-separated:
+
+```conf
+capabilities = { "^cap_net_raw", "^cap_net_admin", "!cap_sys_admin" }
+```
+
+See the [Linux Capabilities](config/capabilities.md) section for detailed
+information, examples, and security best practices.
+
+
+**Supplementary Groups**
+
+Finit supports supplementary groups for services, allowing them to access
+resources owned by multiple groups without running as root. This complements
+capabilities for fine-grained privilege control.
+
+```conf
+service @caddy:caddy,ssl-cert /usr/bin/caddy run
+```
+
+In this example, the Caddy web server runs as user `caddy` with primary group
+`caddy`, but also has access to resources owned by the `ssl-cert` group (such
+as TLS certificates).
+
+Finit automatically reads the user's supplementary group membership from
+`/etc/group`. Additional groups can be specified explicitly using the syntax
+`@user:group,sup1,sup2,...`.
+
+See the [Non-privileged Services](config/services.md#non-privileged-services)
+section for more information.
+
+
+**Cgroups**
+
+Finit supports cgroups v2 and comes with the following default groups in
+which services and user sessions are placed in:
+
+     /sys/fs/cgroup
+       |-- init/               # cpu.weight:100
+       |-- system/             # cpu.weight:9800
+       `-- user/               # cpu.weight:100
+
+Finit itself and its helper scripts and services are placed in the
+top-level leaf-node group `init/`, which also is _reserved_.
+
+All run/task/service/sysv processes are placed in their own sub-group
+in `system/`.  The name of each sub-group is taken from the respective
+`.conf` file from `/etc/finit.d`.
+
+All getty/tty processes are placed in their own sub-group in `user/`.
+The name of each sub-group is taken from the username.
+
+A fourth group also exists, the `root` group.  It is also _reserved_ and
+primarily intended for RT tasks.  If you have RT tasks they need to be
+declared as such in their service block like this:
+
+    service foo {
+        cgroup root {}
+        command = "/path/to/foo args"
+    }
+
+Every block names the group it joins, so a second RT task says so too:
+
+    service bar {
+        cgroup root {}
+        command = "/path/to/bar args"
+    }
+
+See the [Cgroups](config/cgroups.md) section for more information, e.g.,
+how to configure per-group limits.
+
+The `initctl` tool has three commands to help debug and optimize the
+setup and monitoring of cgroups.  See the `ps`, `top`, and `cgroup`
+commands for details.
+
+> [!NOTE]
+> Systems that do not support cgroups, specifically version 2, are
+> automatically detected.  On such systems the above functionality is
+> disabled early at boot.
+
+
+**Service Management**
+
+Finit includes the `initctl` tool for managing services and system state at
+runtime. Key capabilities include:
+
+- **Enable/Disable services**: Manage which services start at boot by moving
+  configuration files between `/etc/finit.d/available` and
+  `/etc/finit.d/enabled`
+- **Start/Stop/Restart**: Control individual services without requiring a
+  full system reboot
+- **Status monitoring**: View service state, PID, uptime, and resource usage
+- **Condition management**: Set and clear user-defined conditions to control
+  service dependencies
+- **Cgroup monitoring**: Real-time process and resource monitoring with
+  `initctl top`, similar to the traditional `top` command but cgroup-aware
+
+Example commands:
+
+```bash
+initctl enable myservice          # Enable service for next boot
+initctl start myservice           # Start service now
+initctl status                    # Show all services
+initctl top                       # Interactive resource monitor
+initctl cond set usr/custom       # Set custom condition
+```
+
+`initctl` rides Finit's built-in [D-Bus API](dbus.md) when available,
+which is also open to any other bus client, including `dbus-send` and
+language bindings.
+
+See the [Commands & Status](initctl.md) section for complete documentation.
+
+
+**Rescue Mode**
+
+Finit provides a built-in rescue mode for system recovery and maintenance.
+When booting with the `rescue` kernel parameter, the system enters a
+protected maintenance shell.
+
+If the bundled `sulogin` program is available (from Finit, util-linux, or
+BusyBox), you'll be prompted for the root password before accessing the
+maintenance shell. This provides secure access for system recovery.
+
+If `sulogin` is not available, Finit falls back to reading
+`/lib/finit/rescue.conf` and boots the system in a limited maintenance mode.
+
+```
+# Kernel command line
+linux /vmlinuz root=/dev/sda1 rescue
+```
+
+In rescue mode, `initctl` will not work. After fixing the problem, use
+`reboot -f` to force reboot.
+
+Rescue mode can be disabled at build time with `configure --without-rescue`.
+
+See the [Rescue Mode](config/rescue.md) section for more information.
+
+
+**Switch Root**
+
+Finit supports switching from an initramfs to a real root filesystem using
+the built-in `initctl switch-root` command.  This allows Finit to serve as
+the init system in an initramfs for early boot tasks (LUKS unlock, LVM
+activation, network boot) before transitioning to the real root.
+
+```bash
+# In initramfs, after mounting the real root:
+initctl switch-root /mnt/root
+```
+
+The switch-root operation:
+
+1. Runs the `HOOK_SWITCH_ROOT` hook for cleanup
+2. Stops all services gracefully
+3. Moves virtual filesystems (`/dev`, `/proc`, `/sys`, `/run`) to the new root
+4. Deletes initramfs contents to free memory
+5. Pivots to the new root and execs the new init
+
+See the [Switch Root](switchroot.md) section for complete documentation.
+
+
+[5]: https://en.wikipedia.org/wiki/Runlevel