| lainos-layer02-user-guide.md | ||
| README.md | ||
lainOS layer 02
A systemd-free Arch Linux derivative built with OpenRC as PID 1, offering full ABI compatibility for systemd-linked software via the Protocol 7 compatibility architecture.
Table of Contents
- Overview
- Architecture
- Key Features
- System Requirements
- Building
- Installation
- Session Types
- Protocol 7 Compatibility Layer
- System Hardening
- Network Configuration
- lainos-utils
- Troubleshooting
- Project Structure
- Contributing
- License
- Acknowledgments
Overview
lainOS layer 02 is a research project. It not a security distribution, and do not treat it as such. It is a daily driver that aims to strike a balance between usability, privacy, and security, and includes security and privacy hardening to reach that goal.
LainOS Layer 02 is a custom Arch Linux-based distribution built on a clean Arch base using archiso. It replaces systemd with OpenRC as PID 1, while maintaining ABI compatibility with software that dynamically links against systemd's client libraries through the Protocol 7 compatibility layer.
The entire OpenRC stack is self-hosted ~ no Artix repositories are used. All OpenRC service scripts, compatibility packages, and custom daemons are maintained in the Protocol 7 repository.
This is not merely a themed Arch respin ~ it is a genuine init-system replacement project with custom C daemons handling responsibilities that systemd would otherwise own.
Architecture
| Layer | Component | Role |
|---|---|---|
| Boot | GRUB/Syslinux/EFI ~ Dracut | UEFI/BIOS boot, initramfs with dmsquash-live and LUKS support |
| Init | /sbin/openrc-init |
PID 1, explicit kernel cmdline |
| Live Session | greetd + tuigreet |
TUI login manager on TTY1 |
| Wayland | Sway + i3status-rs | Tiling compositor, autotiling, themed status bar |
| Installer | Calamares | Graphical system installer (autolaunches on liveuser login) |
| Compatibility | protocol7-core |
systemd ABI surface, D-Bus facade, session management |
Boot Chain
BIOS/UEFI ~ GRUB/Syslinux ~ kernel + initramfs
~ Dracut: dmsquash-live mounts squashfs, execs /sbin/openrc-init
~ OpenRC sysinit: dbus, lainos-notifyd, lainos-machine-id
~ OpenRC boot: cgroup-delegate, lainos-ghost-units, syslog-ng
~ OpenRC default: seatd, lainos-dbus-bridge, iwd, greetd, chrony, nftables, acpid, polkit
~ greetd ~ tuigreet ~ Sway session
~ lainos-session-sway ~ lainos-init ~ Sway
Key Features
System
- systemd-free ~ OpenRC as PID 1 with no systemd binary present
- Protocol 7 ~ Custom compatibility layer providing
libsystemd.so.0ABI via real systemd-libs (not mocks) - Self-hosted OpenRC stack ~ all OpenRC packages maintained in protocol_7_repo, no Artix dependency
- Live ISO ~ Fully bootable live environment with Calamares installer (autolaunches on login)
- Dracut initramfs ~ Modern initramfs with live boot and LUKS/crypt support
- BTRFS by default ~ with separate ext4 /boot for GRUB compatibility
Desktop (Sway/Wayland)
- Sway 1.12+ tiling compositor with custom keybindings
- i3status-rs themed status bar
- wofi application launcher
- alacritty terminal emulator
- dunst notification daemon
- swaybg static wallpaper
- Autotiling automatic window tiling
- Powerlevel10k zsh prompt
- CoplandOS-GTK dark theme with StarLabs cursor
- wlogout session/power menu (shutdown, reboot, suspend, lock, logout)
- swaylock screen locker with wallpaper background
- gnome-keyring secrets service backend for Electron apps
- PipeWire audio via
lainos-audio-initoptional package
System Hardening
- Protocol 7 Core fuzz tested ~ dfuzzer 2.6 full interface PASS, AddressSanitizer PASS, libFuzzer 2M iterations PASS
- hardened_malloc (GrapheneOS, light variant) preloaded for: alacritty, element, gnome-keyring-daemon, keepassxc, kleopatra, mpv, tor
- Kernel memory hardening ~
init_on_alloc=1,init_on_free=1,page_alloc.shuffle=1 - Full ASLR ~
randomize_va_space=2 - ptrace restricted ~
yama.ptrace_scope=1 - kexec disabled ~
kexec_load_disabled=1 - Unprivileged user namespaces disabled ~
unprivileged_userns_clone=0 - Core dumps disabled
- IPv6 disabled by default (prevents VPN leaks)
- SYN flood protection, ICMP redirect rejection, reverse path filtering
- Kernel pointer restriction (
kptr_restrict=2) - dmesg restricted to root only
- Magic SysRq disabled
- CPU RNG not unconditionally trusted (
random.trust_cpu=off) - Ephemeral machine-id ~ regenerated on every boot
- iwd MAC randomization ~ new MAC address per boot
- nftables firewall ~ default-deny with established/related allowed
- yescrypt password hashing
- doas instead of sudo (minimal attack surface)
- LUKS full disk encryption ~ opt-in at install, confirmed working
- Signed package repositories ~ SigLevel = Required, full trust chain via lainos-keyring
Networking
- iwd for WiFi
- dhcpcd + openresolv for wired DHCP
- chrony for NTP time synchronization
- nftables for firewall management
- No NetworkManager, no systemd-networkd, no systemd-resolved
System Requirements
Minimum
- 64-bit x86_64 processor
- 2 GB RAM
- 4 GB USB drive or free disk space
- UEFI or BIOS boot support
Recommended
- 4+ GB RAM
- GPU with Mesa drivers (Intel/AMD recommended; software rendering fallback available)
- USB 3.0 for live boot
Tested Hardware
- QEMU/KVM with Virtio GPU (primary development environment)
- ThinkPad T480 (Libreboot) ~ baremetal confirmed working, UEFI and BIOS, including LUKS FDE
Building
Prerequisites
Build Host: LainOS Layer 02 or Arch Linux with Protocol 7 repository configured
Required packages:
doas pacman -S archiso base-devel git
Build Steps
- Clone the repository:
git clone https://forgejo.lain.rocks/lainOS/lainos-iso-layer-02.git
cd lainos-iso-layer-02
- Build the ISO:
doas rm -rf ~/lainos-work ~/lainos-out
mkdir -p ~/lainos-work ~/lainos-out
yes "" | doas mkarchiso -v -w ~/lainos-work -o ~/lainos-out protocol7-profile 2>&1 | tee ~/lainos-build.log
- Hash the ISO:
lainos-hash-iso
The resulting ISO will be at ~/lainos-out/lainOS-layer-02-YYYY.MM.DD-x86_64.iso.
Protocol 7 Repository
All packages are self-hosted in protocol_7_repo. All packages and databases are signed with the LainOS maintainer PGP key. Current package list:
| Package | Purpose |
|---|---|
protocol7-core |
Core compatibility layer, init scripts, C daemons |
protocol7-core-runit |
Runit variant of Protocol 7 |
lainos-audio-init |
Optional PipeWire audio orchestration (split from protocol7-core) |
lainos-keyring |
LainOS PGP public key for pacman verification |
openrc |
Init system and service manager |
libeinfo |
OpenRC info library |
eudev |
Genuine udev implementation |
libudev |
libudev ABI compatibility |
systemd |
Dummy ~ satisfies pacman dependencies, no files |
systemd-sysvcompat |
Dummy ~ blocks real sysvcompat |
elogind |
Dummy ~ blocks real elogind |
mkinitcpio |
Dummy ~ blocks real mkinitcpio |
sudo |
Dummy ~ blocks real sudo (doas is used instead) |
netifrc |
Network interface configuration |
dbus-openrc |
OpenRC service for D-Bus |
acpid-openrc |
OpenRC service for acpid |
chrony-openrc |
OpenRC service for chrony |
dhcpcd-openrc |
OpenRC service for dhcpcd |
greetd-openrc |
OpenRC service for greetd |
iwd-openrc |
OpenRC service for iwd |
nftables-openrc |
OpenRC service for nftables |
seatd-openrc |
OpenRC service for seatd |
syslog-ng-openrc |
OpenRC service for syslog-ng |
tor-openrc |
OpenRC service for tor |
lainos-hardened-malloc |
GrapheneOS hardened_malloc, light variant |
lainos-kvm |
KVM/QEMU virtualization ~ OpenRC init scripts, default NAT network, opt-in lainos-kvm-enable-firewall script |
lainos-utils |
LainOS utility scripts |
lainos-calamares-dracut |
Calamares binary (services-openrc enabled) |
lainos-calamares-config-layer-02 |
Calamares configuration and branding |
Deploying packages to the repo
cp <package>.pkg.tar.zst ~/Gitlab/protocol_7_repo/x86_64/
cd ~/Gitlab/protocol_7_repo/x86_64/
bash lainos-repo-push
The lainos-repo-push script signs all unsigned packages, rebuilds the signed database, removes symlinks for GitLab compatibility, and pushes.
Installation
Live Boot
- Write the ISO to a USB drive:
doas dd if=~/lainos-out/lainOS-layer-02-*.iso of=/dev/sdX bs=4M status=progress
-
Boot from USB and select LainOS Layer 02 from the bootloader.
-
At the
tuigreetlogin screen, login asliveuser(no password required). Calamares launches automatically.
Installing to Disk
Calamares launches automatically on liveuser login. If it doesn't appear, run:
calamares_polkit
Follow the installer wizard. To enable full disk encryption, select Encrypt system on the partition screen. LUKS unlock at boot is handled by dracut's crypt module ~ no systemd-cryptsetup required.
Note on filesystem: BTRFS is the default. A separate 1GB ext4 /boot partition is created automatically for GRUB compatibility.
Post-Install Notes
- WiFi: use the
wificommand oriwctl - Privilege escalation:
doas(not sudo) - Power menu:
wlogout - Lid close: automatically locks screen with swaylock and suspends
- Audio: install
lainos-audio-initfor PipeWire support (doas pacman -S lainos-audio-init)
Session Types
Sway (Wayland)
LainOS Layer 02 is a Wayland-only distribution. The desktop is Sway with i3status-rs.
Keybindings:
| Key | Action |
|---|---|
Mod4+Return |
Open terminal (alacritty + tmux) |
Mod4+Space |
Open application launcher (wofi) |
Mod4+Shift+q |
Close focused window |
Mod4+1-9 |
Switch to workspace |
Mod4+Shift+1-9 |
Move window to workspace |
Mod4+h/j/k/l |
Focus left/down/up/right |
Mod4+Shift+h/j/k/l |
Move window left/down/up/right |
Mod4+w |
Open LibreWolf |
Mod4+f |
Open Thunar |
Protocol 7 Compatibility Layer
Protocol 7 is the architectural foundation that enables systemd-free operation while maintaining compatibility with software expecting systemd interfaces.
Philosophy
Protocol 7 is not in a position to own your whole system. systemd, by contrast, is.
Real systemd-libs are used for ABI compatibility ~ the client libraries function fine without systemd running as PID 1. No mock or stub reimplementations are needed. eudev is a genuine, functional udev implementation ~ not a stub.
Security
Protocol 7 Core has been fuzz tested and hardened:
- lainos-dbus-bridge: dfuzzer 2.6 run against the full
org.freedesktop.login1interface ~ Exit status: 0, all methods and properties PASS. AddressSanitizer + dfuzzer ~ Exit status: 0, no memory errors detected. - lainos-notifyd: libFuzzer harness, 2,000,000 iterations ~ zero crashes. Manual socket fuzz test ~ all inputs survived, log injection sanitized, MSG_TRUNC detection confirmed.
- Valgrind memcheck: both daemons confirmed 0 errors, 0 leaks (definite/indirect/possible) under a full test pass, independently cross-validating the ASAN/dfuzzer/libFuzzer results (2026-07-09).
- All daemons drop to
nobodywithin seconds of startup ~ systemd-logind runs as root for the lifetime of the system - seccomp whitelists applied after privilege drop on all security-sensitive daemons
Core Components
| Component | Binary | Role |
|---|---|---|
lainos-init |
/usr/libexec/lainos/lainos-init |
Session initializer ~ detects Wayland, sets environment, execs compositor |
lainos-dbus-bridge |
/usr/libexec/lainos/lainos-dbus-bridge |
org.freedesktop.login1 D-Bus facade ~ fuzz tested, runs as nobody |
lainos-notifyd |
/usr/libexec/lainos/lainos-notifyd |
sd_notify socket sink ~ fuzz tested, runs as nobody |
lainos-ghost-units |
/usr/libexec/lainos/lainos-ghost-units |
Creates /run/systemd/* ghost directories |
lainos-audio-init |
/usr/libexec/lainos/lainos-audio-init |
PipeWire + WirePlumber + pipewire-pulse orchestration (optional package) |
lainos-machine-id |
/etc/init.d/lainos-machine-id |
Generates random /etc/machine-id on every boot |
cgroup-delegate |
/etc/init.d/cgroup-delegate |
cgroup2 mount + controller delegation |
Design Decisions
| Decision | Rationale |
|---|---|
Real systemd-libs, not mocks |
Simpler ABI compatibility |
Real eudev, not stubs |
Genuine udev implementation, full device event support |
dbus in sysinit runlevel |
Ensures D-Bus starts before all dependents |
cgroup-delegate and lainos-ghost-units in boot runlevel |
Dependencies not available in sysinit |
lainos-ghost-units after syslog-ng |
Prevents syslog-ng treating system as systemd-based (sd_booted() fix) |
seatd instead of logind |
Minimalist seat management |
doas instead of sudo |
Smaller attack surface |
No elogind |
Protocol 7 daemons handle logind responsibilities directly |
| Self-hosted OpenRC stack | No Artix dependency, full control over packaging |
lainos-audio-init as optional package |
Separation of concerns; not all systems need PipeWire orchestration |
System Hardening
Kernel Parameters
GRUB_CMDLINE_LINUX:
random.trust_cpu=off init_on_alloc=1 init_on_free=1 page_alloc.shuffle=1
sysctl Configuration
/etc/sysctl.d/99-lainos-hardening.conf:
# Network
net.ipv6.conf.all.disable_ipv6 = 1
net.ipv4.tcp_syncookies = 1
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.all.rp_filter = 1
net.ipv4.icmp_echo_ignore_broadcasts = 1
net.ipv4.tcp_rfc1337 = 1
# Kernel
kernel.kptr_restrict = 2
kernel.dmesg_restrict = 1
kernel.sysrq = 0
kernel.yama.ptrace_scope = 1
kernel.kexec_load_disabled = 1
kernel.unprivileged_userns_clone = 0
kernel.randomize_va_space = 2
kernel.perf_event_paranoid = 3
# Filesystem
fs.suid_dumpable = 0
kernel.core_pattern = |/bin/false
# Memory
vm.max_map_count = 1048576
hardened_malloc
GrapheneOS hardened_malloc (light variant) is preloaded via LD_PRELOAD wrappers for:
- alacritty, element, gnome-keyring-daemon, keepassxc, kleopatra, mpv
- tor daemon via
/etc/conf.d/tor
Incompatible applications (mozjemalloc or bwrap/glycin conflicts): librewolf, torbrowser-launcher, signal, thunar, virt-manager
Full Disk Encryption
LUKS encryption is supported and confirmed working via Calamares (opt-in at install time). Unlock at boot is handled by dracut's crypt and crypt-lib modules ~ no systemd-cryptsetup required.
Privacy Features
- Ephemeral machine-id ~ regenerated every boot
- MAC randomization ~ iwd randomizes WiFi MAC per boot
- No systemd-resolved ~ no DNS caching/tracking by default
- IPv6 disabled ~ prevents VPN/Tor IPv6 leaks
- gnome-keyring ~ encrypted secrets storage for Electron apps
Network Configuration
WiFi (iwd)
Quick start using lainos-utils:
wifi
Or manually:
iwctl
[iwd]# station wlan0 scan
[iwd]# station wlan0 get-networks
[iwd]# station wlan0 connect SSID
MAC randomization is enabled by default.
Wired (dhcpcd)
Automatic on boot via dhcpcd in the default runlevel.
lainos-utils
A set of utility scripts included with LainOS Layer 02:
| Script | Command | Purpose |
|---|---|---|
| wifi-scan | wifi |
iwd auto-scan and connect with numbered network menu |
| wg-vpn | wg1/wg1d ~ wg4/wg4d |
WireGuard VPN tunnel up/down (supports up to 4 tunnels) |
| torctl | torctl |
Start/stop Tor routing |
| kloak | kloak |
Keystroke anonymization (auto-detects keyboard) |
| brightness | brightness |
Screen brightness control |
| lainos-secure-messaging | lainos-secure-messaging |
Automated onion XMPP secure messaging setup (LESME) |
| ani-cli | ani-cli |
Anime streaming CLI |
| virtman | virtman |
KVM/QEMU VM manager wrapper |
| lainos-hardened-malloc | lainos-hardened-malloc {enable|disable|status} |
Toggle system-wide hardened_malloc via LD_PRELOAD in /etc/environment |
| lainos-help | lainos-help |
Opens the LainOS Layer 02 user guide with glow |
Troubleshooting
Calamares Session Log
doas grep -n "" /root/.cache/calamares/session.log
# View specific line range:
sed -n '100,200p' /root/.cache/calamares/session.log
Boot Log
cat /var/log/rc.log
Daemon Logs
Protocol 7 daemons log to /var/log/daemon.log:
doas tail -f /var/log/daemon.log
WiFi Soft-Blocked After Boot (Libreboot + thinkpad_acpi)
On Libreboot systems with thinkpad_acpi force_load=1, wifi may be soft-blocked on boot. This is handled automatically via /etc/local.d/rfkill-unblock.start. If manual intervention is needed:
doas rfkill unblock all
doas rc-service iwd restart
KVM Guests Have No Internet Access (DHCP Works, No Routing)
If a KVM/QEMU guest obtains a DHCP lease from libvirt's virbr0 network but
cannot reach the internet, the base nftables.conf forward chain likely
lacks the accept rules libvirt's own NAT chain depends on (LainOS ships a
default-drop forward policy for security, and this is not opened
automatically). Run:
lainos-kvm-enable-firewall
This adds the necessary virbr0 forward-accept rules to /etc/nftables.conf
and reloads the ruleset. A backup of the previous config is saved automatically.
Migrating from protocol7-core pre-5.5.3-2
doas rc-update del cgroup-delegate sysinit
doas rc-update del lainos-ghost-units sysinit
doas rm -f /etc/init.d/lainos-ghost-units
doas rm -f /etc/runlevels/sysinit/lainos-ghost-units
doas rm -f /etc/runlevels/boot/lainos-ghost-units
doas pacman -Syu
Project Structure
lainos-iso-layer-02/
~~ protocol7-profile/ # ISO build profile
~~ airootfs/ # Overlay files ~ ISO chroot
~ ~~ etc/
~ ~ ~~ acpi/ # Lid close event handler
~ ~ ~~ conf.d/ # Service environment (tor LD_PRELOAD)
~ ~ ~~ default/grub # GRUB configuration
~ ~ ~~ dracut.conf.d/ # Dracut initramfs config
~ ~ ~~ init.d/ # OpenRC init scripts
~ ~ ~~ runlevels/ # Service runlevel symlinks
~ ~ ~~ greetd/
~ ~ ~~ sysctl.d/ # Kernel hardening
~ ~ ~~ skel/ # Default user configs (sway, swaylock, wlogout)
~ ~ ~~ iwd/
~ ~ ~~ syslog-ng/
~ ~ ~~ dbus-1/system.d/
~ ~ ~~ doas.conf
~ ~~ usr/
~ ~ ~~ local/bin/ # Hardened_malloc wrappers, lainos-utils
~ ~ ~~ share/lainos/wallpapers/
~ ~~ root/ # Root home (live ISO swaylock/wlogout configs)
~~ packages.x86_64 # Package list
~~ pacman.conf # Build-time pacman config
~~ profiledef.sh # ISO metadata, permissions
~~ airootfs.sh # pacman-key init during build
Contributing
LainOS is developed by Grayson Giles and the LainOS community.
- Forgejo: https://forgejo.lain.rocks/lainOS/
- Codeberg: https://codeberg.org/lainOS
- GitLab: https://gitlab.com/lainos
- GitHub: https://github.com/The-LainOS-Project
- Website: https://lainos.net
Reporting Issues
Please include:
- ISO version/date
- Hardware/VM configuration
rc-statusoutput- Relevant logs from
/var/log/rc.logordmesg
License
LainOS Layer 02 and the Protocol 7 compatibility layer are released under the GNU General Public License v3.0.
Individual components (Sway, OpenRC, Calamares, etc.) retain their respective licenses.
Acknowledgments
- Arch Linux ~ The foundation everything is built on
- OpenRC ~ Reliable, predictable init system
- GrapheneOS ~ hardened_malloc
- Sway/wlroots ~ Modern Wayland compositor ecosystem
- Calamares ~ User-friendly system installer
Last updated: 2026-07-09 Current package: protocol7-core-5.5.3-21 Status: RC3 ~ release candidate