How plasticgaming99/vigilante works
1. What this repo is
- vigilante is a Linux init system written in V. The main binary is the init daemon itself, intended to run as PID 1 and manage boot targets and services.
- The architecture is split into the daemon, a small control client (vigctl), parsing/configuration, service lifecycle management, and low-level Linux syscall bindings.
2. Top-level control flow
- Startup begins in main.v, which likely initializes logging, signal handling, service state, and the event loop.
- From there, the daemon loads a target/service definition, builds the dependency order, starts required units, and then stays resident to react to process exits, signals, and control requests.
3. Configuration and unit model
- Unit files are TOML-like and define [info], [service], and [mount] sections.
- The service model supports several execution modes: process, fork, oneshot, and internal.
- Units can express ordering and dependency relationships such as after, before, depends_on, depends_ms, and waits_for, plus mount metadata like target path, filesystem type, options, and read/write requirements.
4. Parser and unit loading
- parse.v is the configuration ingestion layer. It turns unit files from defaulttargets/ and testfiles/ into internal service/target structures.
- This is the boundary between declarative boot definitions and the imperative service manager logic.
5. Service management core
- service_ss.v appears to contain the service state machine and orchestration logic: starting, tracking, and stopping units, and enforcing dependency/order constraints.
- This is where target semantics like default.target, multi-user.target, networking.target, recovery.target, and shutdown targets are likely composed into a boot graph.
6. Event-driven runtime
- quickev/ is a lightweight event loop used by the daemon to multiplex process and system events.
- The syscall/event_linux.c.v and related wrappers suggest the event loop is backed by Linux primitives rather than a higher-level runtime, which fits an init system that must remain small and deterministic.
7. Linux boundary and system integration
- syscall/ contains the low-level Linux interface layer: wrappers for syscalls, sockets, and event handling.
- This is the repo’s main OS boundary: process creation, waiting, signals, filesystem mounts, and IPC are all mediated here instead of through external libraries.
8. Signals and process lifecycle
- sighandlers.v handles process-level signals delivered to init.
- In an init system, signals are part of the control plane: they typically drive reload, shutdown, poweroff, reboot, or emergency/recovery transitions, and they must integrate with the service state machine.
9. Boot targets and packaged defaults
- defaulttargets/ contains built-in boot units such as dbus.service, agetty.service, dhcpcd.service, graphical.target, multi-user.target, networking.target, poweroff.target, and reboot.target.
- This shows the intended architecture is target-based: the system boots by selecting a target, and targets pull in the services needed for that mode.
10. Control utility
- vigctl/ is a separate client tool used to interact with the init daemon.
- The presence of shared structs in vigctl/lib/struct.v and socket-related syscall wrappers strongly suggests a local IPC boundary between the CLI and PID 1, likely for service control and status queries.
11. Logging and observability
- log.v is the repository’s internal logging layer.
- For an init system, logging is part of the core control path because early boot failures and service transitions need to be observable even before user space is fully up.
12. Testing and examples
- testfiles/ provides sample units and targets, while testprogs/testsvc1sec provides a small service program used to exercise startup, timing, or dependency behavior.
- These files are important for understanding the architecture because they reflect the supported unit types, ordering rules, and boot scenarios the daemon is designed to handle.
Main entry points: main.v Init main · service_ss.v Service state · default.target Default targets · parse.v Unit parser
Components 19
Init daemon
PID 1 runtime, orchestration, and boot control.
- Init main · Starts the init daemon, wires core runtime pieces, and enters the main loop.
main.v - Service state · Service and target state machine for starting, stopping, ordering, and dependency handling.
service_ss.v - Unit parser · Loads and interprets unit files into internal service and target structures.
parse.v - Signal handlers · Handles init-level signals that drive shutdown, reload, recovery, and other transitions.
sighandlers.v - Logging · Internal logging used across boot, service transitions, and failure reporting.
log.v - Event loop · Lightweight event dispatcher used to multiplex process and system activity.
quickev/quickev_linux.c.v
Linux boundary
Low-level syscall and event integration.
- Syscalls · Core syscall wrappers for process, filesystem, IPC, and other kernel interactions.
syscall/syscall.c.v - Linux syscalls · Linux-specific syscall bindings and platform glue.
syscall/syscall_linux.c.v - Event backend · Linux event primitives backing the daemon's event loop.
syscall/event_linux.c.v - Socket IPC · Socket-related Linux bindings used for daemon and client communication.
syscall/socket_linux.c.v
Control client
User-facing control utility and shared IPC structs.
- vigctl · Command-line client for querying and controlling the init daemon.
vigctl/main.v - IPC structs · Shared data structures used by the client side of daemon communication.
vigctl/lib/struct.v
Boot units
Packaged defaults and sample unit definitions.
- Default targets · Built-in boot targets and services such as default, multi-user, graphical, networking, reboot, and poweroff.
defaulttargets/default.target - Multi-user · Representative target for standard multi-user boot composition.
defaulttargets/multi-user.target - Graphical · Representative target for graphical boot composition.
defaulttargets/graphical.target - Networking · Representative packaged service for bringing up network connectivity.
defaulttargets/networking.target - Shutdown targets · Representative poweroff and reboot targets for machine transition control.
defaulttargets/poweroff.target
Test assets
Support programs and test unit files.
- Test units · Example service, mount, and target files used to exercise parsing and ordering behavior.
testfiles/default.target - Test service · Small sample service program used to validate service startup and timing behavior.
testprogs/testsvc1sec/testsvc1sec.v
Connections 21
- Init main → Unit parser: loads units · Startup reads unit definitions and target graphs.
- Init main → Service state: drives lifecycle · Main runtime hands execution to the service state machine.
- Init main → Event loop: runs on · Daemon stays resident in the event loop.
- Init main → Signal handlers: installs · Process-level signals are wired into init control flow.
- Init main → Logging: logs through · Boot and service activity are reported via internal logging.
- Service state → Unit parser: consumes · Service orchestration operates on parsed unit definitions.
- Service state → Event loop: reacts to events · State machine responds to process exits and runtime events.
- Service state → Signal handlers: receives control · Signals trigger shutdown and recovery transitions.
- Service state → Default targets: composes · Built-in targets and services define boot compositions.
- Unit parser → Test units: parses · Sample unit files exercise the configuration boundary.
- Event loop → Event backend: backs onto · Event loop is implemented with Linux event primitives.
- Event backend → Linux syscalls: uses · Event backend depends on Linux-specific syscall bindings.
- Socket IPC → Linux syscalls: uses · Socket IPC is built on Linux syscall wrappers.
- Linux syscalls → Syscalls: extends · Linux-specific layer builds on shared syscall wrappers.
- vigctl → Socket IPC: communicates via · Control client reaches PID 1 over local IPC.
- vigctl → IPC structs: shares schema · Client and daemon exchange common request/response structures.
- Default targets → Multi-user: includes · Representative target unit in the packaged defaults.
- Default targets → Graphical: includes · Representative graphical boot target.
- Default targets → Networking: includes · Representative networking service or target.
- Default targets → Shutdown targets: includes · Representative shutdown and reboot targets.
- Test units → Test service: exercises · Test service binary is used by sample unit definitions.