Documentation › unix-ipc-protocol

LeonOS Unix IPC protocol

This document is the normative wire contract for the LeonOS service sockets. All paths live below /run/leonos/. Every service uses an AF_UNIX SOCK_STREAM connection and the length-prefixed framing described below.

Framing

u32 magic  = 'LNXU' (0x554e4c4c on little-endian x86_64)
u32 version = 1
repeat:
  u32 length
  u8  payload[length]

All integers are little-endian. A client opens one connection and issues a HELLO message first. The server uses SO_PEERCRED to learn the peer {pid, uid, gid}; the pid in HELLO must match the kernel-reported peer pid or the connection is rejected with ERROR{code=EPERM}.

Status

The four daemons run as independent OpenRC services (system/rootfs/etc/init.d/leonos-{windowd,imd,session,device}). There is no netmand or authd socket service: network control is a kernel ioctl on AF_INET fds (LEONOS_NET_CONTROL_IOCTL) with DHCP/NTP lifecycle owned by the leonos-dhcp/leonos-ntp OpenRC services, and accounts are standard /etc/passwd + /etc/shadow files authenticated through PAM.

Common message set

windowd (/run/leonos/windowd.sock)

The userspace windowd daemon owns the window registry. Pixel storage is a /dev/shm0 segment per window and crosses the socket only as an SCM_RIGHTS fd. Desktop connects with the policy handshake token desktop-policy-v1; the kernel SO_PEERCRED uid must be zero.

Accounts and authentication (no socket service)

Authentication has no AF_UNIX protocol. Accounts are standard /etc/passwd//etc/shadow records (Alpine shadow packaging) and login, password change, and elevation run through the PAM stack: login.elf calls leonos_pam_login(), su/sudo use the upstream binaries with sudoers/PAM policy (the sudod.elf askpass helper supports the legacy leonos_sudo_ libc API), and pam_leonos_password is the LeonOS-specific verifier module. The leonos_auth_ libc wrappers in userland/libc/src/auth_accounts.c read the passwd database directly with getpwuid-style calls; mutating operations run the standard tools as root or require the caller's own uid.

sessiond (/run/leonos/session.sock)

devmand (/run/leonos/devman.sock, the device-agent.elf service)

Phase 6 cleanup

• The fd 3 control-descriptor mechanism and every private service-request ioctl family are deleted from kernel and libc source.
• Remaining ioctls are device-UAPI only: TTY termios/winsize, evdev, OSS, block BLK, fbdev FBIO, and /dev/gpu GPU commands.
• ACL compatibility is expressed through chmod/chown; kernel-debug state uses /var/lib/leonos/kernel-debug.

procfs (kernel, read-only)

/proc/uptime, /proc/meminfo, /proc/version, /proc/machine-id, /proc/<pid>/stat, /proc/<pid>/cmdline, and /proc/self/* are synthetic storage nodes. They are read through ordinary open/read/readdir and are never served through a private ioctl.

Networking (no socket service)

There is no netmand daemon. Read-only network status queries use the kernel's LEONOS_NET_CONTROL_IOCTL (include/uapi/leonos/net_control.h) on an AF_INET socket fd, credential-checked in the kernel. Configuration changes are lifecycle operations of the OpenRC services leonos-dhcp (udhcpc, hook publishes /run/leonos/dhcp-lease) and leonos-ntp (hook publishes /run/leonos/ntp-state); the leonos_net_dhcp_renew()/ leonos_time_ntp_sync() libc helpers restart those services and validate the published files.

imd (/run/leonos/input-method.sock)

Phase 0 verification

Run /usr/lib/leonos/apps/ipctest/ipctest.elf on the target. It covers blocking socketpair reads, SCM_RIGHTS passing of a /dev/shm0 descriptor, shared mmap, credential syscalls, uname, and an AF_INET connect probe.

Migration status

Legacy application exports (leonos_gui_, leonos_auth_, leonos_net_, text_input_, leonos_startup_*, device/driver/system helpers) remain in libleonos with unchanged signatures; only their transport changed (windowd / imd / sessiond / devmand sockets, PAM-backed account reads, or AF_INET sockets plus the net control ioctl).