From 0a1925a455e350b748e4789b9405ee55fecf5781 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Jan 14 2026 14:36:52 +0000 Subject: [PATCH 1/2] filesystem: refer to LFSH instead of the FHS The FHS is severly outdated. Even the "current" version 3.0 is 10 years old at this point (published June 3, 2015), and hasn't even followed the evolution of Linux systems that happened before 2015. In particular, at that time, the usr-merge had already happened in Fedora, with the relevant discussions happening very publicly in the preceding years. Obviously, the FHS also couldn't follow later changes like the sbin-merge, or increasing use of /run. There are some open tickets discussing additions to the FHS, but they are stalled and it seems that there is little suppport among the maintainers. At this point, the FHS is mostly of historical interest. Link to "Linux File System Hierarchy" that is provided by the "uapi group" site that grew out of the systemd project. It describes modern Linux systems as they are, so it's both much more accurate and relevant, but also a _much_ shorter document. That page internally links to FHS 3.0 and XDG docs, so the interested reader can read the background docs if they want to. Since the new page actually describes what we are doing anyway, this doesn't introduce any new rules, only just drops some baggage that we were ignoring anyway. Prompted by fedora-devel thread: https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/54GTFIECDKTIBATUVG3JQ4ZEDFBUMNLE/ v2: - file-hierarchy.7 was lifted from the systemd project to uapi group and modernized, so update the link. /usr/libexec is now described too, so drop the wording about it not being described. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 8336c61..b3784d6 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -518,29 +518,24 @@ For example: == Filesystem Layout -Fedora follows the -https://refspecs.linuxfoundation.org/fhs.shtml[Filesystem Hierarchy Standard] -with regards to filesystem layout, -with exceptions noted below. -The FHS defines where files should be placed on the system. +Fedora uses the layout described in +https://uapi-group.org/specifications/specs/linux_file_system_hierarchy[Linux File System Hierarchy] +with some additional rules noted below +to determine where files should be placed on the system. -=== Exceptions +=== Additional rules -* Fedora allows cross-compilers to place files in `+/usr/target+`. +* Cross-compilers **may** place files in `+/usr/target+`. * The `/nix` top-level directory may be used exclusively for Nix runtime and package store. It may only be created and owned by the `nix-filesystem` package. -* Fedora does not allow new directories - directly under `+/+` or `+/usr+` without FPC approval. +* New directories directly under `+/+` or `+/usr+` **must not** be added without FPC approval. === Libexecdir -The https://www.pathname.com/fhs/[Filesystem Hierarchy Standard] -does not include any provision for libexecdir, -but Fedora packages MAY store appropriate files there. -Libexecdir (aka, `+/usr/libexec+` on Fedora systems) -should only be used as the directory for executable programs +Fedora packages **may** store appropriate files in `/usr/libexecdir`. +This directory should only be used as the directory for executable programs that are designed primarily to be run by other programs rather than by users. @@ -565,7 +560,7 @@ more appropriate for their distro). === Multilib Exempt Locations If a package is exempt from multilib, -it may use `+%{_prefix}/lib+` instead of `+%{_libdir}+`. +it **may** use `+%{_prefix}/lib+` instead of `+%{_libdir}+`. Packages that contain architecture specific files that would ordinarily be installed into `+%{_libexecdir}+` are always considered ineligible for multilib. @@ -584,7 +579,14 @@ before any services are started === No Files or Directories Under `+/srv+`, `+/usr/local+`, or `+/home/$USER+` -The https://www.pathname.com/fhs/pub/fhs-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM[FHS says]: +https://uapi-group.org/specifications/specs/linux_file_system_hierarchy[Linux File System Hierarchy] +describes `+/srv+` as +.... +The place to store general server payload, managed by the administrator. +No restrictions are made how this directory is organized internally. +... + +The https://www.pathname.com/fhs/pub/fhs-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM[FHS] says: .... "...no program should rely on a specific subdirectory structure of /srv existing @@ -595,8 +597,7 @@ Distributions must take care not to remove locally placed files in these directories without administrator permission." .... -The FHS is explicitly handing control of the directory structure -under `+/srv+` to the system administrator rather than the distribution. +`+/srv+` is under control of the system administrator rather than the distribution. Therefore, no Fedora packages can have any files or directories under `+/srv+`, come preconfigured to use specific files or directories under `+/srv+`, to remove files there, or to modify the files there in any way. @@ -605,8 +606,7 @@ In addition, no Fedora package can contain files or directories or modify files under: * `+/usr/local+` -as these directories are not permitted to be used -by Distributions in the FHS +as these directories are not permitted to be used by distributions, * `+/home/$USER+` as users can arbitrarily modify the files in their home directories and rpm packages that modify those files run the risk of destroying user data. @@ -619,12 +619,12 @@ will have negative effects in both of these situations. It is important to note that the software in a Fedora package, once installed and configured by a user, can use `+/srv+` as a location for data. -The package simply must not do this out of the box +The package simply must not do this out of the box. === Limited Usage of `+/opt+`, `+/etc/opt+`, and `+/var/opt+` `+/opt+` and its related directories (`+/etc/opt+` and `+/var/opt+`) -is reserved for the use of vendors in the FHS. +is reserved for the use of vendors. We have reserved the `+fedora+` name with https://www.lanana.org/lsbreg/providers/providers.txt[LANANA] for our use. From dc5ba1d2eb712e6df7c243ceff535040b999e65a Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Jan 14 2026 14:37:26 +0000 Subject: [PATCH 2/2] filesystem: describe /boot/efi The upstream LFSH spec describes /boot and /efi. We traditionally use /boot/efi instead, but that has downsides: /boot must be always mounted (and appropriately populated) before /efi is mounted. An automount cannot be used. Ideally, we'd switch to non-nested directories, and then almost certainly we'd follow the systemd/LFSH layout. But until that's done, let's describe the currently used scheme. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index b3784d6..d55866d 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -530,6 +530,9 @@ to determine where files should be placed on the system. * The `/nix` top-level directory may be used exclusively for Nix runtime and package store. It may only be created and owned by the `nix-filesystem` package. +* LFSH describes `/efi` as the mount point for the EFI System Partition (ESP). + Fedora installations instead use `/boot/efi`. + * New directories directly under `+/+` or `+/usr+` **must not** be added without FPC approval. === Libexecdir