Documentation › FILESYSTEM

Filesystems

LeonOS 4 uses a multi-filesystem storage layer. The normal installed system is not a FAT32 root filesystem: it has a small FAT32 EFI System Partition (ESP) and a separate writable ext2 root partition. Existing exFAT installations remain readable legacy volumes, but the current Alpine-shaped root layout requires real symlinks (for example /bin/sh and /var/run); FAT32/exFAT cannot represent them, so current images do not create an exFAT root and the installer rejects that combination instead of materializing directory copies.

Installed Disk Layout

UEFI GRUB and the early loader read partition 1. Once the kernel is running, the storage layer selects partition 2 as /. FAT32 and exFAT data-volume backends remain available; the current userspace boot contract requires ext2 and the new root skeleton. Old images require a fresh installation.

The installer itself keeps using a writable ext2 image as its ramdisk root because it must start before any target disk is trusted. Its payload is deliberately split:

• /install/root is copied to the ext2 target root /target (or to an existing target with the same layout during update mode).
• /install/esp is copied to the FAT32 target ESP /target/boot.

Fresh installation creates both GPT partitions. Update requires both a valid root and ESP; old FAT32-only installations should use a fresh install. The installer does not migrate former /system, /programs or /users trees. See docs/ROOTFS_LAYOUT_AND_MIGRATION.md for the current layout and boundaries.

Device Namespace

/dev is a kernel-provided synthetic filesystem. It is present on every runtime root. Mount-point directories are stored in the image, but device nodes are synthesized. /dev/shm is a real root-backed directory, mode 1777, cleared before userspace on each boot; it is not a tmpfs mount. Directory reads enumerate the complete set of device nodes, including /dev/null, /dev/zero, /dev/tty, /dev/console, /dev/fb0, /dev/input/event0, /dev/input/event1, /dev/dsp, /dev/serial0, /dev/ethernet0, /dev/gpu, /dev/rtc, /dev/driverctl, /dev/kmsg, /dev/ptmx, and block-device aliases such as /dev/disk0, /dev/sda, /dev/vda, /dev/nvme0n1. The corresponding libc APIs open these paths before issuing device ioctls; legacy fd 3 calls are translated for older binaries.

Whole disks and GPT partitions are exposed as /dev/diskN and /dev/diskNpN block nodes. They support sector-aligned read/write, and the Linux UAPI requests BLKGETSIZE64, BLKGETSIZE, BLKSSZGET, BLKROGET and BLKRRPART from <linux/fs.h>. Raw sector reads/writes require an administrator (or the installer ISO's uid-0 shell); writes and partition-table rereads are rejected for booted or mounted disks.

/dev/input/event0 is the Linux evdev keyboard stream and /dev/input/event1 is the mouse stream. Each opened descriptor has its own event cursor, so readers do not consume Desktop input. The text-input method service no longer has a device node; the retired /dev/input-method endpoint was replaced by the imd daemon's AF_UNIX socket at /run/leonos/input-method.sock.

/dev/dsp is the Linux OSS-compatible PCM playback node. It accepts 16-bit little-endian stereo samples through normal write calls, supports nonblocking mode and poll(POLLOUT), and exposes the supported OSS setup ioctls from <linux/soundcard.h>. /dev/audio is a compatibility alias for legacy binaries only.

Supported Formats

ext2

The kernel implements the classic, unjournaled ext2 subset used by generated images and installer-created targets:

• 1 KiB, 2 KiB, and 4 KiB blocks; generated LeonOS images use 4 KiB.
• 128-byte-or-larger classic inodes.
• Direct, singly indirect, and doubly indirect file blocks.
• File read/write/truncate, directory enumeration, create, mkdir, unlink, rmdir, and same-filesystem rename.
• Standard Linux filesystem-data GPT type GUID.

It intentionally rejects extents, journals, metadata checksums, 64-bit block numbers, encryption, and unsupported incompatible feature bits. Build images with mke2fs -t ext2; tools/make_image.py disables unsupported modern extensions explicitly.

exFAT

New images and fresh installations use the standard single-FAT exFAT subset:

• 512-byte logical sectors with a validated primary and backup boot region.
• Allocation bitmap, compressed Microsoft upcase table, and directory entry-set checksums.
• UTF-8/UTF-16 names (up to 255 UTF-16 units) with case-insensitive lookup.
• Contiguous NoFatChain and ordinary FAT-chain files; reads, writes, truncation, directory creation/removal, deletion, enumeration, and same- volume rename.
• Microsoft Basic Data GPT type is required for the runtime root. The recommended GPT partition name is LEONOS4_ROOT; boot discovery also accepts a valid exFAT signature when that label is missing or was changed. The exFAT volume-label limit means the on-volume label is LEONOS4ROOT.

TexFAT, multiple FATs, non-512-byte sectors, POSIX inode metadata, and native permissions are rejected. LEONACL.SYS remains the hidden LeonOS ACL sidecar. Sudden-power-loss repair is expected to use the host fsck.exfat.

FAT32

FAT32 remains supported for the ESP, installer ramdisk, legacy installed images, removable media, and compatibility data volumes. Long file names, directory traversal, reads, writes, creation, deletion, and renaming remain available. FAT32 remains the only filesystem the UEFI/GRUB boot path relies on.

ISO 9660

Optical media is discovered through AHCI ATAPI and automatically mounted at /media/cdrom<N>. ISO 9660 volumes are read-only. This is independent of whether the boot/root disk uses exFAT, ext2, or FAT32.

Runtime Data Mounts

Disk Manager can mount a supported, unprotected FAT32, exFAT, or ext2 GPT data partition for the current boot. The kernel mounts it at the stable path /mnt/disk<N>p<M>, where N is the disk ID and M is the GPT entry index plus one. The mount path is shown in the partition status and appears in File Manager's sidebar without restarting File Manager. BusyBox mount exposes the same operation and accepts an explicit absolute target path.

Runtime data mounts are deliberately non-persistent in this first version: they are removed on reboot and no automatic mounting policy is stored on disk. Mounting the same partition again is idempotent and returns its existing mount path. FAT32, exFAT, and the classic ext2 subsets documented above are accepted; an unknown or unsupported on-disk filesystem is rejected rather than mounted according to its GPT type alone.

The installer reserves /target for the target root and /target/boot for its ESP while a target is mounted. Formatting or mounting an installer target is rejected with busy if those paths contain an optical, data, or other runtime volume; this prevents an installer operation from silently replacing a live mount.

Unmounting is administrator-gated. The kernel refuses it while any live task has that volume as its working directory, owns an open file on it, is executing an image from it, or retains a file-backed mapping from it. Format and delete are likewise refused while the partition is mounted. This avoids stale file nodes and mappings after a volume is removed.

Disk Manager Partitions

Disk Manager presents the GPT entries of every detected AHCI, IDE/PATA, or NVMe disk, including their name, LBA range, filesystem probe, capacity, GPT role, protection state, and mount path when mounted. It can create a 1 MiB-aligned FAT32, exFAT, or ext2 data partition in free space, format an existing data partition as either filesystem, delete an existing data partition's GPT entry, and mount or unmount a supported data partition. New partition creation includes formatting as part of the operation.

Formatting reuses the installer-grade FAT32, exFAT, and ext2 formatters but applies only to the selected partition extent. FAT32 and exFAT data partitions use the Microsoft Basic Data GPT type; ext2 data partitions use the Linux filesystem type. Deleting a partition removes its GPT metadata only, so it is not a secure-wipe operation.

Disk Manager never allows partition changes or runtime mounts against the current boot disk or a target disk currently mounted by the installer. This restriction is enforced by the kernel, not merely disabled buttons. The initial partition-management ABI supports the common 128-entry, 128-byte GPT table format generated by LeonOS and rejects a malformed, overlapping, out-of-range, or CRC-invalid table before making a modification.

VFS and Paths

LeonOS paths use Unix absolute syntax, for example /usr/lib/leonos/apps/desktop/desktop.elf. The kernel resolves . and .. and the storage layer dispatches the result through the longest matching mount path. Paths containing : are rejected; legacy disk prefixes are not supported. Filesystem names are case-insensitive at the LeonOS path layer for compatibility with historical FAT32 behavior; avoid creating names that differ only by case on ext2.

The device directory is synthesized at /dev; it contains standard device nodes and input/pts subdirectories even when the backing filesystem has no physical directory entry. LEONACL.SYS is internal ACL sidecar metadata: it remains readable by the authorization service but is hidden from normal exFAT, FAT32, and ext2 directory enumeration.

API Behavior

Current file syscalls support all writable exFAT, ext2, and FAT32 roots:

• File reads and short, bounded writes.
• Create and overwrite through open flags.
• mkdir, unlink, rmdir, and rename within one mounted filesystem.
• Directory listing, stat, seek, and ACL service integration.

Cross-mount rename is rejected. ISO 9660 returns a read-only error for all mutation operations. exFAT allocation updates its bitmap and FAT chains; ext2 allocation updates its inode/block bitmaps and free counts; FAT32 retains its cluster-chain allocator and LFN handling.

Safety and Recovery

ext2 has no journal, so sudden loss of power during metadata updates can still require offline repair. The installer writes a complete target layout before copying payload files and treats a failed copy as an installation failure. The normal image generator and installer formatter reserve distinct boot and root partitions so a large runtime file cannot consume ESP space.

Use tools/analyze_boot_log.py when boot diagnostics show a root mount failure. The log identifies whether exFAT, ext2, or the legacy FAT32 fallback was used.