From 5c90c67a344e05368570367009768cb058a3046d Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Wed, 18 May 2022 00:05:38 +0200 Subject: [PATCH] docs: use relative links MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Allows for links to work both on systemd.io (or forks) and when viewed on https://github.com/systemd/systemd/tree/main/docs Note that the markdown links are converted by jekyll-relative-links[1] to html. This plugin is enabled by default on github pages[2][3]. Due to a bug in jekyll-relative-links – see https://github.com/benbalter/jekyll-relative-links/issues/61 – we need to avoid line-wrapped links when using relative markdown links. [1] https://github.com/benbalter/jekyll-relative-links [2] https://github.blog/2016-12-05-relative-links-for-github-pages/ [3] https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins --- docs/ARCHITECTURE.md | 6 +++--- docs/AUTOMATIC_BOOT_ASSESSMENT.md | 2 +- docs/BOOT_LOADER_INTERFACE.md | 10 +++++----- docs/BOOT_LOADER_SPECIFICATION.md | 4 ++-- docs/BUILDING_IMAGES.md | 27 +++++++++++++-------------- docs/CODE_QUALITY.md | 2 +- docs/CONVERTING_TO_HOMED.md | 8 ++++---- docs/CREDENTIALS.md | 8 ++++---- docs/DISCOVERABLE_PARTITIONS.md | 13 ++++++------- docs/ENVIRONMENT.md | 13 ++++++------- docs/GROUP_RECORD.md | 4 ++-- docs/HOME_DIRECTORY.md | 4 ++-- docs/INITRD_INTERFACE.md | 12 +++++------- docs/JOURNAL_EXPORT_FORMATS.md | 4 ++-- docs/JOURNAL_FILE_FORMAT.md | 11 ++++++----- docs/PORTABILITY_AND_STABILITY.md | 16 ++++++++-------- docs/PORTABLE_SERVICES.md | 4 ++-- docs/RANDOM_SEEDS.md | 4 ++-- docs/ROOT_STORAGE_DAEMONS.md | 9 ++++----- docs/USERDB_AND_DESKTOPS.md | 11 +++++------ docs/USER_GROUP_API.md | 5 ++--- docs/USER_RECORD.md | 15 +++++++-------- 22 files changed, 92 insertions(+), 100 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2ae2ac98e3e..46d1d83d789 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -115,9 +115,9 @@ as a normal executable and executed for each of the input samples under with sanitizers and invoked as part of the test suite (if `-Dfuzz-tests=true` is configured). Thirdly, fuzzers are executed through fuzzing engines that try to find new "interesting" inputs through coverage feedback and massive -parallelization; see the links for oss-fuzz in [Code -quality](https://systemd.io/CODE_QUALITY). For testing and debugging, fuzzers -can be executed as any other program, including under `valgrind` or `gdb`. +parallelization; see the links for oss-fuzz in [Code quality](CODE_QUALITY.md). +For testing and debugging, fuzzers can be executed as any other program, +including under `valgrind` or `gdb`. ## Integration Tests diff --git a/docs/AUTOMATIC_BOOT_ASSESSMENT.md b/docs/AUTOMATIC_BOOT_ASSESSMENT.md index daba9502ec1..2e015eab371 100644 --- a/docs/AUTOMATIC_BOOT_ASSESSMENT.md +++ b/docs/AUTOMATIC_BOOT_ASSESSMENT.md @@ -11,7 +11,7 @@ systemd provides support for automatically reverting back to the previous version of the OS or kernel in case the system consistently fails to boot. This support is built into various of its components. When used together these components provide a complete solution on UEFI systems, built as add-on to the -[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION). +[Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md). However, the different components may also be used independently, and in combination with other software, to implement similar schemes, for example with other boot loaders or for non-UEFI systems. Here's a brief overview of the diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md index a96c081a86d..f7be50421c1 100644 --- a/docs/BOOT_LOADER_INTERFACE.md +++ b/docs/BOOT_LOADER_INTERFACE.md @@ -72,7 +72,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](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT). + * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](AUTOMATIC_BOOT_ASSESSMENT.md). * `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. @@ -115,8 +115,8 @@ the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`, `LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized names for them in UIs. -1. When boot loader entries are defined through [Boot Loader - Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) drop-in files +1. When boot loader entries are defined through + [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md) drop-in files the identifier should be derived directly from the drop-in snippet name, but with the `.conf` (or `.efi` in case of Type #2 entries) suffix removed. @@ -146,8 +146,8 @@ names for them in UIs. ## Links -[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
-[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)
+[Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)
+[Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md index 5c93a0ec724..40ec2f152b3 100644 --- a/docs/BOOT_LOADER_SPECIFICATION.md +++ b/docs/BOOT_LOADER_SPECIFICATION.md @@ -438,8 +438,8 @@ There are a couple of items that are out of focus for this specification: ## Links [GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table)
-[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)
-[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)
+[Boot Loader Interface](BOOT_LOADER_INTERFACE.md)
+[Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) diff --git a/docs/BUILDING_IMAGES.md b/docs/BUILDING_IMAGES.md index 88c7a6167de..955dd90e553 100644 --- a/docs/BUILDING_IMAGES.md +++ b/docs/BUILDING_IMAGES.md @@ -66,15 +66,15 @@ boot. For that it's essential to: The [`kernel-install(8)`](https://www.freedesktop.org/software/systemd/man/kernel-install.html) -logic used to generate [Boot Loader Specification Type -1](https://systemd.io/BOOT_LOADER_SPECIFICATION) entries by default uses the -machine ID as stored in `/etc/machine-id` for naming boot menu entries and the -directories in the ESP to place kernel images in. This is done in order to -allow multiple installations of the same OS on the same system without -conflicts. However, this is problematic if the machine ID shall be generated -automatically on first boot: if the ID is not known before the first boot it -cannot be used to name the most basic resources required for the boot process -to complete. +logic used to generate +[Boot Loader Specification Type 1](BOOT_LOADER_SPECIFICATION.md) entries by +default uses the machine ID as stored in `/etc/machine-id` for naming boot menu +entries and the directories in the ESP to place kernel images in. This is done +in order to allow multiple installations of the same OS on the same system +without conflicts. However, this is problematic if the machine ID shall be +generated automatically on first boot: if the ID is not known before the first +boot it cannot be used to name the most basic resources required for the boot +process to complete. Thus, for images that shall acquire their identity on first boot only, it is required to use a different identifier for naming boot menu entries. To allow @@ -203,9 +203,8 @@ it, then format it. in. The `x-systemd.growfs` mount option in `/etc/fstab` is sufficient to enable this logic for specific mounts. Alternatively appropriately set up partitions can set GPT partition flag 59 to request this behaviour, see the - [Discoverable Partitions - Specification](https://systemd.io/DISCOVERABLE_PARTITIONS) for details. If - the file system is already grown it executes no operation. + [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md) for + details. If the file system is already grown it executes no operation. 3. Similar, the `systemd-makefs@.service` and `systemd-makeswap@.service` services can format file systems and swap spaces before first use, if they @@ -268,8 +267,8 @@ fields. [`machine-id(5)`](https://www.freedesktop.org/software/systemd/man/machine-id.html)
[`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)
[`os-release(5)`](https://www.freedesktop.org/software/systemd/man/os-release.html)
-[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
-[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)
+[Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)
+[Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)
[`mkosi`](https://github.com/systemd/mkosi)
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
[`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html)
diff --git a/docs/CODE_QUALITY.md b/docs/CODE_QUALITY.md index 29dfdd8ae09..9057dbd2834 100644 --- a/docs/CODE_QUALITY.md +++ b/docs/CODE_QUALITY.md @@ -72,7 +72,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](https://systemd.io/TESTING_WITH_SANITIZERS) + See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS.md) for more information. 16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell). diff --git a/docs/CONVERTING_TO_HOMED.md b/docs/CONVERTING_TO_HOMED.md index 1c77a46b7e5..591b9d8c45e 100644 --- a/docs/CONVERTING_TO_HOMED.md +++ b/docs/CONVERTING_TO_HOMED.md @@ -16,10 +16,10 @@ it might be desirable to convert an existing, traditional user account to a Before continuing, please read up on these basic concepts: -* [Home Directories](https://systemd.io/HOME_DIRECTORY) -* [JSON User Records](https://systemd.io/USER_RECORD) -* [JSON Group Records](https://systemd.io/GROUP_RECORD) -* [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API) +* [Home Directories](HOME_DIRECTORY.md) +* [JSON User Records](USER_RECORD.md) +* [JSON Group Records](GROUP_RECORD.md) +* [User/Group Record Lookup API via Varlink](USER_GROUP_API.md) ## Caveat diff --git a/docs/CREDENTIALS.md b/docs/CREDENTIALS.md index d8131c4425b..766d84fdba9 100644 --- a/docs/CREDENTIALS.md +++ b/docs/CREDENTIALS.md @@ -57,9 +57,9 @@ 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](https://systemd.io/PORTABLE_SERVICES) may be parameterized this - way securely and robustly. + directly from the host directory tree. + Specifically, [Portable Services](PORTABLE_SERVICES.md) may be + parameterized this way securely and robustly. 9. Credentials can be binary and relatively large (though currently an overall size limit of 1M per service is enforced). @@ -251,7 +251,7 @@ services where they are ultimately consumed. invokes. [`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](https://systemd.io/CONTAINER_INTERFACE) + the [Container Interface](CONTAINER_INTERFACE.md) documentation. 2. Quite similar, qemu VMs can be invoked with `-fw_cfg diff --git a/docs/DISCOVERABLE_PARTITIONS.md b/docs/DISCOVERABLE_PARTITIONS.md index 5a4ff4594e2..7dff3593944 100644 --- a/docs/DISCOVERABLE_PARTITIONS.md +++ b/docs/DISCOVERABLE_PARTITIONS.md @@ -34,9 +34,8 @@ Note that the OS side of this specification is currently implemented in [systemd](https://systemd.io/) 211 and newer in the [systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) generator tool. Note that automatic discovery of the root only works if the -boot loader communicates this information to the OS, by implementing the [Boot -Loader -Interface](https://systemd.io/BOOT_LOADER_INTERFACE). +boot loader communicates this information to the OS, by implementing the +[Boot Loader Interface](BOOT_LOADER_INTERFACE.md). ## Defined Partition Type UUIDs @@ -151,7 +150,7 @@ Interface](https://systemd.io/BOOT_LOADER_INTERFACE). | _`/usr/` Verity Signature Partition (amd64/x86_64)_ | `e7bb33fb-06cf-4e81-8273-e543b413e2e2` | ditto | ditto | | _`/usr/` Verity Signature Partition (x86)_ | `974a71c0-de41-43c3-be5d-5c5ccd1ad2c0` | ditto | ditto | | _EFI System Partition_ | `c12a7328-f81f-11d2-ba4b-00a0c93ec93b` | VFAT | The ESP used for the current boot is automatically mounted to `/efi/` (or `/boot/` as fallback), unless a different partition is mounted there (possibly via `/etc/fstab`, or because the Extended Boot Loader Partition — see below — exists) or the directory is non-empty on the root disk. This partition type is defined by the [UEFI Specification](http://www.uefi.org/specifications). | -| _Extended Boot Loader Partition_ | `bc13c2ff-59e6-4262-a352-b275fd6f7172` | Typically VFAT | The Extended Boot Loader Partition (XBOOTLDR) used for the current boot is automatically mounted to `/boot/`, unless a different partition is mounted there (possibly via `/etc/fstab`) or the directory is non-empty on the root disk. This partition type is defined by the [Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION). | +| _Extended Boot Loader Partition_ | `bc13c2ff-59e6-4262-a352-b275fd6f7172` | Typically VFAT | The Extended Boot Loader Partition (XBOOTLDR) used for the current boot is automatically mounted to `/boot/`, unless a different partition is mounted there (possibly via `/etc/fstab`) or the directory is non-empty on the root disk. This partition type is defined by the [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md). | | _Swap_ | `0657fd6d-a4ab-43c4-84e5-0933c84b4f4f` | Swap, optionally in LUKS | All swap partitions on the disk containing the root partition are automatically enabled. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/swap`. This partition type predates the Discoverable Partitions Specification. | | _Home Partition_ | `933ac7e1-2eb4-4f13-b844-0e14e2aef915` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/home/`. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/home`. | | _Server Data Partition_ | `3b8f8425-20e0-4f3b-907f-1a25a76f98e8` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/srv/`. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/srv`. | @@ -410,9 +409,9 @@ The `gdisk` tool (from version 1.0.5 onward) and its variants (`sgdisk`, ## Links -[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
-[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)
-[Safely Building Images](https://systemd.io/BUILDING_IMAGES)
+[Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)
+[Boot Loader Interface](BOOT_LOADER_INTERFACE.md)
+[Safely Building Images](BUILDING_IMAGES.md)
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 711e14a7c56..7caa9518145 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -182,8 +182,8 @@ All tools: requested. The file contains the requested boot loader entry identifier. This file may be checked for by services run during system shutdown in order to request the appropriate operation from the boot loader in an alternative - fashion. Note that by default only boot loader entries which follow the [Boot - Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) and are + fashion. Note that by default only boot loader entries which follow the + [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md) and are placed in the ESP or the Extended Boot Loader partition may be selected this way. However, if a directory `/run/boot-loader-entries/` exists, the entries are loaded from there instead. The directory should contain the usual @@ -364,11 +364,10 @@ disk images with `--image=` or similar: to load the embedded Verity signature data. If enabled (which is the default), Verity root hash information and a suitable signature is automatically acquired from a signature partition, following the - [Discoverable Partitions - Specification](https://systemd.io/DISCOVERABLE_PARTITIONS). If disabled any - such partition is ignored. Note that this only disables discovery of the root - hash and its signature, the Verity data partition itself is still searched in - the GPT image. + [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md). + If disabled any such partition is ignored. Note that this only disables + discovery of the root hash and its signature, the Verity data partition + itself is still searched in the GPT image. * `$SYSTEMD_DISSECT_VERITY_SIGNATURE` — takes a boolean, which controls whether to validate the signature of the Verity root hash if available. If enabled diff --git a/docs/GROUP_RECORD.md b/docs/GROUP_RECORD.md index 44666930dbc..381036994e1 100644 --- a/docs/GROUP_RECORD.md +++ b/docs/GROUP_RECORD.md @@ -7,8 +7,8 @@ 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](https://systemd.io/USER_RECORD) are to `struct passwd`. +Long story short: JSON Group Records are to `struct group` what +[JSON User Records](USER_RECORD.md) 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/HOME_DIRECTORY.md b/docs/HOME_DIRECTORY.md index 680b2ed237f..0aafce2b69b 100644 --- a/docs/HOME_DIRECTORY.md +++ b/docs/HOME_DIRECTORY.md @@ -18,8 +18,8 @@ mechanism used. ## General Structure 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`](https://systemd.io/USER_RECORD). It is recommended to bring the +user record of the user. It follows the format defined in +[`JSON User Records`](USER_RECORD.md). 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. Since the user record is cryptographically signed, the diff --git a/docs/INITRD_INTERFACE.md b/docs/INITRD_INTERFACE.md index 3898840c56b..1e9493cd8a6 100644 --- a/docs/INITRD_INTERFACE.md +++ b/docs/INITRD_INTERFACE.md @@ -37,11 +37,10 @@ interfaces are currently used by dracut and the ArchLinux initrds. optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command 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](https://systemd.io/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. +* Storage daemons run from the initrd should follow the guide on + [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md) + to survive properly from the boot initrd all the way to the point where + systemd jumps back into the initrd for shutdown. One last clarification: we use the term _initrd_ very generically here describing any kind of early boot file system, regardless whether that might be @@ -70,5 +69,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](https://systemd.io/ROOT_STORAGE_DAEMONS). + on [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md). diff --git a/docs/JOURNAL_EXPORT_FORMATS.md b/docs/JOURNAL_EXPORT_FORMATS.md index 441872b088c..5b4517dca1f 100644 --- a/docs/JOURNAL_EXPORT_FORMATS.md +++ b/docs/JOURNAL_EXPORT_FORMATS.md @@ -9,7 +9,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](https://systemd.io/JOURNAL_FILE_FORMAT/)._ +The binary format on disk is documented as the [Journal File Format](JOURNAL_FILE_FORMAT.md)._ _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)._ @@ -122,7 +122,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](https://systemd.io/JOURNAL_FILE_FORMAT)._ +The binary format on disk is documented as [Journal File Format](JOURNAL_FILE_FORMAT.md)._ _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 0036ee45d68..61a27a96996 100644 --- a/docs/JOURNAL_FILE_FORMAT.md +++ b/docs/JOURNAL_FILE_FORMAT.md @@ -8,8 +8,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later # Journal File Format _Note that this document describes the binary on-disk format of journals only. -For interfacing with web technologies there's the [Journal JSON Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format). -For transfer of journal data across the network there's the [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format)._ +For interfacing with web technologies there's the [Journal JSON Format](JOURNAL_EXPORT_FORMATS.md#journal-json-format). +For transfer of journal data across the network there's the [Journal Export Format](JOURNAL_EXPORT_FORMATS.md#journal-export-format)._ The systemd journal stores log data in a binary format with several features: @@ -45,9 +45,10 @@ 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](https://systemd.io/JOURNAL_EXPORT_FORMATS) instead! -This document is primarily for your entertainment and education. Thank you!_ +And if you really don't want the C API, then you want the +[Journal Export Format or Journal JSON Format](JOURNAL_EXPORT_FORMATS.md) +instead! This document is primarily for your entertainment and education. +Thank you!_ This document assumes you have a basic understanding of the journal concepts, the properties of a journal entry and so on. If not, please go and read up, diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index bfe5b6aa892..6328b44d7a2 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -83,9 +83,9 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy | [hostnamed](https://www.freedesktop.org/wiki/Software/systemd/hostnamed) | 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/wiki/Software/systemd/localed) | 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/wiki/Software/systemd/timedated) | 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](https://systemd.io/INITRD_INTERFACE) | Environment, flag files | yes | yes | dracut, ArchLinux | yes | ArchLinux | no | -| [Container interface](https://systemd.io/CONTAINER_INTERFACE) | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no | -| [Boot Loader interface](https://systemd.io/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no | +| [initrd interface](INITRD_INTERFACE.md) | Environment, flag files | yes | yes | dracut, ArchLinux | yes | ArchLinux | no | +| [Container interface](CONTAINER_INTERFACE.md) | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no | +| [Boot Loader interface](BOOT_LOADER_INTERFACE.md) | EFI variables | yes | yes | gummiboot | yes | - | no | | [Service bus API](https://www.freedesktop.org/wiki/Software/systemd/dbus) | D-Bus | yes | yes | system-config-services | no | - | no | | [logind](https://www.freedesktop.org/wiki/Software/systemd/logind) | D-Bus | yes | yes | GNOME | no | - | no | | [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, polkit, ... | no | - | no | @@ -95,15 +95,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](https://systemd.io/ROOT_STORAGE_DAEMONS) | `/proc` marking | yes | yes | mdadm | yes | - | no | +| [argv[0][0]='@' Logic](ROOT_STORAGE_DAEMONS.md) | `/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](https://systemd.io/JOURNAL_FILE_FORMAT) | File format | yes | yes | - | maybe | - | no | -| [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format) | File format | yes | yes | - | yes | - | no | -| [Journal JSON Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format) | File format | yes | yes | - | yes | - | no | +| [Journal File Format](JOURNAL_FILE_FORMAT.md) | File format | yes | yes | - | maybe | - | no | +| [Journal Export Format](JOURNAL_EXPORT_FORMATS.md#journal-export-format) | File format | yes | yes | - | yes | - | no | +| [Journal JSON Format](JOURNAL_EXPORT_FORMATS.md#journal-json-format) | File format | yes | yes | - | yes | - | no | | [Cooperation in cgroup tree](https://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups) | Treaty | yes | yes | libvirt | yes | libvirt | no | -| [Password Agents](https://systemd.io/PASSWORD_AGENTS) | Socket+Files | yes | yes | - | yes | - | no | +| [Password Agents](PASSWORD_AGENTS.md) | 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/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md index 7f67be2b086..20acbeae033 100644 --- a/docs/PORTABLE_SERVICES.md +++ b/docs/PORTABLE_SERVICES.md @@ -168,8 +168,8 @@ requirements are made for an image that can be attached/detached with must be a raw disk image either containing only one, naked file system, or an image with a partition table understood by the Linux kernel with only a single partition defined, or alternatively, a GPT partition table with a set - of properly marked partitions following the [Discoverable Partitions - Specification](https://systemd.io/DISCOVERABLE_PARTITIONS). + of properly marked partitions following the + [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md). 3. The image must at least contain one matching unit file, with the right name prefix and suffix (see above). The unit file is searched in the usual paths, diff --git a/docs/RANDOM_SEEDS.md b/docs/RANDOM_SEEDS.md index 1c389730399..b6b900acdbf 100644 --- a/docs/RANDOM_SEEDS.md +++ b/docs/RANDOM_SEEDS.md @@ -387,8 +387,8 @@ This primarily leaves two kind of systems in the cold: [systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html) 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](https://systemd.io/BOOT_LOADER_INTERFACE) documentation. + will then upload into the kernel's entropy pool. For details see the + [Boot Loader Interface](BOOT_LOADER_INTERFACE.md) 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 6ab158cd2bf..3b19ea79d18 100644 --- a/docs/ROOT_STORAGE_DAEMONS.md +++ b/docs/ROOT_STORAGE_DAEMONS.md @@ -108,10 +108,9 @@ 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](https://systemd.io/INITRD_INTERFACE) for details) which when exists -results in `argv[0][0]` being set to `@`, and otherwise doesn't. Something like -this: +initrd implementations, see the [initrd Interface](INITRD_INTERFACE.md) for +details) which when exists results in `argv[0][0]` being set to `@`, and +otherwise doesn't. Something like this: ```c #include @@ -191,4 +190,4 @@ few additional notes for supporting these setups: program consult this blog story: [Socket Activation](http://0pointer.de/blog/projects/socket-activation.html) -* Consider having a look at the [initrd Interface of systemd](https://systemd.io/INITRD_INTERFACE). +* Consider having a look at the [initrd Interface of systemd](INITRD_INTERFACE.md). diff --git a/docs/USERDB_AND_DESKTOPS.md b/docs/USERDB_AND_DESKTOPS.md index e6097eab1ee..7017d8d86ed 100644 --- a/docs/USERDB_AND_DESKTOPS.md +++ b/docs/USERDB_AND_DESKTOPS.md @@ -21,10 +21,10 @@ are recommended. A few areas where that applies are discussed below. Before reading on, please read up on the basic concepts, specifically: -* [Home Directories](https://systemd.io/HOME_DIRECTORY) -* [JSON User Records](https://systemd.io/USER_RECORD) -* [JSON Group Records](https://systemd.io/GROUP_RECORD) -* [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API) +* [Home Directories](HOME_DIRECTORY.md) +* [JSON User Records](USER_RECORD.md) +* [JSON Group Records](GROUP_RECORD.md) +* [User/Group Record Lookup API via Varlink](USER_GROUP_API.md) ## Support for Suspending Home Directory Access during System Suspend @@ -147,8 +147,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](https://systemd.io/CONVERTING_TO_HOMED). +[Converting Existing Users to systemd-homed managed Users](CONVERTING_TO_HOMED.md). ## Future Additions diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md index ccd9f9b3d88..3078dfd8ecd 100644 --- a/docs/USER_GROUP_API.md +++ b/docs/USER_GROUP_API.md @@ -7,9 +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](https://systemd.io/USER_RECORD) and [JSON Group -Records](https://systemd.io/GROUP_RECORD) documents) that are defined on the +JSON User/Group Records (as described in the [JSON User Records](USER_RECORD.md) +and [JSON Group Records](GROUP_RECORD.md) 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)`](http://man7.org/linux/man-pages/man3/getpwnam.3.html) and diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md index da911d5e73a..53081029445 100644 --- a/docs/USER_RECORD.md +++ b/docs/USER_RECORD.md @@ -14,8 +14,8 @@ pairs, encoded as JSON. 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](https://systemd.io/HOME_DIRECTORY) for details). + directly in the home directory images + (see [Home Directories](HOME_DIRECTORY.md) 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 @@ -71,14 +71,13 @@ the following extensions are envisioned: 4. Default parameters for backup applications and similar -Similar to JSON User Records there are also [JSON Group -Records](https://systemd.io/GROUP_RECORD) that encapsulate UNIX groups. +Similar to JSON User Records there are also +[JSON Group Records](GROUP_RECORD.md) that encapsulate UNIX groups. 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](https://systemd.io/USER_GROUP_API). User/group records may also be -dropped in number of drop-in directories as files. See +[User/Group Lookup API via Varlink](USER_GROUP_API.md). 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. @@ -215,7 +214,7 @@ object. The following fields are currently defined: UNIX user name. This field is the only mandatory field, all others are optional. Corresponds with the `pw_name` field of 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](https://systemd.io/USER_NAMES) for +`/etc/shadow`). See [User/Group Name Syntax](USER_NAMES.md) for the (relaxed) rules the various systemd components enforce on user/group names. `realm` → The "realm" a user is defined in. This concept allows distinguishing -- 2.39.2