From 9e7b691073922433a71cf49dcaaf7f9f61f58e6d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 30 Sep 2024 17:29:15 +0200 Subject: [PATCH 1/4] man: drop mention of /usr/include/ from file-hierarchy(7) man page The man page is supposed to provide a "generalized, though minimal and modernized subset" (as per introductory pargapraghs), from a systemd perspective. But the thing is that /usr/include/ really doesn't matter to us. It's a development thing, and slightly weird (because it arguably would be better places in /usr/share/include/ or so). It's not going to be there on 95% of deployed systems, and we really don't want people to bother with it on such systems. We only define the skeleton of directories in this document, and it's expected that people extend it, and I think this really should be one of those dirs that is an extension of our skeleton, but not part of the skeleton, if that makes any sense. --- man/file-hierarchy.xml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 9c208dba74..db045b7fe0 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -182,11 +182,6 @@ subdirectory of /usr/lib/ instead. - - /usr/include/ - C and C++ API header files of system libraries. - - /usr/lib/ Static, private vendor data that is compatible with all architectures (though not @@ -616,10 +611,6 @@ /usr/lib/arch-id/package/ Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture. - - /usr/include/package/ - Public C/C++ APIs of public shared libraries of the package. - From b0201b36d2e0181d08530aaad496322812c4e77e Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 30 Sep 2024 17:29:35 +0200 Subject: [PATCH 2/4] man: drop /var/spool/ mention from file-hierarchy(7) man page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Today it seems this is mostly used by mail and printer servers, and it's not clear to me at all what the property is that makes /var/spool/ the better place for the relevant data than /var/lib/. Hence, in the interest of shortening the spec, let's not mention the dir anymore. In particular as the dir really isn't used by us much, for example we do not have a counterpart for RuntimeDirectory=, StateDirectory=, … that would cover the spool. Since most systems these days we care about probably come *without* a printer or mail server, let's maybe no mention this in the man page that is supposed to discuss the rough skeleton how things are set up. After all, people are supposed to exend the skeleton with their stuff, and this sounds more like a case for an extension of the skeleton instead of being considered part of the skeleton itself. --- man/file-hierarchy.xml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index db045b7fe0..4b92d596cb 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -277,11 +277,6 @@ calls. - - /var/spool/ - Persistent system spool data, such as printer or mail queues. - - /var/tmp/ The place for larger and persistent temporary files. In contrast to @@ -658,10 +653,6 @@ /var/log/package/ Persistent log data of the package. As above, the package should make sure to create this directory if necessary, possibly using tmpfiles.d5 or LogsDirectory= (see systemd.exec5), as it might be missing. - - /var/spool/package/ - Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing. - From fd6e079e7b296696028c161224d2a86fce70726f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 30 Sep 2024 18:19:33 +0200 Subject: [PATCH 3/4] man: clarify that the defined file hiearchy is just a skeleton (And specifically mention /usr/include + /var/spool as not covered here, but being OK to add downstream) --- man/file-hierarchy.xml | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 4b92d596cb..06f8fecf89 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -24,17 +24,21 @@ Description Operating systems using the - systemd1 system and service - manager are organized based on a file system hierarchy inspired by UNIX, more specifically the hierarchy described - in the File System Hierarchy - specification and hier7, with various - extensions, partially documented in the systemd1 system and + service manager are organized based on a file system hierarchy inspired by UNIX, more specifically the + hierarchy described in the File + System Hierarchy specification and hier7, with + various extensions, partially documented in the XDG Base Directory Specification and XDG User - Directories. This manual page describes a more generalized, though minimal and modernized subset of these - specifications that defines more strictly the suggestions and restrictions systemd makes on the file system - hierarchy. + Directories. This manual page describes a more generalized, though minimal and modernized subset + of these specifications that defines more strictly the suggestions and restrictions systemd makes on the + file system hierarchy. Note that this document makes no attempt to define the directory structure + comprehensively, it only documents a skeleton of a directory tree, that downstreams can extend. Because + of that traditional directories such as /usr/include/ or + /var/spool/ are not covered, even though it might (or might not) make a lot of sense + to include them in the structure of an actually deployed OS. Many of the paths described here can be queried with the From 5b53894123b9d01f5738b02befd4189625c5451f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 30 Sep 2024 18:28:27 +0200 Subject: [PATCH 4/4] man: add a comment that inode type policy might be enforces via an LSM or similar Just to tighten the language a bit, why people should care about where they place their inodes. --- man/file-hierarchy.xml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 06f8fecf89..47f93a3234 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -573,6 +573,9 @@ Similarly, /run/ shall be the only location to place sockets and FIFOs. Regular files, directories and symlinks may be used in all directories. + + Applications should expect that a security policy might be enforced on a system that enforces these + rules.