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
* `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.
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
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).
# 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
## 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.
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.
### 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.
### 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
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
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)
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
[`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
# 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?**
**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)
# 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
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.
## 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
```
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:
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.
* 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".
* 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
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.
* 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).
_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)._
_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)._
_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!_
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?
| [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 |
| [$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 |
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?*
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:
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).
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).
**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 /.
# Tips & Tricks
-Also check out the [Frequently Asked Questions](FAQ)!
+Also check out the [Frequently Asked Questions](/FAQ)!
## Listing running services
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
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
# 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
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
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.
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.
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
# 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.
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.
- 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).
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.
## 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.
projects / thirdparty / systemd.git / commitdiff
