aboutsummaryrefslogtreecommitdiff
HIER(7)                        Mutineer's Guide                        HIER(7)



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.

   Symbolic links
       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
       file-hierarchy(7)
       <https://www.freedesktop.org/software/systemd/man/file-hierarchy.html>

       Filesystem Hierarchy Standard Group, The Filesystem Hierarchy Standard,
       version 2.3
       <https://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html>, January
       29, 2004.

       LSB Workgroup, The Linux Foundation, The Filesystem Hierarchy Standard,
       version 3.0
       <https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html>, June 3,
       2015.

       Rob Landley, Understanding the bin, sbin, usr/bin, usr/sbin Split
       <http://lists.busybox.net/pipermail/busybox/2010-December/074114.html>,
       December 9, 2010.

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.

        <http://creativecommons.org/publicdomain/zero/1.0/>

NOTES
       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.



Mutiny                            2020-07-11                           HIER(7)