fds-os/docs/power.md

Shutdown and reboot

Documentation index · DATA usage · Media tools

M10 software acceptance passed; see the validation report. Physical timing and durability targets remain unmeasured. Rebuild the rootfs to obtain these commands; images built before M10 do not contain them.

Normal use

At the ordinary FDS console:

fds poweroff
fds reboot

Use one command for the action you want. fds-power poweroff and fds-power reboot are equivalent static aliases. No root password or setuid executable is needed: the root cartridge daemon authenticates the local FDS user and performs the controlled operation.

Preparation freezes new cartridge operations, stops the desktop, stops managed PROGRAM/DATA jobs and their descendants, then stops networking and all DHCP children. It flushes DATA through the filesystem descriptor retained since activation, changes the filesystem to read-only, checks writeback again, and unmounts it normally. Other cartridges are unmounted next. Only after those steps succeed does native s6 stop remaining services and request kernel halt or reboot. Dasung remains part of the base service set until that final service stop.

The read-only transition prevents new writes while the error-tracking descriptor is closed for unmount. An open writer blocks that transition. A working directory or unexpected additional mount can block unmount. No lazy unmount is used to turn a busy or faulty cartridge into a successful shutdown.

If shutdown is blocked

The machine stays running and the command reports the cause. Inspect it with:

fds power status
fds --json power status

The JSON response includes the current phase, requested action, error, whether native shutdown has begun, and actual CLOCK_BOOTTIME timestamps for preparation steps. It is a software diagnostic, not a physical power-off measurement.

Common cases:

Reported problem	What to do
Active media operation	Let an existing write finish, or use fds burn cancel OPERATION_ID. A preview awaiting confirmation must be cancelled. New confirmations are refused while shutdown is frozen. Then retry shutdown.
Busy DATA filesystem	Close files and programs that were started outside FDS management. Leave /data in every shell with cd /. Remove any extra mounts you deliberately created. Then retry shutdown.
DATA I/O error or interrupted session	Do not interpret this as SAFE. Inspect the read-only data and recover/check the cartridge in a maintenance environment before writable use. Restarting the daemon does not clear this fault.
Service transition failure	Inspect the corresponding volatile service logs under /run/log, resolve the failure, and retry.

If native shutdown has not begun, you can abandon preparation:

fds power resume

This enables new cartridge operations again. It does not restart stopped jobs. Start the desktop or network explicitly when needed, using fds profile activate windowmaker and fds network on. DATA faults remain quarantined.

If native shutdown has already begun, it cannot be cancelled. Its guard remains alive while preparation is blocked. Resolve the cause, leave busy directories, then retry fds poweroff to complete preparation; the original native action continues. This also protects direct administrative use of the native poweroff or reboot commands. The final native hook never treats an unsuccessful preparation command as permission to kill processes and power down.

Flushing real storage may take time. A client timeout is an error, never proof that a filesystem was unmounted or a request completed. There is no automatic force-poweroff path after a timeout.

DATA recovery records

Before enabling writable DATA, FDS creates a root-owned session record under /run/fds/data-sessions. Successful sync and unmount clear it. A daemon crash can lose the original descriptor's writeback error history; a remaining record therefore quarantines the same kernel insertion even if a later flush appears successful. A known I/O fault is also recorded there.

The record survives daemon restarts during this boot. It is tied to the kernel insertion identity and does not pretend to survive complete power loss or a new insertion. Filesystem recovery and physical durability still require separate acceptance. Shutdown preparation itself is recorded under /run/fds/power, so restarting the daemon does not silently unfreeze a blocked shutdown.

Build and virtual tests

After the boot-image prerequisites, run on the build host:

make rootfs PROFILE=development
make rootfs-test
make media-image-test
make power-test
make data-test
make desktop-test

The development profile supplies Xvfb for the graphical shutdown case. The tests use private ARM virtual machines and disposable image files, with no physical disks or USB devices passed through. They exercise native halt/reboot, busy refusal, explicit resume, active-write protection, daemon crashes, and independent filesystem/payload checks, plus an attached-device writeback EIO that must survive daemon restarts. M11 extends media-writer fault injection and twelve-device stress. Physical Pi timing, power rails, battery and flash-controller behavior remain deferred.

Dependencies and native init behavior

No new package or external Rust crate is introduced. fds-init explicitly depends on fds-cartridged because native shutdown requires its DATA checks. The CLI now declares the already-locked libc crate directly for its native shutdown guard's identity, inotify and signal-wait syscalls. DHCP children use the existing cgroup v2 controller and native FDS helpers. fds-power is another static copy of fds, with behavior selected by its executable name.

Native s6 still owns shutdown and PID 1. Its configurable final grace period is set to zero after FDS has verified DATA and the service manager has waited for managed service exits. Process groups use real exit events and bounded TERM/KILL deadlines, rather than sleeping before assuming a process has stopped.

References: s6 shutdown, native init configuration, Linux remount behavior, and filesystem error reporting.