# Startup and shutdown

On a system with the system manager as process #1, startup and shutdown operate (in broad overview) as follows.

## System startup

1. `system-manager` performs process setup, a few inescapable items of system setup, starts the service manager and a logger for it, and enters the main system management state machine. It will restart the service manager and logger if they exit before system shutdown is initiated. The service manager process and its logger process are joined, standard output+error to standard input, via a pipe. The system manager keeps an open file descriptor for this pipe, so that its contents aren't lost in the event of a logger restart.

2. The initialization action of the system management state machine is to spawn a process that runs `system-control init arguments` where arguments are the arguments passed to the system manager itself at bootstrap. They will usually be flags such as `-b` or `-s`, to indicate "emergency" and "rescue" modes.

3. In normal mode, `system-control` simply sends `SIGRTMIN + 10` to process #1, followed by `SIGRTMIN + 0`. In rescue mode it sends `SIGRTMIN + 10`, followed by `SIGRTMIN + 1`. In emergency mode it sends just `SIGRTMIN + 2`.

4. In response to `SIGRTMIN + 10` the system management state machine spawns `system-control start sysinit`.

5. `system-control` activates the "sysinit" target. This is a special system target that is expected to bring up "sysinit" services, and encompasses targets such as "local-fs". After the target is started, the system is expected to have performed fundamental initialization tasks such as:

   - mounting `/usr` and `/var` (if necessary),

   - remounting `/` read-write,

   - ensuring that `/etc/machine-id` is set,

   - loading kernel modules for things like IPv6 and local-domain sockets,

   - squirrelling away the boot log somewhere,

   - initializing the dynamic library loader, and

   - bringing the system console TTY's line discipline into a "sane" state.

   Note: Fundamental initialization cannot rely upon a writable root filesystem or the presence of the filesystems that contain the bundle directories for "regular" services. So all "sysinit" services and targets have to have supervise directories under `/run/service-bundles/early-supervise/`. And this is a separate step from starting the "normal" target later, even though that indirectly encompasses the "sysinit" target and would thus be expected to start all this, because at this point the service/target ordering and dependency mechanism might not even find "regular" services. So the "sysinit" target has to be started explicitly first, just to make it possible to find and load all other "regular" services and targets.

6. In response to `SIGRTMIN + 0`, `SIGRTMIN + 1`, or `SIGRTMIN + 2` the system management state machine spawns `system-control start` with the `normal`, `rescue`, or `emergency` target respectively.

7. `system-control` activates the "normal", "rescue", or "emergency" targets, as if by `system-control start`. By now, `/usr` and `/var` are mounted, and the service/target ordering and dependency system will find all "regular" services and targets encompassed by these targets.

## System shutdown

1. The administrator runs `system-control halt`, `system-control poweroff`, `system-control reboot`, or some other utility.

2. The utility sends the appropriate signal to process #1. (On BSD, these are the same signals as issued by the BSD `shutdown` command, for compatibility with that command. On Linux, these are the systemd signals.)

   The administrator must have run `system-control` as the superuser in order to have permission to send signals to process #1.

3. In response to the signal the system management state machine spawns `system-control start target` where target is "halt", "reboot", or "poweroff".

   Caution: Do not run `system-control start target` directly. That does not work, as partway through it will end up terminating the very login session wherein the `system-control` process is running, and the change of state would be incomplete. The original `shutdown` utilities on NetBSD and elsewhere also have this problem that they enact state changes in-line, and if they are run from a login session that is terminated they end up transitioning the system to a state where shutdown is only partly complete. The indirection in this mechanism is precisely to ensure that the `system-control` process actually directing the state change is not under the umbrella of service management, but is a direct child process of the system manager.

4. `system-control` starts the named target.

   - All of these targets encompass the "shutdown" target, and as standard all "regular" services are marked as conflicting with that target (causing them to be stopped if it is started) and to be stopped before it is started.

   - All of these targets encompass the "unmount" target, and as standard all "mount@" services are marked as conflicting with that target (causing them to be stopped if it is started) and to be stopped before it is started.

5. The "halt", "reboot", and "poweroff" targets are finally started. They are ordered to be started after the "shutdown" and "unmount" targets have been started. Their `start` programs invoke `system-control halt --force`, `system-control poweroff --force`, or `system-control reboot --force`, as appropriate.

6. `system-control` sends a different signal to process #1. (These are the systemd signals on both BSD and Linux, as there is no BSD mechanism to be compatible with, here.)

7. In response to the signal the system management state machine attempts to terminate the service manager and its logger dæmon. All services should have been shut down already, but the service manager attempts to shut down all services that it manages when it is told to terminate. The logger dæmon is expected to close when it reaches EOF on the pipe that is attached to its standard input, which happens after the service manager process closes and the system manager (process #1) closes its open file descriptor for the write end of the pipe.

8. The system management state machine at last enters its final state, halting, rebooting, or powering off the machine directly with the appropriate system calls, after asking the kernel to flush the filesystem cache to disc.