Name

hier - overview of the filesystem layout

Description

On Mutiny, a filesystem layout is used that attempts to both preserve relative compatibility with the Filesystem Hierarchy Standard, while also making it a priority to reduce cruft, legacy, and other unnecessary redundancy where possible.

Hierarchy

The following is a sketch of the filesystem hierarchy.

/

The root of the filesystem. From here, all flows forth. This is additionally the root user’s home directory.

/boot

Files used during the boot process, such as boot loader configuration, kernel executables, initramfs archives, and so on. If running on an EFI-enabled system, this whole directory should be mounted on an EFI partition.

/bin

Binaries installed on the system by the package manager, praxis(7), or through some other system-managed method.

/dev

Device files. This structure is first populated by devtmpfs[1] at boot, and then after boot, managed by mdevd(8).

/etc

System configuration. This directory is first populated by tendency-config-populate(1).

ksh/

Files relating to ksh(1).

  • rc - Startup file for ksh(1), sourced by /etc/profile. See profile(7).

fstab

Filesystem table. It is for specifying what filesystems can be mounted, and it’s used by commune-init(8) and mount(8) to mount your filesystems at boot. See fstab(5).

group

A list of groups on the system. See group(5).

hosts

A table of IP addresses associated with hostnames. See hosts(5).

issue

A file containing the message shown prior to the login prompt, printed by getty(8).

passwd

A list of user accounts on the system. This should be readable by all users. See passwd(5).

profile

A sh(1) script ran for login shells. See profile(7).

shadow

A "shadowed" passwd file: that is to say, it contains encrypted passwords, while /etc/passwd does not. Fittingly, it should not be readable by anyone except root. See shadow(5).

shells

A list of the shells a user can have as their login shell. See shells(5).

/home

Non-system users' home directories. There’s no specified directory structure within this directory, but usually all non-system users will have a directory under this one as their home directory.

/include

Header files for C and C++ libraries installed by the package manager, praxis(7), or through some other system-managed method, used by their respective compilers, cc(1) and c++(1).

/lib

Libraries and other non-user-facing executables installed by the package manager, praxis(7), or through some other system-managed method.

os-release

File containing metadata about the installed OS.

/local

System administrator-managed prefix. Everything under /local is effectively free reign for the user to add things without them being touched by any system management things; praxis(7) never install anything within here.

/mnt

Mounted filesystems. They may or may not be filesystems mounted from hotpluggable devices. There’s no specified directory structure within here.

/proc

The mountpoint of a pseudo-filesystem that provides a filesystem interface to some data in the kernel. Most notably, it contains a folder for each process ID on the system. See proc(5) for more details.

/run

Runtime files. That is, files that pertain to the system since it booted up, in some way; they hold no permanance and are never backed by an actual persistent storage. It is mounted as a tmpfs(5) filesystem, and exists only in RAM.

tmp

Various temporary files. This is also mounted as a secondary tmpfs(5). The contents of this directory is visible to all users of the system.

user

User-specific runtime files.

<UID>:

Runtime files which are controlled by the user ID UID. Each directory is created when the user logs in—​see login(7). This directory is marked read/write/execute only for the owner.

/share

Resources of various types, installed on the system by the package manager, praxis(7), or through some other system-managed method.

man

System man(1) pages. man* directories under this correspond to manual sections.

/srv

Data served by the system. Most commonly, data served by daemons running on the system, like an HTTP daemon, git-daemon(1), and so on.

/sys

The mountpoint of a pseudo-filesystem that provides a filesystem interface to kernel data structures. See sysfs(5).

/var

Persistent, mutable system data. Data that system programs might need sooner or later, and that might change over multiple boots of the system. Things like databases, logs, caches.

cache

Cache files.

lib

Databases and state files.

log

Log files.

tmp

Persistent, yet temporary files. It persists across boots, in contrast to /run/tmp.

A few symbolic links are used in the file hierarchy so as to facilitate compatibilty with some usually-common locations that Mutiny does not use.

/sbin

A symbolic link to "bin". Mutiny merges a lot of (nowadays) redundant directories. This one is from the era of Unix when /bin and /sbin were kept separate.

/tmp

A symbolic link to "run/tmp", so as not to disturb applications that expect this to be the temporary filesystem.

/usr

A symbolic link to "." (dot). Mutiny merges a lot of (nowadays) redundant directories. This one is from the era of Unix when /usr/bin and /bin were kept separate.

/var/run

A symbolic link to "../run". This is a location that has been used in the past for runtime data, in version 2.3 of the Filesystem Hierarchy Standard. In version 3.0, it was deprecated in favor of /run, but suggests a symbolic link be made.

See also

Filesystem Hierarchy Standard Group, The Filesystem Hierarchy Standard, version 2.3, January 29, 2004.

LSB Workgroup, The Linux Foundation, The Filesystem Hierarchy Standard, version 3.0, June 3, 2015.

Contributing

The canonical URL of this repository is https://git.mutiny.red/mutiny/filesystem. Submit patches and bugs to <kylie@somas.is>.

There is also an IRC channel for Mutiny and other projects at irc://irc.freenode.net/#mutiny. Please don’t hesitate to message if you need help.

License

filesystem is in the public domain.

To the extent possible under law, Kylie McClain <kylie@somas.is> has waived all copyright and related or neighboring rights to this work.


1. devtmpfs does not currently have a manual page, and documentation of it in the kernel is slim. See CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT in the kernel configuration to see descriptions of what it does.