boot-oneshots.d — package-provided stage-1 oneshots
===================================================

Under native runit boot (/etc/runit/native.boot.run, from runit-init),
stage 1 sources /etc/runit/boot-run/*.sh in lexical order (each file is
dotted in, not run in a subshell — use return, not exit).  runit-init
ships 00, 05, 10, and 99; other packages add their own NN-*.sh hooks
only when installed (see README-flagfiles, native.boot.run).

At step 05, each executable in /etc/runit/boot-oneshots.d/ is run in
lexical order:

  /etc/runit/boot-oneshots.d/NN-servicename

NN is two digits (boot order).  Packages ship these as symlinks:

  /etc/sv/<servicename>/run  →  /etc/runit/boot-oneshots.d/NN-<servicename>

All stage-1 oneshots MUST ship a static ./down so runsv never auto-starts
them when linked under runsvdir.

Shebangs
--------

  /etc/sv/<name>/run  (and finish, when present):

    #!/usr/bin/env /lib/runit/invoke-run

    Debian/dh-runit convention.  Loads /etc/default/<name>, optional
    env/, .meta checks, and (under native.boot.run) puts stage1/sv on
    PATH.  05 runs these via "sv once" or "(cd /etc/sv/<name> && ./run)"
    so PWD is the service directory — required by invoke-run.

  /etc/runit/boot-run/*.sh:

    Do NOT use invoke-run.  Stage 1 sources these files (. "$f"); they
    are not supervised runscripts.  Use #!/bin/sh (or no shebang) and
    return, never exit.

Two shutdown patterns (both valid; tree uses both as examples)
--------------------------------------------------------------

1) exit + *-stop  (networking, cryptdisks, urandom, resolvconf, …)
   - ./run does work and exits (any status → still end cleanly)
   - static ./down keeps the service down after "sv once" (stage 1)
   - companion /etc/sv/<name>-stop does cleanup at stage 3 via
     /etc/runit/shutdown-oneshots.d/ (see shutdown-oneshots.d.txt)

2) pause + ./finish  (fake-hwclock — illustrative for stage 1)
   - linked in runsvdir WITH static ./down
   - stage 1 uses "sv once" (05 detects the default link)
   - ./run ends with: exec sv -v pause .
     (also after failure — only one attempt)
   - on shutdown, runsv downs the service → ./finish runs cleanup
   - no <name>-stop oneshot

Number ranges (policy — keep gaps for local admin 9x):

  00–09  early mounts / kernel fs, live-config
                                           (initscripts 01–02; live-config 05)
  10–19  hostname, hwclock, keyboard       (initscripts, fake-hwclock,
                                           console-setup-linux)
  20–29  checkroot, cryptsetup             (initscripts, cryptsetup)
  30–39  modules, fsck, mountall           (initscripts)
  40–49  urandom, procps, sysusers, …      (initscripts, procps, …)
  50–59  nfs / remaining net helpers       (initscripts; networking and
                                           resolvconf are stage 2)
  60–69  bootmisc, console, sudo
  90–99  rc.local / local admin

Stage-2 oneshots (not in boot-oneshots.d)
-----------------------------------------

Services that need devices from vdev (or may run after stage-1 mounts)
live under runsvdir waves — typically 02-base — without a boot-oneshots.d
entry and WITHOUT a static ./down (runsv starts them when the wave
merges; they are not invoked via boot-oneshots / sv once from stage 1).

Two models:

  exit + finish + *-stop: finish downs after ./run so runsv does not
    restart the oneshot; stage 3 runs <name>-stop from
    shutdown-oneshots.d.  Examples: x11-common, rmnologin, networking,
    resolvconf, alsa-utils.

  pause + finish: ./run ends in "sv pause"; finish on force-stop at
    stage 3 — no *-stop.  Example: brightness.

Do not list these in tier .needs (oneshots finish/down). Optional
longruns (dbus, ubus, elogind) are also omitted from shipped .needs.
