Sysgraph

Sysgraph manages system states and services as a state graph. It is a generalization of the concepts of init systems like OpenRC and systemd, and supervisors like daemontools and runit. The core idea is to provide the control flow for stateful, scriptable functionality, and make as little assumptions as possible in the process.

Overview

States and services are represented as a node in a graph. The behavior and topology of the graph is defined in a config directory, which can be read-only for operation. Nodes can be up, down, or in a number of transition states. At its simplest, a node is a subdirectory of the config dir. Each node can have, among others, a start and stop script for state transitions, a run script for long running processes. Different kinds of dependencies can be declared as edges between the nodes. Nodes can also act as listeners in a simple publish-subscribe based event system.

As an example to convey the idea, sysgraph can be used to complement or replace the following components with simple scripts:

Init system, sysgraph can, but does not have to run as PID 1
Service supervisor, using nodes with run scripts that set up the environment, then exec into the service executable
fstab, using nodes that mount in the start script, umount in the stop script, and possibly run periodic health checks
udev, ACPI event handling, automounting, using event adapters and nodes with event handlers
network interface management, using nodes with ip dev calls in start and stop scripts, and a DHCP client in the run script
Cron daemon, using nodes that subscribe to periodic events

Miscellaneous Selling Points

Sysgraph is fast and lightweight. The core daemon sgd currently has ca. 2500 lines of C code.
Using service supervision and health checks, sysgraph is acutely aware of the current state of the system, and very insistent on reaching the goal state. An isolated service crash will not ruin your day.
sgd is engineered to be rock-solid. Development follows strict rules based on the NASA JPL "Power of 10", documented in the coding guidelines. sgd is guaranteed to always stay responsive and never hang, and a lot of thought has been put into making sure it never crashes.

Requirements

Build requirements:

ISO C99 compiler (tested with gcc, clang, tcc)
POSIX.1-2008 compatible libc, such as glibc or musl
GNU make

Runtime requirements:

POSIX.1-2008 compatible shell and environment, busybox is enough
Some specific features require the config dir to be on a filesystem that can distinguish between executable and non-executable files.
sgd acquires a lock file inside the state dir to prevent user error. Behavior on a filesystem that does not (correctly) implement POSIX advisory file locking is untested.

Testing requirements:

Bash
busybox (static)
bubblewrap (optional)

Requirements for automated QA checks:

Build requirements
gcc and clang (both are used for more thorough error checking)
clang-tidy
cppcheck
shellcheck
git

Building

Build settings and install paths to override can be found at the start of common.mk. DESTDIR is supported.

Build: make

Install: make install for a system-wide installation, make install-user to just install the executables into ~/.local/bin/. Fine-grained install targets are found in Makefile.

Documentation

The documentation can be found here.

Recommended Software

The following software is particularly useful when working with sysgraph:

Sysgraph config directories work very well with version control, especially if the service config files are placed inside the node dirs.
Having multiple machines sync a config dir from a server, e.g. with rsync, can serve as a simple form of orchestration that integrates well with version control.
With squashfs and squashfuse, a config dir can be distributed as a single file, protected against modification.

Some particularly useful helpers for writing scripts are listed in the documentation overview.

State of Development

While sgd has been designed with PID 1 capabilities in mind, a lot of the scaffolding necessary to actually boot and power down a system is still missing.

The current roadmap of issues and features can be found in the todo/ directory.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.