diff options
author | Frantisek Sumsal <frantisek@sumsal.cz> | 2024-04-17 20:54:45 +0200 |
---|---|---|
committer | Frantisek Sumsal <frantisek@sumsal.cz> | 2024-04-17 21:21:23 +0200 |
commit | 0d592a5e17d473d301b921fbd43b8ef2c3b518ec (patch) | |
tree | e6a72e51047a8f575bfc155596e8f8744651fdeb | |
parent | Revert "docs: don't suffix page permalink with a slash" (diff) | |
download | systemd-0d592a5e17d473d301b921fbd43b8ef2c3b518ec.tar.xz systemd-0d592a5e17d473d301b921fbd43b8ef2c3b518ec.zip |
docs: use absolute links for our pages
Since 56b2970 has proven to be a no-go for us, as it breaks existing
links, let's embrace the trailing slash and use absolute links
everywhere for our pages. This way we'll get around browser cleverly
appending the relative link to the current location (since it ends with
a slash), and given our docs/ layout is flat it's not much of a hassle
either.
Converted using this beauty:
$ sed -ri 's/(\[.+\]\()([A-Z_]+\))/\1\/\2/g' *.md
Resolves: #32088 (again) and #32310
32 files changed, 70 insertions, 70 deletions
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0534c190a8..d046f274ee 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -112,7 +112,7 @@ Names of meson tests include the input file name and output looks awkward if the Fuzzers are invoked primarily in three ways: firstly, each fuzzer is compiled as a normal executable and executed for each of the input samples under `test/fuzz/` as part of the test suite. Secondly, fuzzers may be instrumented with sanitizers and invoked as part of the test suite (if `-Dfuzz-tests=true` is configured). -Thirdly, fuzzers are executed through fuzzing engines that tryto find new "interesting" inputs through coverage feedback and massive parallelization; see the links for oss-fuzz in [Code quality](CODE_QUALITY). +Thirdly, fuzzers are executed through fuzzing engines that tryto find new "interesting" inputs through coverage feedback and massive parallelization; see the links for oss-fuzz in [Code quality](/CODE_QUALITY). For testing and debugging, fuzzers can be executed as any other program, including under `valgrind` or `gdb`. ## Integration Tests diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md index a1f6b59568..4bf074df5e 100644 --- a/docs/BOOT_LOADER_INTERFACE.md +++ b/docs/BOOT_LOADER_INTERFACE.md @@ -78,7 +78,7 @@ variables. All EFI variables use the vendor UUID * `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set. * `1 << 2` → The boot loader honours `LoaderEntryDefault` when set. * `1 << 3` → The boot loader honours `LoaderEntryOneShot` when set. - * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](AUTOMATIC_BOOT_ASSESSMENT). + * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](/AUTOMATIC_BOOT_ASSESSMENT). * `1 << 5` → The boot loader supports looking for boot menu entries in the Extended Boot Loader Partition. * `1 << 6` → The boot loader supports passing a random seed to the OS. * `1 << 13` → The boot loader honours `menu-disabled` option when set. diff --git a/docs/CGROUP_DELEGATION.md b/docs/CGROUP_DELEGATION.md index 0aeb6f21ab..9e2e76c5ee 100644 --- a/docs/CGROUP_DELEGATION.md +++ b/docs/CGROUP_DELEGATION.md @@ -29,8 +29,8 @@ This document then adds in the higher-level view from systemd. This document augments the existing documentation we already have: -* [The New Control Group Interfaces](CONTROL_GROUP_INTERFACE) -* [Writing VM and Container Managers](WRITING_VM_AND_CONTAINER_MANAGERS) +* [The New Control Group Interfaces](/CONTROL_GROUP_INTERFACE) +* [Writing VM and Container Managers](/WRITING_VM_AND_CONTAINER_MANAGERS) These wiki documents are not as up to date as they should be, currently, but the basic concepts still fully apply. You should read them too, if you do something diff --git a/docs/CODE_QUALITY.md b/docs/CODE_QUALITY.md index 166b307b66..4caf38f7e8 100644 --- a/docs/CODE_QUALITY.md +++ b/docs/CODE_QUALITY.md @@ -75,7 +75,7 @@ available functionality: 15. Each PR is automatically tested with [Address Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) and [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html). - See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS) + See [Testing systemd using sanitizers](/TESTING_WITH_SANITIZERS) for more information. 16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell). diff --git a/docs/CONTAINER_INTERFACE.md b/docs/CONTAINER_INTERFACE.md index fee6ccbab3..e64953c8b4 100644 --- a/docs/CONTAINER_INTERFACE.md +++ b/docs/CONTAINER_INTERFACE.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later # The Container Interface -Also consult [Writing Virtual Machine or Container Managers](WRITING_VM_AND_CONTAINER_MANAGERS). +Also consult [Writing Virtual Machine or Container Managers](/WRITING_VM_AND_CONTAINER_MANAGERS). systemd has a number of interfaces for interacting with container managers, when systemd is used inside of an OS container. If you work on a container diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ea5efceeb2..c247102d10 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -33,13 +33,13 @@ For older versions that are still supported by your distribution please use resp ## Security vulnerability reports -See [reporting of security vulnerabilities](SECURITY). +See [reporting of security vulnerabilities](/SECURITY). ## Posting Pull Requests * Make sure to post PRs only relative to a recent tip of the `main` branch. -* Follow our [Coding Style](CODING_STYLE) when contributing code. This is a requirement for all code we merge. -* Please make sure to test your change before submitting the PR. See the [Hacking guide](HACKING) for details on how to do this. +* Follow our [Coding Style](/CODING_STYLE) when contributing code. This is a requirement for all code we merge. +* Please make sure to test your change before submitting the PR. See the [Hacking guide](/HACKING) for details on how to do this. * Make sure to run the test suite locally, before posting your PR. We use a CI system, meaning we don't even look at your PR if the build and tests don't pass. * If you need to update the code in an existing PR, force-push into the same branch, overriding old commits with new versions. * After you have pushed a new version, add a comment explaining the latest changes. diff --git a/docs/CONTROL_GROUP_INTERFACE.md b/docs/CONTROL_GROUP_INTERFACE.md index 5e461d7f15..c82a2c330a 100644 --- a/docs/CONTROL_GROUP_INTERFACE.md +++ b/docs/CONTROL_GROUP_INTERFACE.md @@ -12,7 +12,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later Starting with version 205 systemd provides a number of interfaces that may be used to create and manage labelled groups of processes for the purpose of monitoring and controlling them and their resource usage. This is built on top of the Linux kernel Control Groups ("cgroups") facility. -Previously, the kernel's cgroups API was exposed directly as shared application API, following the rules of the [Pax Control Groups](PAX_CONTROL_GROUPS) document. +Previously, the kernel's cgroups API was exposed directly as shared application API, following the rules of the [Pax Control Groups](/PAX_CONTROL_GROUPS) document. However, the kernel cgroup interface has been reworked into an API that requires that each individual cgroup is managed by a single writer only. With this change the main cgroup tree becomes private property of that userspace component and is no longer a shared resource. @@ -56,7 +56,7 @@ On systemd systems use the systemd APIs as described below. At this time we are ### What's the timeframe of this? Do I need to care now? -In the short-term future writing directly to the control group tree from applications should still be OK, as long as the [Pax Control Groups](PAX_CONTROL_GROUPS) document is followed. In the medium-term future it will still be supported to alter/read individual attributes of cgroups directly, but no longer to create/delete cgroups without using the systemd API. In the longer-term future altering/reading attributes will also be unavailable to userspace applications, unless done via systemd's APIs (either D-Bus based IPC APIs or shared library APIs for _passive_ operations). +In the short-term future writing directly to the control group tree from applications should still be OK, as long as the [Pax Control Groups](/PAX_CONTROL_GROUPS) document is followed. In the medium-term future it will still be supported to alter/read individual attributes of cgroups directly, but no longer to create/delete cgroups without using the systemd API. In the longer-term future altering/reading attributes will also be unavailable to userspace applications, unless done via systemd's APIs (either D-Bus based IPC APIs or shared library APIs for _passive_ operations). It is recommended to use the new systemd APIs described below in any case. Note that the kernel cgroup interface is currently being reworked (available when the "sane_behaviour" kernel option is used). This will change the cgroupfs interface. By using systemd's APIs this change is abstracted away and invisible to applications. @@ -219,7 +219,7 @@ To acquire a list of currently running units, use the `ListUnits()` call on the ### VM and Container Managers -Use these APIs to register any kind of process workload with systemd to be placed in a resource controlled cgroup. Note however that for containers and virtual machines it is better to use the [`machined`](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.machine1.html) interfaces since they provide integration with "ps" and similar tools beyond what mere cgroup registration provides. Also see [Writing VM and Container Managers](WRITING_VM_AND_CONTAINER_MANAGERS) for details. +Use these APIs to register any kind of process workload with systemd to be placed in a resource controlled cgroup. Note however that for containers and virtual machines it is better to use the [`machined`](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.machine1.html) interfaces since they provide integration with "ps" and similar tools beyond what mere cgroup registration provides. Also see [Writing VM and Container Managers](/WRITING_VM_AND_CONTAINER_MANAGERS) for details. ### Reading Accounting Information diff --git a/docs/CONVERTING_TO_HOMED.md b/docs/CONVERTING_TO_HOMED.md index d2841a5a7e..a31ff5a37e 100644 --- a/docs/CONVERTING_TO_HOMED.md +++ b/docs/CONVERTING_TO_HOMED.md @@ -17,10 +17,10 @@ Below is a brief guide how to do that. Before continuing, please read up on these basic concepts: -* [Home Directories](HOME_DIRECTORY) -* [JSON User Records](USER_RECORD) -* [JSON Group Records](GROUP_RECORD) -* [User/Group Record Lookup API via Varlink](USER_GROUP_API) +* [Home Directories](/HOME_DIRECTORY) +* [JSON User Records](/USER_RECORD) +* [JSON Group Records](/GROUP_RECORD) +* [User/Group Record Lookup API via Varlink](/USER_GROUP_API) ## Caveat diff --git a/docs/COREDUMP.md b/docs/COREDUMP.md index 925e3eb6c0..d2354792d9 100644 --- a/docs/COREDUMP.md +++ b/docs/COREDUMP.md @@ -68,7 +68,7 @@ specified service unit, and thus can take benefit of regular service resource management and sandboxing. The `systemd-coredump` handler will extract a backtrace and -[ELF packaging metadata](ELF_PACKAGE_METADATA) from any coredumps it +[ELF packaging metadata](/ELF_PACKAGE_METADATA) from any coredumps it receives and log both. The information about coredumps stored in the journal can be enumerated and queried with the [`coredumpctl`](https://www.freedesktop.org/software/systemd/man/coredumpctl.html) diff --git a/docs/CREDENTIALS.md b/docs/CREDENTIALS.md index 070ef42cf0..fd87c8598a 100644 --- a/docs/CREDENTIALS.md +++ b/docs/CREDENTIALS.md @@ -59,7 +59,7 @@ purpose. Specifically, the following features are provided: 8. Credentials are an effective way to pass parameters into services that run with `RootImage=` or `RootDirectory=` and thus cannot read these resources directly from the host directory tree. - Specifically, [Portable Services](PORTABLE_SERVICES) may be + Specifically, [Portable Services](/PORTABLE_SERVICES) may be parameterized this way securely and robustly. 9. Credentials can be binary and relatively large (though currently an overall @@ -288,7 +288,7 @@ services where they are ultimately consumed. [`systemd-nspawn(1)`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#Credentials)'s `--set-credential=` and `--load-credential=` switches implement this, in order to pass arbitrary credentials from host to container payload. Also see - the [Container Interface](CONTAINER_INTERFACE) documentation. + the [Container Interface](/CONTAINER_INTERFACE) documentation. 2. Quite similar, VMs can be passed credentials via SMBIOS OEM strings (example qemu command line switch `-smbios diff --git a/docs/FAQ.md b/docs/FAQ.md index 83ea743ad9..3b03726c9d 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later # Frequently Asked Questions -Also check out the [Tips & Tricks](TIPS_AND_TRICKS)! +Also check out the [Tips & Tricks](/TIPS_AND_TRICKS)! **Q: How do I change the current runlevel?** @@ -104,12 +104,12 @@ A: Use: **Q: Whenever my service tries to acquire RT scheduling for one of its threads this is refused with EPERM even though my service is running with full privileges. This works fine on my non-systemd system!** -A: By default, systemd places all systemd daemons in their own cgroup in the "cpu" hierarchy. Unfortunately, due to a kernel limitation, this has the effect of disallowing RT entirely for the service. See [My Service Can't Get Realtime!](MY_SERVICE_CANT_GET_REATLIME) for a longer discussion and what to do about this. +A: By default, systemd places all systemd daemons in their own cgroup in the "cpu" hierarchy. Unfortunately, due to a kernel limitation, this has the effect of disallowing RT entirely for the service. See [My Service Can't Get Realtime!](/MY_SERVICE_CANT_GET_REATLIME) for a longer discussion and what to do about this. **Q: My service is ordered after `network.target` but at boot it is still called before the network is up. What's going on?** -A: That's a long story, and that's why we have a wiki page of its own about this: [Running Services After the Network is up](NETWORK_ONLINE) +A: That's a long story, and that's why we have a wiki page of its own about this: [Running Services After the Network is up](/NETWORK_ONLINE) **Q: My systemd system always comes up with `/tmp` as a tiny `tmpfs`. How do I get rid of this?** -A: That's also a long story, please have a look on [API File Systems](API_FILE_SYSTEMS) +A: That's also a long story, please have a look on [API File Systems](/API_FILE_SYSTEMS) diff --git a/docs/GROUP_RECORD.md b/docs/GROUP_RECORD.md index aa51286d0e..c055e49d43 100644 --- a/docs/GROUP_RECORD.md +++ b/docs/GROUP_RECORD.md @@ -8,7 +8,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later # JSON Group Records Long story short: JSON Group Records are to `struct group` what -[JSON User Records](USER_RECORD) are to `struct passwd`. +[JSON User Records](/USER_RECORD) are to `struct passwd`. Conceptually, much of what applies to JSON user records also applies to JSON group records. They also consist of seven sections, with similar properties and diff --git a/docs/HACKING.md b/docs/HACKING.md index 82b6434984..de67c703f5 100644 --- a/docs/HACKING.md +++ b/docs/HACKING.md @@ -11,8 +11,8 @@ We welcome all contributions to systemd. If you notice a bug or a missing feature, please feel invited to fix it, and submit your work as a [GitHub Pull Request (PR)](https://github.com/systemd/systemd/pull/new). -Please make sure to follow our [Coding Style](CODING_STYLE) when submitting patches. -Also have a look at our [Contribution Guidelines](CONTRIBUTING). +Please make sure to follow our [Coding Style](/CODING_STYLE) when submitting patches. +Also have a look at our [Contribution Guidelines](/CONTRIBUTING). When adding new functionality, tests should be added. For shared functionality (in `src/basic/` and `src/shared/`) unit tests should be sufficient. @@ -155,7 +155,7 @@ Those are not useful when compiling for distribution and can be disabled by sett ## Sanitizers in mkosi -See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS) for more information on how to build with sanitizers enabled in mkosi. +See [Testing systemd using sanitizers](/TESTING_WITH_SANITIZERS) for more information on how to build with sanitizers enabled in mkosi. ## Fuzzers @@ -211,7 +211,7 @@ done ``` If you find a bug that impacts the security of systemd, -please follow the guidance in [CONTRIBUTING.md](CONTRIBUTING) on how to report a security vulnerability. +please follow the guidance in [CONTRIBUTING.md](/CONTRIBUTING) on how to report a security vulnerability. For more details on building fuzzers and integrating with OSS-Fuzz, visit: diff --git a/docs/HOME_DIRECTORY.md b/docs/HOME_DIRECTORY.md index 9977b42e9a..2efabaeb92 100644 --- a/docs/HOME_DIRECTORY.md +++ b/docs/HOME_DIRECTORY.md @@ -19,7 +19,7 @@ mechanism used. Inside of the home directory a file `~/.identity` contains the JSON formatted user record of the user. -It follows the format defined in [`JSON User Records`](USER_RECORD). +It follows the format defined in [`JSON User Records`](/USER_RECORD). It is recommended to bring the record into 'normalized' form(i.e. all objects should contain their fields sorted alphabetically by their key) before storing it there, though this is not required nor enforced. diff --git a/docs/INCOMPATIBILITIES.md b/docs/INCOMPATIBILITIES.md index 647d6b8800..332f1ef3d9 100644 --- a/docs/INCOMPATIBILITIES.md +++ b/docs/INCOMPATIBILITIES.md @@ -17,7 +17,7 @@ Many of the incompatibilities are specific to distribution-specific extensions o * LSB header dependency information matters. The SysV implementations on many distributions did not use the dependency information encoded in LSB init script headers, or used them only in very limited ways. Due to that they are often incorrect or incomplete. systemd however fully interprets these headers and follows them closely at runtime (and not at installation time like some implementations). * Timeouts apply to all init script operations in systemd. While on SysV systems a hanging init script could freeze the system on systemd all init script operations are subject to a timeout of 5min. * Services are executed in completely clean execution contexts, no context of the invoking user session is inherited. Not even $HOME or similar are set. Init scripts depending on these will not work correctly. -* Services cannot read from stdin, as this will be connected to /dev/null. That means interactive init scripts are not supported (i.e. Debian's X-Interactive in the LSB header is not supported either.) Thankfully most distributions do not support interaction in init scripts anyway. If you need interaction to ask disk or SSL passphrases please consider using the minimal password querying framework systemd supports. ([details](PASSWORD_AGENTS), [manual page](http://0pointer.de/public/systemd-man/systemd-ask-password.html)) +* Services cannot read from stdin, as this will be connected to /dev/null. That means interactive init scripts are not supported (i.e. Debian's X-Interactive in the LSB header is not supported either.) Thankfully most distributions do not support interaction in init scripts anyway. If you need interaction to ask disk or SSL passphrases please consider using the minimal password querying framework systemd supports. ([details](/PASSWORD_AGENTS), [manual page](http://0pointer.de/public/systemd-man/systemd-ask-password.html)) * Additional verbs for init scripts are not supported. If your init script traditionally supported additional verbs for your init script simply move them to an auxiliary script. * Additional parameters to the standard verbs (i.e. to "start", "stop" and "status") are not supported. This was an extension of SysV that never was standardized officially, and is not supported in systemd. * Overriding the "restart" verb is not supported. This verb is always implemented by systemd itself, and consists of a "stop" followed by a "start". diff --git a/docs/INITRD_INTERFACE.md b/docs/INITRD_INTERFACE.md index 64465430ce..402b6a93b7 100644 --- a/docs/INITRD_INTERFACE.md +++ b/docs/INITRD_INTERFACE.md @@ -26,7 +26,7 @@ Arch Linux initrds. * It's highly recommended that the initrd also mounts `/usr/` (if split off) as appropriate and passes it pre-mounted to the main system, to avoid the - problems described in [Booting without /usr is Broken](SEPARATE_USR_IS_BROKEN). + problems described in [Booting without /usr is Broken](/SEPARATE_USR_IS_BROKEN). * If the executable `/run/initramfs/shutdown` exists systemd will use it to jump back into the initrd on shutdown. `/run/initramfs/` should be a usable @@ -39,7 +39,7 @@ Arch Linux initrds. line options, for example `--log-level=` and similar. * Storage daemons run from the initrd should follow the guide on - [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS) + [systemd and Storage Daemons for the Root File System](/ROOT_STORAGE_DAEMONS) to survive properly from the boot initrd all the way to the point where systemd jumps back into the initrd for shutdown. @@ -66,4 +66,4 @@ systemd. Here are a few terse notes: * The switch-root operation will result in a killing spree of all running processes. Some processes might need to be excluded from that, see the guide - on [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS). + on [systemd and Storage Daemons for the Root File System](/ROOT_STORAGE_DAEMONS). diff --git a/docs/JOURNAL_EXPORT_FORMATS.md b/docs/JOURNAL_EXPORT_FORMATS.md index 83336784b1..0da5252432 100644 --- a/docs/JOURNAL_EXPORT_FORMATS.md +++ b/docs/JOURNAL_EXPORT_FORMATS.md @@ -11,7 +11,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later _Note that this document describes the binary serialization format of journals only, as used for transfer across the network. For interfacing with web technologies there's the Journal JSON Format, described below. -The binary format on disk is documented as the [Journal File Format](JOURNAL_FILE_FORMAT)._ +The binary format on disk is documented as the [Journal File Format](/JOURNAL_FILE_FORMAT)._ _Before reading on, please make sure you are aware of the [basic properties of journal entries](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html), in particular realize that they may include binary non-text data (though usually don't), and the same field might have multiple values assigned within the same entry (though usually hasn't)._ @@ -136,7 +136,7 @@ _SOURCE_REALTIME_TIMESTAMP=1423944916372858 _Note that this section describes the JSON serialization format of the journal only, as used for interfacing with web technologies. For binary transfer of journal data across the network there's the Journal Export Format described above. -The binary format on disk is documented as [Journal File Format](JOURNAL_FILE_FORMAT)._ +The binary format on disk is documented as [Journal File Format](/JOURNAL_FILE_FORMAT)._ _Before reading on, please make sure you are aware of the [basic properties of journal entries](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html), in particular realize that they may include binary non-text data (though usually don't), and the same field might have multiple values assigned within the same entry (though usually hasn't)._ diff --git a/docs/JOURNAL_FILE_FORMAT.md b/docs/JOURNAL_FILE_FORMAT.md index 50c3e32504..7d3b0396ff 100644 --- a/docs/JOURNAL_FILE_FORMAT.md +++ b/docs/JOURNAL_FILE_FORMAT.md @@ -44,7 +44,7 @@ Due to its stream-based nature it is not indexed. _Or, to put this in other words: this low-level document is probably not what you want to use as base of your project. You want our [C API](https://www.freedesktop.org/software/systemd/man/sd-journal.html) instead! And if you really don't want the C API, then you want the -[Journal Export Format or Journal JSON Format](JOURNAL_EXPORT_FORMATS) instead! +[Journal Export Format or Journal JSON Format](/JOURNAL_EXPORT_FORMATS) instead! This document is primarily for your entertainment and education. Thank you!_ diff --git a/docs/PAX_CONTROL_GROUPS.md b/docs/PAX_CONTROL_GROUPS.md index 2d13271427..4b2374a053 100644 --- a/docs/PAX_CONTROL_GROUPS.md +++ b/docs/PAX_CONTROL_GROUPS.md @@ -16,7 +16,7 @@ The cgroups tree can no longer be considered a shared resource. Instead, a management daemon of some kind needs to arbitrate access to it, and it needs to actively propagate changes between the entities it manages. More specifically, on systemd systems this management daemon is systemd itself, accessible via a number of bus APIs. This means instead of dealing directly with the low-level interfaces of the cgroup file system, please use systemd's high-level APIs as a replacement, see the -[New Control Group Interfaces](CONTROL_GROUP_INTERFACE) +[New Control Group Interfaces](/CONTROL_GROUP_INTERFACE) for details. They offer similar functionality.** Are you writing an application interfacing with the cgroups tree? diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index 441c77ccfb..e611c3bf70 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -119,9 +119,9 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy | [hostnamed](https://www.freedesktop.org/software/systemd/man/org.freedesktop.hostname1.html) | D-Bus | yes | yes | GNOME | yes | [Ubuntu](https://launchpad.net/ubuntu/+source/ubuntu-system-service), [Gentoo](http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml), [BSD](http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary) | partially | | [localed](https://www.freedesktop.org/software/systemd/man/org.freedesktop.locale1.html) | D-Bus | yes | yes | GNOME | yes | [Ubuntu](https://launchpad.net/ubuntu/+source/ubuntu-system-service), [Gentoo](http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml), [BSD](http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary) | partially | | [timedated](https://www.freedesktop.org/software/systemd/man/org.freedesktop.timedate1.html) | D-Bus | yes | yes | GNOME | yes | [Gentoo](http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml), [BSD](http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary) | partially | -| [initrd interface](INITRD_INTERFACE) | Environment, flag files | yes | yes | mkosi, dracut, ArchLinux | yes | ArchLinux | no | -| [Container interface](CONTAINER_INTERFACE) | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no | -| [Boot Loader interface](BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no | +| [initrd interface](/INITRD_INTERFACE) | Environment, flag files | yes | yes | mkosi, dracut, ArchLinux | yes | ArchLinux | no | +| [Container interface](/CONTAINER_INTERFACE) | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no | +| [Boot Loader interface](/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no | | [Service bus API](https://www.freedesktop.org/software/systemd/man/org.freedesktop.systemd1.html) | D-Bus | yes | yes | system-config-services | no | - | no | | [logind](https://www.freedesktop.org/software/systemd/man/org.freedesktop.login1.html) | D-Bus | yes | yes | GNOME | no | - | no | | [sd-bus.h API](https://www.freedesktop.org/software/systemd/man/sd-bus.html) | C Library | yes | yes | - | maybe | - | maybe | @@ -138,15 +138,15 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy | [$XDG_RUNTIME_DIR](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) | Environment | yes | yes | glib, GNOME | yes | - | no | | [$LISTEN_FDS $LISTEN_PID FD Passing](https://www.freedesktop.org/software/systemd/man/sd_listen_fds.html) | Environment | yes | yes | numerous (via sd-daemon.h) | yes | - | no | | [$NOTIFY_SOCKET Daemon Notifications](https://www.freedesktop.org/software/systemd/man/sd_notify.html) | Environment | yes | yes | a few, including udev | yes | - | no | -| [argv[0][0]='@' Logic](ROOT_STORAGE_DAEMONS) | `/proc` marking | yes | yes | mdadm | yes | - | no | +| [argv[0][0]='@' Logic](/ROOT_STORAGE_DAEMONS) | `/proc` marking | yes | yes | mdadm | yes | - | no | | [Unit file format](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) | File format | yes | yes | numerous | no | - | no | | [Network](https://www.freedesktop.org/software/systemd/man/systemd.network.html) & [Netdev file format](https://www.freedesktop.org/software/systemd/man/systemd.netdev.html) | File format | yes | yes | no | no | - | no | | [Link file format](https://www.freedesktop.org/software/systemd/man/systemd.link.html) | File format | yes | yes | no | no | - | no | -| [Journal File Format](JOURNAL_FILE_FORMAT) | File format | yes | yes | - | maybe | - | no | +| [Journal File Format](/JOURNAL_FILE_FORMAT) | File format | yes | yes | - | maybe | - | no | | [Journal Export Format](JOURNAL_EXPORT_FORMATS#journal-export-format) | File format | yes | yes | - | yes | - | no | | [Journal JSON Format](JOURNAL_EXPORT_FORMATS#journal-json-format) | File format | yes | yes | - | yes | - | no | -| [Cooperation in cgroup tree](PAX_CONTROL_GROUPS) | Treaty | yes | yes | libvirt | yes | libvirt | no | -| [Password Agents](PASSWORD_AGENTS) | Socket+Files | yes | yes | - | yes | - | no | +| [Cooperation in cgroup tree](/PAX_CONTROL_GROUPS) | Treaty | yes | yes | libvirt | yes | libvirt | no | +| [Password Agents](/PASSWORD_AGENTS) | Socket+Files | yes | yes | - | yes | - | no | | [udev multi-seat properties](https://www.freedesktop.org/software/systemd/man/sd-login.html) | udev Property | yes | yes | X11, gdm | no | - | no | | udev session switch ACL properties | udev Property | no | no | - | no | - | no | | [CLI of systemctl,...](https://www.freedesktop.org/software/systemd/man/systemctl.html) | CLI | yes | yes | numerous | no | - | no | diff --git a/docs/RANDOM_SEEDS.md b/docs/RANDOM_SEEDS.md index 2dfeae4ec5..49d33290c9 100644 --- a/docs/RANDOM_SEEDS.md +++ b/docs/RANDOM_SEEDS.md @@ -366,7 +366,7 @@ This primarily leaves two kind of systems in the cold: for an introduction why. That said, any boot loader can re-implement the logic described above, and can pass a random seed that systemd as PID 1 will then upload into the kernel's entropy pool. For details see the - [Boot Loader Interface](BOOT_LOADER_INTERFACE) documentation. + [Boot Loader Interface](/BOOT_LOADER_INTERFACE) documentation. 11. *Why not pass the boot loader random seed via kernel command line instead of as EFI variable?* diff --git a/docs/ROOT_STORAGE_DAEMONS.md b/docs/ROOT_STORAGE_DAEMONS.md index 69812c9055..41fc602772 100644 --- a/docs/ROOT_STORAGE_DAEMONS.md +++ b/docs/ROOT_STORAGE_DAEMONS.md @@ -106,7 +106,7 @@ to find a different solution to your problem._ The recommended way to distinguish between run-from-initrd and run-from-rootfs for a daemon is to check for `/etc/initrd-release` (which exists on all modern -initrd implementations, see the [initrd Interface](INITRD_INTERFACE) for +initrd implementations, see the [initrd Interface](/INITRD_INTERFACE) for details) which when exists results in `argv[0][0]` being set to `@`, and otherwise doesn't. Something like this: @@ -191,4 +191,4 @@ few additional notes for supporting these setups: program consult this blog story: [Socket Activation](https://0pointer.de/blog/projects/socket-activation.html) -* Consider having a look at the [initrd Interface of systemd](INITRD_INTERFACE). +* Consider having a look at the [initrd Interface of systemd](/INITRD_INTERFACE). diff --git a/docs/SEPARATE_USR_IS_BROKEN.md b/docs/SEPARATE_USR_IS_BROKEN.md index 71dfd5dee0..56129450d1 100644 --- a/docs/SEPARATE_USR_IS_BROKEN.md +++ b/docs/SEPARATE_USR_IS_BROKEN.md @@ -86,4 +86,4 @@ The new `/usr` could also easily be shared read-only across several systems. Such a setup would be more efficient, can provide additional security, is more flexible to use, provides saner options for custom setups, and is much simpler to setup and maintain. -For more information on this please continue to [The Case for the /usr Merge](THE_CASE_FOR_THE_USR_MERGE). +For more information on this please continue to [The Case for the /usr Merge](/THE_CASE_FOR_THE_USR_MERGE). diff --git a/docs/THE_CASE_FOR_THE_USR_MERGE.md b/docs/THE_CASE_FOR_THE_USR_MERGE.md index 1f8cbcd6cd..c603e143e4 100644 --- a/docs/THE_CASE_FOR_THE_USR_MERGE.md +++ b/docs/THE_CASE_FOR_THE_USR_MERGE.md @@ -104,7 +104,7 @@ _With all vendor-supplied OS resources in a single directory /usr they may be sh **Myth #10**: The status quo of a split /usr with mounting it without initrd is perfectly well supported right now and works. -**Fact**: A split /usr without involvement of an initrd mounting it before jumping into the root file system [hasn't worked correctly since a long time](SEPARATE_USR_IS_BROKEN). +**Fact**: A split /usr without involvement of an initrd mounting it before jumping into the root file system [hasn't worked correctly since a long time](/SEPARATE_USR_IS_BROKEN). **Myth #11**: Instead of merging / into /usr it would make a lot more sense to merge /usr into /. diff --git a/docs/TIPS_AND_TRICKS.md b/docs/TIPS_AND_TRICKS.md index a63fbb593c..208f444452 100644 --- a/docs/TIPS_AND_TRICKS.md +++ b/docs/TIPS_AND_TRICKS.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later # Tips & Tricks -Also check out the [Frequently Asked Questions](FAQ)! +Also check out the [Frequently Asked Questions](/FAQ)! ## Listing running services diff --git a/docs/USERDB_AND_DESKTOPS.md b/docs/USERDB_AND_DESKTOPS.md index 5c6720a005..b9a9eace59 100644 --- a/docs/USERDB_AND_DESKTOPS.md +++ b/docs/USERDB_AND_DESKTOPS.md @@ -20,10 +20,10 @@ A few areas where that applies are discussed below. Before reading on, please read up on the basic concepts, specifically: -* [Home Directories](HOME_DIRECTORY) -* [JSON User Records](USER_RECORD) -* [JSON Group Records](GROUP_RECORD) -* [User/Group Record Lookup API via Varlink](USER_GROUP_API) +* [Home Directories](/HOME_DIRECTORY) +* [JSON User Records](/USER_RECORD) +* [JSON Group Records](/GROUP_RECORD) +* [User/Group Record Lookup API via Varlink](/USER_GROUP_API) ## Support for Suspending Home Directory Access during System Suspend @@ -140,7 +140,7 @@ solution only. In case you wonder, there's no automatic mechanism for converting existing users registered in `/etc/passwd` or LDAP to users managed by `systemd-homed`. There's documentation for doing this manually though, see -[Converting Existing Users to systemd-homed managed Users](CONVERTING_TO_HOMED). +[Converting Existing Users to systemd-homed managed Users](/CONVERTING_TO_HOMED). ## Future Additions diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md index e996527157..d0016dbc2d 100644 --- a/docs/USER_GROUP_API.md +++ b/docs/USER_GROUP_API.md @@ -7,8 +7,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later # User/Group Record Lookup API via Varlink -JSON User/Group Records (as described in the [JSON User Records](USER_RECORD) -and [JSON Group Records](GROUP_RECORD) documents) that are defined on the +JSON User/Group Records (as described in the [JSON User Records](/USER_RECORD) +and [JSON Group Records](/GROUP_RECORD) documents) that are defined on the local system may be queried with a [Varlink](https://varlink.org/) API. This API takes both the role of what [`getpwnam(3)`](https://man7.org/linux/man-pages/man3/getpwnam.3.html) and diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md index 3b4fb4ae51..0268cc1230 100644 --- a/docs/USER_RECORD.md +++ b/docs/USER_RECORD.md @@ -16,7 +16,7 @@ Specifically: 1. [`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html) manages `human` user home directories and embeds these JSON records directly in the home directory images - (see [Home Directories](HOME_DIRECTORY) for details). + (see [Home Directories](/HOME_DIRECTORY) for details). 2. [`pam_systemd`](https://www.freedesktop.org/software/systemd/man/pam_systemd.html) processes these JSON records for users that log in, and applies various @@ -72,15 +72,15 @@ the following extensions are envisioned: 4. Default parameters for backup applications and similar Similar to JSON User Records there are also -[JSON Group Records](GROUP_RECORD) that encapsulate UNIX groups. +[JSON Group Records](/GROUP_RECORD) that encapsulate UNIX groups. JSON User Records are not suitable for storing all identity information about the user, such as binary data or large unstructured blobs of text. These parts -of a user's identity should be stored in the [Blob Directories](USER_RECORD_BLOB_DIRS). +of a user's identity should be stored in the [Blob Directories](/USER_RECORD_BLOB_DIRS). JSON User Records may be transferred or written to disk in various protocols and formats. To inquire about such records defined on the local system use the -[User/Group Lookup API via Varlink](USER_GROUP_API). User/group records may +[User/Group Lookup API via Varlink](/USER_GROUP_API). User/group records may also be dropped in number of drop-in directories as files. See [`nss-systemd(8)`](https://www.freedesktop.org/software/systemd/man/nss-systemd.html) for details. @@ -211,7 +211,7 @@ The following fields are currently defined: Takes a string with a valid UNIX user name. This field is the only mandatory field, all others are optional. Corresponds with the `pw_name` field of `struct passwd` and the `sp_namp` field of `struct spwd` (i.e. the shadow user record stored in `/etc/shadow`). -See [User/Group Name Syntax](USER_NAMES) +See [User/Group Name Syntax](/USER_NAMES) for the (relaxed) rules the various systemd components enforce on user/group names. `realm` → The "realm" a user is defined in. @@ -227,10 +227,10 @@ A user record with a realm set is never compatible (for the purpose of updates, see above) with a user record without one set, even if the `userName` field matches. `blobDirectory` → The absolute path to a world-readable copy of the user's blob -directory. See [Blob Directories](USER_RECORD_BLOB_DIRS) for more details. +directory. See [Blob Directories](/USER_RECORD_BLOB_DIRS) for more details. `blobManifest` → An object, which maps valid blob directory filenames (see -[Blob Directories](USER_RECORD_BLOB_DIRS) for requirements) to SHA256 hashes +[Blob Directories](/USER_RECORD_BLOB_DIRS) for requirements) to SHA256 hashes formatted as hex strings. This exists for the purpose of including the contents of the blob directory in the record's signature. Managers that support blob directories and utilize signed user records (like `systemd-homed`) should use diff --git a/docs/USER_RECORD_BLOB_DIRS.md b/docs/USER_RECORD_BLOB_DIRS.md index fd030e7966..efbc5cdde2 100644 --- a/docs/USER_RECORD_BLOB_DIRS.md +++ b/docs/USER_RECORD_BLOB_DIRS.md @@ -8,7 +8,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later # User Record Blob Directories The blob directories are for storing binary or unstructured data that would -otherwise be stored in [JSON User Records](USER_RECORD). For instance, +otherwise be stored in [JSON User Records](/USER_RECORD). For instance, this includes image files such as the user's avatar picture. This data, like most of the user record, will be made publicly available to the system. diff --git a/docs/WRITING_DESKTOP_ENVIRONMENTS.md b/docs/WRITING_DESKTOP_ENVIRONMENTS.md index 958eebf97a..774308df78 100644 --- a/docs/WRITING_DESKTOP_ENVIRONMENTS.md +++ b/docs/WRITING_DESKTOP_ENVIRONMENTS.md @@ -12,7 +12,7 @@ _Or: how to hook up your favorite desktop environment with logind_ systemd's logind service obsoletes ConsoleKit which was previously widely used on Linux distributions. This provides a number of new features, but also requires updating of the Desktop Environment running on it, in a few ways. -This document should be read together with [Writing Display Managers](WRITING_DISPLAY_MANAGERS) which focuses on the porting work necessary for display managers. +This document should be read together with [Writing Display Managers](/WRITING_DISPLAY_MANAGERS) which focuses on the porting work necessary for display managers. If required it is possible to implement ConsoleKit and systemd-logind support in the same desktop environment code, detecting at runtime which interface is needed. The [sd_booted()](http://www.freedesktop.org/software/systemd/man/sd_booted.html) call may be used to determine at runtime whether systemd is used. @@ -37,11 +37,11 @@ Here are the suggested changes: - If your session manager handles the special power, suspend, hibernate hardware keys or the laptop lid switch on its own it is welcome to do so, but needs to disable logind's built-in handling of these events. Take one or more of the _handle-power-key_, _handle-suspend-key_, _handle-hibernate-key_, _handle-lid-switch_ inhibitor locks for that. - See [Inhibitor Locks](INHIBITOR_LOCKS) for further details on this. + See [Inhibitor Locks](/INHIBITOR_LOCKS) for further details on this. - Before rebooting/powering-off/suspending/hibernating and when the operation is triggered by the user by clicking on some UI elements (or suchlike) it is recommended to show the list of currently active inhibitors for the operation, and ask the user to acknowledge the operation. Note that PK often allows the user to execute the operation ignoring the inhibitors. - Use logind's ListInhibitors() call to get a list of these inhibitors. See [Inhibitor Locks](INHIBITOR_LOCKS) for further details on this. + Use logind's ListInhibitors() call to get a list of these inhibitors. See [Inhibitor Locks](/INHIBITOR_LOCKS) for further details on this. - If your DE contains a process viewer of some kind ("system monitor") it's a good idea to show session, service and seat information for each process. Use sd_pid_get_session(), sd_pid_get_unit(), sd_session_get_seat() to determine these. For details see [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html). diff --git a/docs/WRITING_DISPLAY_MANAGERS.md b/docs/WRITING_DISPLAY_MANAGERS.md index 7912cfd39c..467e8a886a 100644 --- a/docs/WRITING_DISPLAY_MANAGERS.md +++ b/docs/WRITING_DISPLAY_MANAGERS.md @@ -13,7 +13,7 @@ systemd's logind service obsoletes ConsoleKit which was previously widely used o For X11 display managers the switch to logind requires a minimal amount of porting, however brings a couple of new features: true automatic multi-seat support, proper tracking of session processes, (optional) automatic killing of user processes on logout, a synchronous low-level C API and much simplification. -This document should be read together with [Writing Desktop Environments](WRITING_DESKTOP_ENVIRONMENTS) which focuses on the porting work necessary for desktop environments. +This document should be read together with [Writing Desktop Environments](/WRITING_DESKTOP_ENVIRONMENTS) which focuses on the porting work necessary for desktop environments. If required it is possible to implement ConsoleKit and systemd-logind support in the same display manager, detecting at runtime which interface is needed. The [sd_booted()](http://www.freedesktop.org/software/systemd/man/sd_booted.html) call may be used to determine at runtime whether systemd is used. diff --git a/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md b/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md index 86ef0c3f13..724d3d6daf 100644 --- a/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md +++ b/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md @@ -32,7 +32,7 @@ For more details on the APIs provided by machine consult [the bus API interface ## Guest OS Integration -As container virtualization is much less comprehensive, and the guest is less isolated from the host, there are a number of interfaces defined how the container manager can set up the environment for systemd running inside a container. These Interfaces are documented in [Container Interface of systemd](CONTAINER_INTERFACE). +As container virtualization is much less comprehensive, and the guest is less isolated from the host, there are a number of interfaces defined how the container manager can set up the environment for systemd running inside a container. These Interfaces are documented in [Container Interface of systemd](/CONTAINER_INTERFACE). VM virtualization is more comprehensive and fewer integration APIs are available. In fact there's only one: a VM manager may initialize the SMBIOS DMI field "Product UUUID" to a UUID uniquely identifying this virtual machine instance. |