HIER(7) Miscellaneous Information Manual HIER(7)

hier, fhs — MOUSE filesystem layout

MOUSE uses a BSD-shaped filesystem hierarchy with an explicit boundary between World and Ports. The name fhs is provided as a lookup alias; this page describes MOUSE policy rather than claiming conformance with the Linux Filesystem Hierarchy Standard.

/
The active ZFS root dataset.
/bin
Essential World commands, including the static rescue multicall executable and the system shell.
/sbin
World administration commands needed for boot, recovery, storage, networking, and service control.
/dev
Device nodes created for the running kernel.
/etc
System policy and configuration seeded by World and subsequently owned by the machine. Local service enablement belongs in /etc/rc.conf; local service-definition overrides belong in /etc/init.d; World default service definitions are below /usr/lib/mouse/init.d; OpenRC framework settings belong in /etc/openrc/rc.conf; package configuration does not. It is mounted from the separate zroot/ETC dataset and is preserved during World installation and rollback.
/home
User home directories on the separate zroot/HOME dataset.
/media
Mount point for removable media. World creates it but does not replace it during an in-place upgrade.
/lib
Runtime libraries and OpenRC support files supplied by World.
/libexec
Private World executables used during startup and runtime linking.
/root
The superuser administration and recovery directory. It remains in the root dataset and must not be used for ordinary persistent storage.
/tmp
Temporary files writable by all users. On a normal installed boot, it is a dynamically sized tmpfs mounted by cheesed(8) at boot; live media bounds it to 64 MiB and 8192 nodes.
/usr
The complete installed World outside the boot-critical root directories.
/var
Machine state on the separate zroot/VAR dataset.

/usr/bin
Ordinary World commands and MOUSE desktop programs.
/usr/sbin
World administration commands not required directly by the early boot path.
/usr/include
Headers used to compile World and Ports software.
/usr/doc
Licences and notices installed by World components.
/usr/lib
Libraries, development objects, private data, and MOUSE runlevel manifests.
/usr/lib/mouse
MOUSE release metadata, the World manifest, boot payload, and default OpenRC service definitions below /usr/lib/mouse/init.d.
/usr/libexec
Private World executables.
/usr/share
Architecture-independent World data, manual pages, fonts, desktop data, and build-system files.
/usr/src
The wheel-writable MOUSE source tree used to construct and maintain this release.

/usr/local
The installation prefix reserved for user-selected Ports software. World does not install programs or libraries here. It is mounted from the separate zroot/LOCAL dataset so installed Ports remain separate from World.
/usr/local/etc
Configuration installed or consumed by Ports software, including optional OpenRC service definitions below /usr/local/etc/init.d. World defaults and local overrides take precedence over Ports definitions.
/usr/local/src
Administrator-managed source trees for optional software. Pkgsrc is normally checked out at /usr/local/src/pkgsrc by the bootstrap procedure in ports(7); World never supplies it.

/var/cache
Reusable application and package-manager data.
/var/cache/pkgsrc/distfiles
Downloaded pkgsrc distribution files created by the optional bootstrap.
/var/cache/pkgsrc/packages
Binary packages created by pkgsrc.
/var/chroot
Restricted roots used by network services.
/var/db
Persistent system and application databases.
/var/db/pkg
The pkgsrc package database created by the optional bootstrap.
/var/lib
Persistent application state.
/var/log
System and service logs.
/var/run
Runtime state on a dynamically sized tmpfs mounted by cheesed(8), including the effective OpenRC runlevel tree; live media bounds it to 32 MiB and 8192 nodes.
/var/shm
Shared-memory files on a dynamically sized tmpfs mounted by cheesed(8). Live media bounds it to 64 MiB and 16384 nodes.
/var/spool
Queued service data, including cron tables.
/var/tmp
Temporary files intended to survive longer than files below /tmp.
/var/tmp/pkgsrc
pkgsrc work directories created by the optional bootstrap.

World owns /bin, /sbin, and /usr. World seeds /etc when creating a system but does not replace it during an upgrade. Ports install below /usr/local and record packages below /var/db/pkg. A Port may use World headers and libraries, but it must not replace World files or store package configuration in /etc.

/usr/src is the MOUSE source shipped with the release. /usr/local/src is an administrator-managed upstream pkgsrc checkout when optional software is bootstrapped. It is never part of World. They have different update policies and must remain separate.

The root dataset contains World. Keeping other ownership domains on separate datasets lets World be snapshotted or restored without capturing ordinary user data, installed Ports, or continuously changing machine state.

/home is controlled by users, /usr/local is controlled by the system administrator, and /var is variable by definition. Their separate datasets keep those ownership domains outside World snapshots. /root is different: it is part of the base administration and recovery environment, so it remains with World and is expected to contain only the material needed to administer the machine. Keeping it with World makes the recovery account's own directory available without depending on user-controlled or continuously changing datasets.

/etc begins with World defaults and becomes machine policy. Its separate dataset keeps that policy outside World snapshots and rollback. /tmp has no persistent ownership at all, so it is recreated as a tmpfs at each boot.

rc.conf(5), mouse(7), ports(7), world(7), cheesed(8)

MOUSE September 1, 2026 HIER(7)