diff --git a/doc/features.md b/doc/features.md index 4046912d..51fea9e7 100644 --- a/doc/features.md +++ b/doc/features.md @@ -1,6 +1,10 @@ Finit Features ============== +This page highlights some of Finit's key features with examples and usage +scenarios. For complete documentation, configuration syntax, and advanced +options, see the [Configuration](config/index.md) section. + **Process Supervision** Start, monitor and restart services should they fail. @@ -162,6 +166,28 @@ See the [Linux Capabilities](config/capabilities.md) section for detailed information, examples, and security best practices. +**Supplementary Groups** + +Finit supports supplementary groups for services, allowing them to access +resources owned by multiple groups without running as root. This complements +capabilities for fine-grained privilege control. + +```conf +service @caddy:caddy,ssl-cert /usr/bin/caddy run +``` + +In this example, the Caddy web server runs as user `caddy` with primary group +`caddy`, but also has access to resources owned by the `ssl-cert` group (such +as TLS certificates). + +Finit automatically reads the user's supplementary group membership from +`/etc/group`. Additional groups can be specified explicitly using the syntax +`@user:group,sup1,sup2,...`. + +See the [Non-privileged Services](config/services.md#non-privileged-services) +section for more information. + + **Cgroups** Finit supports cgroups v2 and comes with the following default groups in @@ -207,4 +233,59 @@ commands for details. > disabled early at boot. +**Service Management** + +Finit includes the `initctl` tool for managing services and system state at +runtime. Key capabilities include: + +- **Enable/Disable services**: Manage which services start at boot by moving + configuration files between `/etc/finit.d/available` and + `/etc/finit.d/enabled` +- **Start/Stop/Restart**: Control individual services without requiring a + full system reboot +- **Status monitoring**: View service state, PID, uptime, and resource usage +- **Condition management**: Set and clear user-defined conditions to control + service dependencies +- **Cgroup monitoring**: Real-time process and resource monitoring with + `initctl top`, similar to the traditional `top` command but cgroup-aware + +Example commands: + +```bash +initctl enable myservice # Enable service for next boot +initctl start myservice # Start service now +initctl status # Show all services +initctl top # Interactive resource monitor +initctl cond set usr/custom # Set custom condition +``` + +See the [Commands & Status](initctl.md) section for complete documentation. + + +**Rescue Mode** + +Finit provides a built-in rescue mode for system recovery and maintenance. +When booting with the `rescue` kernel parameter, the system enters a +protected maintenance shell. + +If the bundled `sulogin` program is available (from Finit, util-linux, or +BusyBox), you'll be prompted for the root password before accessing the +maintenance shell. This provides secure access for system recovery. + +If `sulogin` is not available, Finit falls back to reading +`/lib/finit/rescue.conf` and boots the system in a limited maintenance mode. + +``` +# Kernel command line +linux /vmlinuz root=/dev/sda1 rescue +``` + +In rescue mode, `initctl` will not work. After fixing the problem, use +`reboot -f` to force reboot. + +Rescue mode can be disabled at build time with `configure --without-rescue`. + +See the [Rescue Mode](config/rescue.md) section for more information. + + [5]: https://en.wikipedia.org/wiki/Runlevel diff --git a/doc/index.md b/doc/index.md index 33e03a87..4e4f7481 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,7 +1,7 @@ Introduction ============ -![Alpine screenshot](img/alpine-screenshot2.png){ align=right } +![Alpine screenshot](img/alpine-screenshot2.png){ align=right width=40% } > Reverse engineered from the [EeePC fastinit][] > "gaps filled with frog DNA …" @@ -17,26 +17,30 @@ PID file monitoring, or [conditions](conditions.md). Features -------- - * [Runlevels][5], defined per service - * One-shot tasks, services (daemons), or [SysV init][4] start/stop scripts - * Runparts and `/etc/rc.local` support + * [Runlevels](config/runlevels.md), defined per service + * [One-shot tasks](config/task-and-run.md), [services](config/services.md) (daemons), or [SysV init][4] start/stop scripts + * [Runparts](config/runparts.md) and `/etc/rc.local` support * Process supervision similar to [systemd][] - * Sourcing environment files - * Conditions for network/process/custom dependencies - * Readiness notification; PID files (native) for synchronizing system + * Fine-grained privilege control: + - [Linux capabilities](config/capabilities.md) for minimal required privileges + - [Supplementary groups](config/services.md#non-privileged-services) for multi-group resource access + * [Sourcing environment files](config/service-env.md) + * [Conditions](conditions.md) for network/process/custom dependencies + * [Readiness notification](config/service-sync.md); PID files (native) for synchronizing system startup, support for systemd [sd_notify()][], or [s6 style][] too * Limited support for [tmpfiles.d(5)][] (no aging, attributes, or subvolumes) - * Pre/Post script actions + * [Pre/Post script actions](config/service-wrappers.md) * Rudimentary [templating support](config/templating.md) - * Tooling to enable/disable services - * Built-in getty + * [Tooling](initctl.md) to enable/disable services + * [Automatic reload](features.md#automatic-reload) of modified configuration files (optional) + * [Built-in getty](config/tty.md) * Built-in watchdog, with support for hand-over to [watchdogd][] * Built-in support for Debian/BusyBox [`/etc/network/interfaces`][3] - * Cgroups v2, both configuration and monitoring in `initctl top` - * Plugin support for customization - * Proper rescue mode with bundled `sulogin` for protected maintenance shell + * [Cgroups v2](config/cgroups.md), both configuration and monitoring in [`initctl top`](initctl.md) + * [Plugin support](plugins.md) for customization + * Proper [rescue mode](config/rescue.md) with bundled `sulogin` for protected maintenance shell * Integration with [watchdogd][] for full system supervision - * Logging to kernel ring buffer before `syslogd` has started, see the + * [Logging](config/logging.md) to kernel ring buffer before `syslogd` has started, see the recommended [sysklogd][] project for complete logging integration and how to log to the kernel ring buffer from scripts using `logger` @@ -64,6 +68,7 @@ and proposed extensions. [4]: https://en.wikipedia.org/wiki/Init [5]: https://en.wikipedia.org/wiki/Runlevel [6]: https://github.com/finit-project/finit +[dinit]: https://davmac.org/projects/dinit/ [systemd]: https://www.freedesktop.org/wiki/Software/systemd/ [sd_notify()]: https://www.freedesktop.org/software/systemd/man/sd_notify.html [s6 style]: https://skarnet.org/software/s6/notifywhenup.html