shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-18 10:04:04 +03:00
Code

docs: use relative links

Browse Source 
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
This commit is contained in:
Benjamin Franzke 2022-05-18 00:05:38 +02:00
parent e4885958dc
commit 5c90c67a34
22 changed files with 92 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/ARCHITECTURE.md
View File

@ -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` 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 is configured). Thirdly, fuzzers are executed through fuzzing engines that try
to find new "interesting" inputs through coverage feedback and massive to find new "interesting" inputs through coverage feedback and massive
parallelization; see the links for oss-fuzz in [Code parallelization; see the links for oss-fuzz in [Code quality](CODE_QUALITY.md).
quality](https://systemd.io/CODE_QUALITY). For testing and debugging, fuzzers For testing and debugging, fuzzers can be executed as any other program,
can be executed as any other program, including under `valgrind` or `gdb`. including under `valgrind` or `gdb`.
## Integration Tests ## Integration Tests

2
docs/AUTOMATIC_BOOT_ASSESSMENT.md
View File

@ -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 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 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 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 However, the different components may also be used independently, and in
combination with other software, to implement similar schemes, for example with 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 other boot loaders or for non-UEFI systems. Here's a brief overview of the

10
docs/BOOT_LOADER_INTERFACE.md
View File

@ -72,7 +72,7 @@ variables. All EFI variables use the vendor UUID
* `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set. * `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set.
* `1 << 2` → The boot loader honours `LoaderEntryDefault` when set. * `1 << 2` → The boot loader honours `LoaderEntryDefault` when set.
* `1 << 3` → The boot loader honours `LoaderEntryOneShot` 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 << 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 << 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 `LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized
names for them in UIs. names for them in UIs.
1. When boot loader entries are defined through [Boot Loader 1. When boot loader entries are defined through
Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) drop-in files [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md) drop-in files
the identifier should be derived directly from the drop-in snippet name, but 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. with the `.conf` (or `.efi` in case of Type #2 entries) suffix removed.
@ -146,8 +146,8 @@ names for them in UIs.
## Links ## Links
[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)<br> [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)<br>
[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br> [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)<br>
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br> [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br> [`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) [`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)

4
docs/BOOT_LOADER_SPECIFICATION.md
View File

@ -438,8 +438,8 @@ There are a couple of items that are out of focus for this specification:
## Links ## Links
[GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table)<br> [GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table)<br>
[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)<br> [Boot Loader Interface](BOOT_LOADER_INTERFACE.md)<br>
[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br> [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)<br>
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br> [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br> [`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) [`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)

27
docs/BUILDING_IMAGES.md
View File

@ -66,15 +66,15 @@ boot. For that it's essential to:
The The
[`kernel-install(8)`](https://www.freedesktop.org/software/systemd/man/kernel-install.html) [`kernel-install(8)`](https://www.freedesktop.org/software/systemd/man/kernel-install.html)
logic used to generate [Boot Loader Specification Type logic used to generate
1](https://systemd.io/BOOT_LOADER_SPECIFICATION) entries by default uses the [Boot Loader Specification Type 1](BOOT_LOADER_SPECIFICATION.md) entries by
machine ID as stored in `/etc/machine-id` for naming boot menu entries and the default uses the machine ID as stored in `/etc/machine-id` for naming boot menu
directories in the ESP to place kernel images in. This is done in order to entries and the directories in the ESP to place kernel images in. This is done
allow multiple installations of the same OS on the same system without in order to allow multiple installations of the same OS on the same system
conflicts. However, this is problematic if the machine ID shall be generated without conflicts. However, this is problematic if the machine ID shall be
automatically on first boot: if the ID is not known before the first boot it generated automatically on first boot: if the ID is not known before the first
cannot be used to name the most basic resources required for the boot process boot it cannot be used to name the most basic resources required for the boot
to complete. process to complete.
Thus, for images that shall acquire their identity on first boot only, it is 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 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 in. The `x-systemd.growfs` mount option in `/etc/fstab` is sufficient to
enable this logic for specific mounts. Alternatively appropriately set up enable this logic for specific mounts. Alternatively appropriately set up
partitions can set GPT partition flag 59 to request this behaviour, see the partitions can set GPT partition flag 59 to request this behaviour, see the
[Discoverable Partitions [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md) for
Specification](https://systemd.io/DISCOVERABLE_PARTITIONS) for details. If details. If the file system is already grown it executes no operation.
the file system is already grown it executes no operation.
3. Similar, the `systemd-makefs@.service` and `systemd-makeswap@.service` 3. Similar, the `systemd-makefs@.service` and `systemd-makeswap@.service`
services can format file systems and swap spaces before first use, if they 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)<br> [`machine-id(5)`](https://www.freedesktop.org/software/systemd/man/machine-id.html)<br>
[`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)<br> [`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)<br>
[`os-release(5)`](https://www.freedesktop.org/software/systemd/man/os-release.html)<br> [`os-release(5)`](https://www.freedesktop.org/software/systemd/man/os-release.html)<br>
[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)<br> [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)<br>
[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br> [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md)<br>
[`mkosi`](https://github.com/systemd/mkosi)<br> [`mkosi`](https://github.com/systemd/mkosi)<br>
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br> [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html)<br> [`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html)<br>

2
docs/CODE_QUALITY.md
View File

@ -72,7 +72,7 @@ available functionality:
15. Each PR is automatically tested with [Address Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) 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). 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. for more information.
16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell). 16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell).

8
docs/CONVERTING_TO_HOMED.md
View File

@ -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: Before continuing, please read up on these basic concepts:
* [Home Directories](https://systemd.io/HOME_DIRECTORY) * [Home Directories](HOME_DIRECTORY.md)
* [JSON User Records](https://systemd.io/USER_RECORD) * [JSON User Records](USER_RECORD.md)
* [JSON Group Records](https://systemd.io/GROUP_RECORD) * [JSON Group Records](GROUP_RECORD.md)
* [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API) * [User/Group Record Lookup API via Varlink](USER_GROUP_API.md)
## Caveat ## Caveat

8
docs/CREDENTIALS.md
View File

@ -57,9 +57,9 @@ purpose. Specifically, the following features are provided:
8. Credentials are an effective way to pass parameters into services that run 8. Credentials are an effective way to pass parameters into services that run
with `RootImage=` or `RootDirectory=` and thus cannot read these resources with `RootImage=` or `RootDirectory=` and thus cannot read these resources
directly from the host directory tree. Specifically, [Portable directly from the host directory tree.
Services](https://systemd.io/PORTABLE_SERVICES) may be parameterized this Specifically, [Portable Services](PORTABLE_SERVICES.md) may be
way securely and robustly. parameterized this way securely and robustly.
9. Credentials can be binary and relatively large (though currently an overall 9. Credentials can be binary and relatively large (though currently an overall
size limit of 1M per service is enforced). 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 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 `--set-credential=` and `--load-credential=` switches implement this, in
order to pass arbitrary credentials from host to container payload. Also see 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. documentation.
2. Quite similar, qemu VMs can be invoked with `-fw_cfg 2. Quite similar, qemu VMs can be invoked with `-fw_cfg

13
docs/DISCOVERABLE_PARTITIONS.md
View File

@ -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](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) [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 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 boot loader communicates this information to the OS, by implementing the
Loader [Boot Loader Interface](BOOT_LOADER_INTERFACE.md).
Interface](https://systemd.io/BOOT_LOADER_INTERFACE).
## Defined Partition Type UUIDs ## 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 (amd64/x86_64)_ | `e7bb33fb-06cf-4e81-8273-e543b413e2e2` | ditto | ditto |
| _`/usr/` Verity Signature Partition (x86)_ | `974a71c0-de41-43c3-be5d-5c5ccd1ad2c0` | 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). | | _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. | | _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`. | | _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`. | | _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 ## Links
[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)<br> [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)<br>
[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)<br> [Boot Loader Interface](BOOT_LOADER_INTERFACE.md)<br>
[Safely Building Images](https://systemd.io/BUILDING_IMAGES)<br> [Safely Building Images](BUILDING_IMAGES.md)<br>
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br> [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br> [`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) [`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)

13
docs/ENVIRONMENT.md
View File

@ -182,8 +182,8 @@ All tools:
requested. The file contains the requested boot loader entry identifier. This 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 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 request the appropriate operation from the boot loader in an alternative
fashion. Note that by default only boot loader entries which follow the [Boot fashion. Note that by default only boot loader entries which follow the
Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) and are [Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md) and are
placed in the ESP or the Extended Boot Loader partition may be selected this 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 way. However, if a directory `/run/boot-loader-entries/` exists, the entries
are loaded from there instead. The directory should contain the usual 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 to load the embedded Verity signature data. If enabled (which is the
default), Verity root hash information and a suitable signature is default), Verity root hash information and a suitable signature is
automatically acquired from a signature partition, following the automatically acquired from a signature partition, following the
[Discoverable Partitions [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md).
Specification](https://systemd.io/DISCOVERABLE_PARTITIONS). If disabled any If disabled any such partition is ignored. Note that this only disables
such partition is ignored. Note that this only disables discovery of the root discovery of the root hash and its signature, the Verity data partition
hash and its signature, the Verity data partition itself is still searched in itself is still searched in the GPT image.
the GPT image.
* `$SYSTEMD_DISSECT_VERITY_SIGNATURE` — takes a boolean, which controls whether * `$SYSTEMD_DISSECT_VERITY_SIGNATURE` — takes a boolean, which controls whether
to validate the signature of the Verity root hash if available. If enabled to validate the signature of the Verity root hash if available. If enabled

4
docs/GROUP_RECORD.md
View File

@ -7,8 +7,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later
# JSON Group Records # JSON Group Records
Long story short: JSON Group Records are to `struct group` what [JSON User Long story short: JSON Group Records are to `struct group` what
Records](https://systemd.io/USER_RECORD) are to `struct passwd`. [JSON User Records](USER_RECORD.md) are to `struct passwd`.
Conceptually, much of what applies to JSON user records also applies to JSON 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 group records. They also consist of seven sections, with similar properties and

4
docs/HOME_DIRECTORY.md
View File

@ -18,8 +18,8 @@ mechanism used.
## General Structure ## General Structure
Inside of the home directory a file `~/.identity` contains the JSON formatted 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 user record of the user. It follows the format defined in
Records`](https://systemd.io/USER_RECORD). It is recommended to bring the [`JSON User Records`](USER_RECORD.md). It is recommended to bring the
record into 'normalized' form (i.e. all objects should contain their fields 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 sorted alphabetically by their key) before storing it there, though this is not
required nor enforced. Since the user record is cryptographically signed, the required nor enforced. Since the user record is cryptographically signed, the

12
docs/INITRD_INTERFACE.md
View File

@ -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 optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command
line options, for example `--log-level=` and similar. line options, for example `--log-level=` and similar.
* Storage daemons run from the initrd should follow the guide on [systemd * Storage daemons run from the initrd should follow the guide on
and Storage Daemons for the Root File [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md)
System](https://systemd.io/ROOT_STORAGE_DAEMONS) to survive properly from the to survive properly from the boot initrd all the way to the point where
boot initrd all the way to the point where systemd jumps back into the initrd systemd jumps back into the initrd for shutdown.
for shutdown.
One last clarification: we use the term _initrd_ very generically here One last clarification: we use the term _initrd_ very generically here
describing any kind of early boot file system, regardless whether that might be 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 * 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 processes. Some processes might need to be excluded from that, see the guide
on [systemd and Storage Daemons for the Root File on [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md).
System](https://systemd.io/ROOT_STORAGE_DAEMONS).

4
docs/JOURNAL_EXPORT_FORMATS.md
View File

@ -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. _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. 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)._ _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. _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. 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)._ _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)._

11
docs/JOURNAL_FILE_FORMAT.md
View File

@ -8,8 +8,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later
# Journal File Format # Journal File Format
_Note that this document describes the binary on-disk format of journals only. _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 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](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-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: 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 _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 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! 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 And if you really don't want the C API, then you want the
Format or Journal JSON Format](https://systemd.io/JOURNAL_EXPORT_FORMATS) instead! [Journal Export Format or Journal JSON Format](JOURNAL_EXPORT_FORMATS.md)
This document is primarily for your entertainment and education. Thank you!_ instead! This document is primarily for your entertainment and education.
Thank you!_
This document assumes you have a basic understanding of the journal concepts, 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, the properties of a journal entry and so on. If not, please go and read up,

16
docs/PORTABILITY_AND_STABILITY.md
View File

@ -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 | | [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 | | [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 | | [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 | | [initrd interface](INITRD_INTERFACE.md) | 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 | | [Container interface](CONTAINER_INTERFACE.md) | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no |
| [Boot Loader interface](https://systemd.io/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | 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 | | [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 | | [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 | | [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 | | [$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 | | [$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 | | [$NOTIFY_SOCKET Daemon Notifications](https://www.freedesktop.org/software/systemd/man/sd_notify.html) | Environment | yes | yes | a few, including udev | yes | - | no |
| [argv&#91;0&#93;&#91;0&#93;='@' Logic](https://systemd.io/ROOT_STORAGE_DAEMONS) | `/proc` marking | yes | yes | mdadm | yes | - | no | | [argv&#91;0&#93;&#91;0&#93;='@' 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 | | [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 | | [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 | | [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 File Format](JOURNAL_FILE_FORMAT.md) | 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 Export Format](JOURNAL_EXPORT_FORMATS.md#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 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 | | [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 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 | | 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 | | [CLI of systemctl,...](https://www.freedesktop.org/software/systemd/man/systemctl.html) | CLI | yes | yes | numerous | no | - | no |

4
docs/PORTABLE_SERVICES.md
View File

@ -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 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 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 single partition defined, or alternatively, a GPT partition table with a set
of properly marked partitions following the [Discoverable Partitions of properly marked partitions following the
Specification](https://systemd.io/DISCOVERABLE_PARTITIONS). [Discoverable Partitions Specification](DISCOVERABLE_PARTITIONS.md).
3. The image must at least contain one matching unit file, with the right name 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, prefix and suffix (see above). The unit file is searched in the usual paths,

4
docs/RANDOM_SEEDS.md
View File

@ -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) [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 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 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 will then upload into the kernel's entropy pool. For details see the
Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE) documentation. [Boot Loader Interface](BOOT_LOADER_INTERFACE.md) documentation.
11. *Why not pass the boot loader random seed via kernel command line instead 11. *Why not pass the boot loader random seed via kernel command line instead
of as EFI variable?* of as EFI variable?*

9
docs/ROOT_STORAGE_DAEMONS.md
View File

@ -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 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 for a daemon is to check for `/etc/initrd-release` (which exists on all modern
initrd implementations, see the [initrd initrd implementations, see the [initrd Interface](INITRD_INTERFACE.md) for
Interface](https://systemd.io/INITRD_INTERFACE) for details) which when exists details) which when exists results in `argv[0][0]` being set to `@`, and
results in `argv[0][0]` being set to `@`, and otherwise doesn't. Something like otherwise doesn't. Something like this:
this:
```c ```c
#include <unistd.h> #include <unistd.h>
@ -191,4 +190,4 @@ few additional notes for supporting these setups:
program consult this blog story: [Socket program consult this blog story: [Socket
Activation](http://0pointer.de/blog/projects/socket-activation.html) 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).

11
docs/USERDB_AND_DESKTOPS.md
View File

@ -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: Before reading on, please read up on the basic concepts, specifically:
* [Home Directories](https://systemd.io/HOME_DIRECTORY) * [Home Directories](HOME_DIRECTORY.md)
* [JSON User Records](https://systemd.io/USER_RECORD) * [JSON User Records](USER_RECORD.md)
* [JSON Group Records](https://systemd.io/GROUP_RECORD) * [JSON Group Records](GROUP_RECORD.md)
* [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API) * [User/Group Record Lookup API via Varlink](USER_GROUP_API.md)
## Support for Suspending Home Directory Access during System Suspend ## 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 In case you wonder, there's no automatic mechanism for converting existing
users registered in `/etc/passwd` or LDAP to users managed by users registered in `/etc/passwd` or LDAP to users managed by
`systemd-homed`. There's documentation for doing this manually though, see `systemd-homed`. There's documentation for doing this manually though, see
[Converting Existing Users to systemd-homed managed [Converting Existing Users to systemd-homed managed Users](CONVERTING_TO_HOMED.md).
Users](https://systemd.io/CONVERTING_TO_HOMED).
## Future Additions ## Future Additions

5
docs/USER_GROUP_API.md
View File

@ -7,9 +7,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later
# User/Group Record Lookup API via Varlink # User/Group Record Lookup API via Varlink
JSON User/Group Records (as described in the [JSON User JSON User/Group Records (as described in the [JSON User Records](USER_RECORD.md)
Records](https://systemd.io/USER_RECORD) and [JSON Group and [JSON Group Records](GROUP_RECORD.md) documents) that are defined on the
Records](https://systemd.io/GROUP_RECORD) documents) that are defined on the
local system may be queried with a [Varlink](https://varlink.org/) API. This local system may be queried with a [Varlink](https://varlink.org/) API. This
API takes both the role of what API takes both the role of what
[`getpwnam(3)`](http://man7.org/linux/man-pages/man3/getpwnam.3.html) and [`getpwnam(3)`](http://man7.org/linux/man-pages/man3/getpwnam.3.html) and

15
docs/USER_RECORD.md
View File

@ -14,8 +14,8 @@ pairs, encoded as JSON. Specifically:
1. [`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html) 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 manages `human` user home directories and embeds these JSON records
directly in the home directory images (see [Home directly in the home directory images
Directories](https://systemd.io/HOME_DIRECTORY) for details). (see [Home Directories](HOME_DIRECTORY.md) for details).
2. [`pam_systemd`](https://www.freedesktop.org/software/systemd/man/pam_systemd.html) 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 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 4. Default parameters for backup applications and similar
Similar to JSON User Records there are also [JSON Group Similar to JSON User Records there are also
Records](https://systemd.io/GROUP_RECORD) that encapsulate UNIX groups. [JSON Group Records](GROUP_RECORD.md) that encapsulate UNIX groups.
JSON User Records may be transferred or written to disk in various protocols 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 and formats. To inquire about such records defined on the local system use the
[User/Group Lookup API via [User/Group Lookup API via Varlink](USER_GROUP_API.md). User/group records may
Varlink](https://systemd.io/USER_GROUP_API). User/group records may also be also be dropped in number of drop-in directories as files. See
dropped in number of drop-in directories as files. See
[`nss-systemd(8)`](https://www.freedesktop.org/software/systemd/man/nss-systemd.html) [`nss-systemd(8)`](https://www.freedesktop.org/software/systemd/man/nss-systemd.html)
for details. 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 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 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 `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. the (relaxed) rules the various systemd components enforce on user/group names.
`realm` → The "realm" a user is defined in. This concept allows distinguishing `realm` → The "realm" a user is defined in. This concept allows distinguishing