Consult our [NEWS file](NEWS) for information about what's new in the most recent systemd versions.
-Please see the [Code Map](docs/ARCHITECTURE.md) for information about this repository's layout and content.
+Please see the [Code Map](docs/_contributing/ARCHITECTURE.md) for information about this repository's layout and content.
-Please see the [Hacking guide](docs/HACKING.md) for information on how to hack on systemd and test your modifications.
+Please see the [Hacking guide](docs/_contributing/HACKING.md) for information on how to hack on systemd and test your modifications.
-Please see our [Contribution Guidelines](docs/CONTRIBUTING.md) for more information about filing GitHub Issues and posting GitHub Pull Requests.
+Please see our [Contribution Guidelines](docs/_contributing/CONTRIBUTING.md) for more information about filing GitHub Issues and posting GitHub Pull Requests.
-When preparing patches for systemd, please follow our [Coding Style Guidelines](docs/CODING_STYLE.md).
+When preparing patches for systemd, please follow our [Coding Style Guidelines](docs/_contributing/CODING_STYLE.md).
If you are looking for support, please contact our [mailing list](https://lists.freedesktop.org/mailman/listinfo/systemd-devel), join our [IRC channel #systemd on libera.chat](https://web.libera.chat/#systemd) or [Matrix channel](https://matrix.to/#/#systemd-project:matrix.org)
* `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.md).
+ * `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.
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.md) 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
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](CONTAINER_INTERFACE.md) 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
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.md) 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?*
baseurl: "" # the subpath of your site, e.g. /blog/
url: "https://systemd.io" # the base hostname & protocol for your site
-permalink: /:title/
-
# Build settings
markdown: kramdown
+
+collections:
+ concepts:
+ title: 'Concepts'
+ output: true
+ contributing:
+ title: 'Contributing'
+ output: true
+ userdocs:
+ output: true
+ title: 'Documentation for Users and Administrators'
+ booting:
+ title: 'Booting'
+ output: true
+ interfaces:
+ title: 'Interfaces'
+ output: true
+ networking:
+ title: 'Networking'
+ output: true
+ groups:
+ title: 'Users, Groups and Home Directories'
+ output: true
+ devdocs:
+ title: 'Documentation for Developers'
+ output: 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
to find new "interesting" inputs through coverage feedback and massive
-parallelization; see the links for oss-fuzz in [Code quality](CODE_QUALITY.md).
+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`.
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.md)
+ See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS)
for more information.
16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell).
## Security vulnerability reports
-See [reporting of security vulnerabilities](SECURITY.md).
+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.md) 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.md) 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. If you are a member of the systemd project on GitHub, remove the `reviewed/needs-rework`/`ci-fails/needs-rework`/`needs-rebase` labels.
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.md) when submitting
-patches. Also have a look at our [Contribution Guidelines](CONTRIBUTING.md).
+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. The general
strongly recommended. If that is not possible, integration tests in `test/` are
encouraged.
-Please also have a look at our list of [code quality tools](CODE_QUALITY.md) we
+Please also have a look at our list of [code quality tools](CODE_QUALITY) we
have setup for systemd, to ensure our codebase stays in good shape.
Please always test your work before submitting a PR. For many of the components
## Sanitizers in mkosi
-See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS.md) for more information
+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.md) on how to report a security vulnerability.
+guidance in [CONTRIBUTING.md](CONTRIBUTING) on how to report a security vulnerability.
For more details on building fuzzers and integrating with OSS-Fuzz, visit:
[
- { "category": "Project", "title": "mkosi Project - Build Bespoke OS Images", "url": "https://mkosi.systemd.io/" },
- { "category": "Project", "title": "Brand", "url": "https://brand.systemd.io/" },
- { "category": "Project", "title": "Releases", "url": "https://github.com/systemd/systemd/releases" },
- { "category": "Project", "title": "GitHub Project Page", "url": "https://github.com/systemd/systemd" },
- { "category": "Project", "title": "Issues", "url": "https://github.com/systemd/systemd/issues" },
- { "category": "Project", "title": "Pull Requests", "url": "https://github.com/systemd/systemd/pulls" },
- { "category": "Project", "title": "Mailing List", "url": "https://lists.freedesktop.org/mailman/listinfo/systemd-devel" },
- { "category": "Manual Pages", "title": "Index", "url": "https://www.freedesktop.org/software/systemd/man/" },
- { "category": "Manual Pages", "title": "Directives", "url": "https://www.freedesktop.org/software/systemd/man/systemd.directives.html" }
+ {
+ "category": "Manual Pages",
+ "title": "Index",
+ "url": "https://www.freedesktop.org/software/systemd/man/"
+ },
+ {
+ "category": "Manual Pages",
+ "title": "Directives",
+ "url": "https://www.freedesktop.org/software/systemd/man/systemd.directives.html"
+ },
+ {
+ "category": "Publications",
+ "title": "Article in The H",
+ "url": "http://www.h-online.com/open/features/Control-Centre-The-systemd-Linux-init-system-1565543.html"
+ },
+ {
+ "category": "Publications",
+ "title": "Article in The H, Part 2",
+ "url": "http://www.h-online.com/open/features/Booting-up-Tools-and-tips-for-systemd-1570630.html"
+ },
+ {
+ "category": "Publications",
+ "title": "Bê-á-bá do systemd #1 (Brazilian Portuguese)",
+ "url": "https://community.ibm.com/community/user/legacy"
+ },
+ {
+ "category": "Publications",
+ "title": "Bê-á-bá do systemd #2 (Brazilian Portuguese)",
+ "url": "https://community.ibm.com/community/user/legacy"
+ },
+ {
+ "category": "Publications",
+ "title": "Bê-á-bá do systemd #3 (Brazilian Portuguese)",
+ "url": "https://community.ibm.com/community/user/legacy"
+ },
+ {
+ "category": "Publications",
+ "title": "Bê-á-bá do systemd #4 (Brazilian Portuguese)",
+ "url": "https://community.ibm.com/community/user/legacy"
+ },
+ {
+ "category": "Publications",
+ "title": "Bê-á-bá do systemd #5 (Brazilian Portuguese)",
+ "url": "https://community.ibm.com/community/user/legacy"
+ },
+ {
+ "category": "Publications",
+ "title": "Bê-á-bá do systemd #6 (Brazilian Portuguese)",
+ "url": "https://community.ibm.com/community/user/legacy"
+ },
+ {
+ "category": "Publications",
+ "title": "Évolutions techniques de systemd (French)",
+ "url": "https://linuxfr.org/news/evolutions-techniques-de-systemd"
+ },
+ {
+ "category": "Publications",
+ "title": "RHEL7 docs",
+ "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/chap-managing_services_with_systemd"
+ },
+ {
+ "category": "Publications",
+ "title": "SUSE White Paper on systemd",
+ "url": "https://www.suse.com/media/white-paper/systemd_in_suse_linux_enterprise_12_white_paper.pdf"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about kdbus at linux.conf.au 2014",
+ "url": "https://mirror.linux.org.au/pub/linux.conf.au/2014/Friday/104-D-Bus_in_the_kernel_-_Lennart_Poettering.mp4"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at the Red Hat Summit 2013",
+ "url": "https://access.redhat.com/videos/403833"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about the journal at Devconf 2013",
+ "url": "https://www.youtube.com/watch?v=i4CACB7paLc"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about recent developments at Devconf 2013",
+ "url": "https://www.youtube.com/watch?v=_rrpjYD373A"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at FOSDEM 2013",
+ "url": "https://ftp.fau.de/fosdem/2013/maintracks/Janson/systemd,_Two_Years_Later.webm"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at FOSDEM 2013 (Slides)",
+ "url": "https://0pointer.de/public/systemd-fosdem2013.pdf"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at FOSS.in 2012",
+ "url": "https://www.youtube.com/watch?v=_2aa34Uzr3c"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at OSEC Barcamp 2012",
+ "url": "https://www.youtube.com/watch?v=9UnEV9SPuw8"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at FOSDEM 2011",
+ "url": "https://www.youtube.com/watch?v=TyMLi8QF6sw"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at linux.conf.au 2011",
+ "url": "http://linuxconfau.blip.tv/file/4696791/"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at linux.conf.au 2011 (Slides)",
+ "url": "https://0pointer.de/public/systemd-lca2011.pdf"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Interview about systemd at golem.de (German)",
+ "url": "https://video.golem.de/oss/4823/interview-mit-lennart-poettering-entwickler-systemd.html"
+ },
+ {
+ "category": "Videos for Users and Administrators",
+ "title": "Presentation about systemd at OSworld 2014 (systemd cheat-sheet) (Polish)",
+ "url": "https://www.youtube.com/watch?v=tU3HJVUPMyw"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#01: Verifying Bootup",
+ "url": "https://0pointer.de/blog/projects/systemd-for-admins-1.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#02: Which Service Owns Which Processes?",
+ "url": "https://0pointer.de/blog/projects/systemd-for-admins-2.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#03: How Do I Convert A SysV Init Script Into A systemd Service File?",
+ "url": "https://0pointer.de/blog/projects/systemd-for-admins-3.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#04: Killing Services",
+ "url": "https://0pointer.de/blog/projects/systemd-for-admins-4.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#05: The Three Levels of \"Off\"",
+ "url": "https://0pointer.de/blog/projects/three-levels-of-off"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#06: Changing Roots",
+ "url": "https://0pointer.de/blog/projects/changing-roots.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#07: The Blame Game",
+ "url": "https://0pointer.de/blog/projects/blame-game.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#08: The New Configuration Files",
+ "url": "https://0pointer.de/blog/projects/the-new-configuration-files"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#09: On /etc/sysconfig and /etc/default",
+ "url": "https://0pointer.de/blog/projects/on-etc-sysinit.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#10: Instantiated Services",
+ "url": "https://0pointer.de/blog/projects/instances.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#11: Converting inetd Services",
+ "url": "https://0pointer.de/blog/projects/inetd.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#12: Securing Your Services",
+ "url": "https://0pointer.de/blog/projects/security.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#13: Log and Service Status",
+ "url": "https://0pointer.de/blog/projects/systemctl-journal.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#14: The Self-Explanatory Boot",
+ "url": "https://0pointer.de/blog/projects/self-documented-boot.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#15: Watchdogs",
+ "url": "https://0pointer.de/blog/projects/watchdog.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#16: Gettys on Serial Consoles (and Elsewhere)",
+ "url": "https://0pointer.de/blog/projects/serial-console.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#17: Using the Journal",
+ "url": "https://0pointer.de/blog/projects/journalctl.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#18: Managing Resources",
+ "url": "https://0pointer.de/blog/projects/resources.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#19: Detecting Virtualization",
+ "url": "https://0pointer.de/blog/projects/detect-virt.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#20: Socket Activated Internet Services and OS Containers",
+ "url": "https://0pointer.de/blog/projects/socket-activated-containers.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "#21: Container Integration",
+ "url": "https://0pointer.net/blog/systemd-for-administrators-part-xxi.html"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "A Russian translation",
+ "url": "https://wiki.opennet.ru/Systemd_%D0%B4%D0%BB%D1%8F_%D0%B0%D0%B4%D0%BC%D0%B8%D0%BD%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%BE%D1%80%D0%BE%D0%B2"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "A more complete Russian translation (PDF)",
+ "url": "http://www2.kangran.su/~nnz/pub/s4a/s4a_latest.pdf"
+ },
+ {
+ "category": "The systemd for Administrators Blog Series",
+ "title": "A Vietnamese translation",
+ "url": "https://archlinuxvn.org/doc/systemd/#lp"
+ },
+ {
+ "category": "The systemd for Developers Series",
+ "title": "#1: Socket Activation",
+ "url": "https://0pointer.de/blog/projects/socket-activation.html"
+ },
+ {
+ "category": "The systemd for Developers Series",
+ "title": "#2: Socket Activation (Part 2)",
+ "url": "https://0pointer.de/blog/projects/socket-activation2.html"
+ },
+ {
+ "category": "The systemd for Developers Series",
+ "title": "#3: Logging to the Journal",
+ "url": "https://0pointer.de/blog/projects/journal-submit.html"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Go Bindings for the Journal API, socket activation and DBUS",
+ "url": "https://github.com/coreos/go-systemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "PHP Bindings for the Journal APIs",
+ "url": "https://github.com/systemd/php-systemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Lua Bindinds for systemd APIs",
+ "url": "https://github.com/daurnimator/lua-systemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Node.JS bindings for the Journal APIs",
+ "url": "https://www.fourkitchens.com/blog/2012/09/25/nodejs-extension-systemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Node.JS support for systemd Socket Activation",
+ "url": "https://www.npmjs.com/package/systemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Node.JS wrapper for sd_notify",
+ "url": "https://www.npmjs.com/package/sd-notify"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Node.JS wrapper for sd_notify (repo)",
+ "url": "https://github.com/systemd/node-sd-notify"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Experimental Qt bindings",
+ "url": "https://github.com/ilpianista/libsystemd-qt"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Haskell socket activation",
+ "url": "https://hackage.haskell.org/package/socket-activation"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Haskell Journal API",
+ "url": "https://hackage.haskell.org/package/libsystemd-journal"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Ruby bindings for the Journal APIs",
+ "url": "https://github.com/ledbettj/systemd-journal"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Ruby bindings for the systemd D-Bus APIs",
+ "url": "https://github.com/nathwill/ruby-dbus-systemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Erlang bindings for the Journal APIs",
+ "url": "https://github.com/systemd/ejournald"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Erlang journald backend for Lager",
+ "url": "https://github.com/travelping/lager_journald_backend"
+ },
+ {
+ "category": "Related Packages",
+ "title": "Perl bindings for the Journal APIs",
+ "url": "https://metacpan.org/release/LKUNDRAK/Log-Journald-0.10"
+ },
+ {
+ "category": "Related Packages",
+ "title": "GLib bindings",
+ "url": "https://github.com/tcbrindle/systemd-glib"
+ },
+ {
+ "category": "Related Packages",
+ "title": "python-systemd",
+ "url": "https://www.freedesktop.org/software/systemd/python-systemd/index.html"
+ },
+ {
+ "category": "Related Packages",
+ "title": "pystemd",
+ "url": "https://github.com/systemd/pystemd"
+ },
+ {
+ "category": "Related Packages",
+ "title": "C++ bindings for sd-bus",
+ "url": "https://github.com/Kistler-Group/sdbus-cpp/"
+ },
+ {
+ "category": "Documentation for Developers - external links",
+ "title": "On /etc/os-release",
+ "url": "http://0pointer.de/blog/projects/os-release.html"
+ },
+ {
+ "category": "Documentation for Developers - external links",
+ "title": "Control Groups vs. Control Groups",
+ "url": "http://0pointer.de/blog/projects/cgroups-vs-cgroups.html"
+ },
+ {
+ "category": "Documentation for Developers - external links",
+ "title": "The 30 Biggest Myths about systemd",
+ "url": "http://0pointer.de/blog/projects/the-biggest-myths.html"
+ },
+ {
+ "category": "Documentation for Developers - external links",
+ "title": "Introduction to systemd in French",
+ "url": "http://lea-linux.org/documentations/Systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Fedora packages",
+ "url": "https://packages.fedoraproject.org/pkgs/systemd/systemd/"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Fedora sources",
+ "url": "https://src.fedoraproject.org/rpms/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Fedora bugtracker",
+ "url": "https://bugzilla.redhat.com/buglist.cgi?list_id=565273&classification=Fedora&query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=ON_DEV&bug_status=ON_QA&bug_status=VERIFIED&bug_status=RELEASE_PENDING&bug_status=POST&component=systemd&product=Fedora"
+ },
+ {
+ "category": "The various distributions",
+ "title": "openSUSE packages",
+ "url": "https://build.opensuse.org/package/show/Base:System/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "openSUSE instructions",
+ "url": "http://en.opensuse.org/SDB:Systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "openSUSE bugtracker",
+ "url": "https://bugzilla.novell.com/buglist.cgi?short_desc=systemd&field0-0-0=product&type0-0-1=substring&field0-0-1=component&classification=openSUSE&value0-0-2=systemd&query_based_on=systemd&query_format=advanced&type0-0-3=substring&field0-0-3=status_whiteboard&value0-0-3=systemd&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=NEEDINFO&bug_status=REOPENED&short_desc_type=allwordssubstr&field0-0-2=short_desc&value0-0-1=systemd&type0-0-0=substring&value0-0-0=systemd&type0-0-2=substring&known_name=systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Arch Linux packages",
+ "url": "https://www.archlinux.org/packages/core/x86_64/systemd/"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Arch Linux wiki",
+ "url": "https://wiki.archlinux.org/index.php/Systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Arch Linux bugtracker",
+ "url": "https://bugs.archlinux.org/?project=1&cat%5B%5D=31&string=systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Debian packages",
+ "url": "http://packages.debian.org/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Debian wiki",
+ "url": "http://wiki.debian.org/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Debian bugtracker",
+ "url": "http://bugs.debian.org/cgi-bin/pkgreport.cgi?ordering=normal;archive=0;src=systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Ubuntu packages",
+ "url": "https://launchpad.net/ubuntu/+source/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Ubuntu wiki",
+ "url": "https://wiki.ubuntu.com/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Mageia packages",
+ "url": "http://svnweb.mageia.org/packages/cauldron/systemd/current/"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Mageia bugtracker",
+ "url": "https://bugs.mageia.org/buglist.cgi?field0-0-0=cf_rpmpkg&query_format=advanced&bug_status=NEW&bug_status=UNCONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&type0-0-0=substring&value0-0-0=systemd&component=RPM%20Packages&product=Mageia"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Gentoo packages",
+ "url": "http://packages.gentoo.org/package/sys-apps/systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Gentoo wiki",
+ "url": "http://wiki.gentoo.org/wiki/Systemd"
+ },
+ {
+ "category": "The various distributions",
+ "title": "Gentoo bugtracker",
+ "url": "https://bugs.gentoo.org/buglist.cgi?quicksearch=systemd"
+ }
]
--- /dev/null
+[
+ {
+ "category": "Project",
+ "title": "mkosi Project - Build Bespoke OS Images",
+ "url": "https://mkosi.systemd.io/"
+ },
+ {
+ "collection": "project",
+ "title": "Brand",
+ "url": "https://brand.systemd.io/"
+ },
+ {
+ "collection": "project",
+ "title": "Mailing List",
+ "url": "https://lists.freedesktop.org/mailman/listinfo/systemd-devel"
+ },
+ {
+ "collection": "project",
+ "title": "Mastodon",
+ "url": "https://mastodon.social/@pid_eins"
+ },
+ {
+ "collection": "project",
+ "title": "Releases",
+ "url": "https://github.com/systemd/systemd/releases"
+ },
+ {
+ "collection": "project",
+ "title": "GitHub Project Page",
+ "url": "https://github.com/systemd/systemd"
+ },
+ {
+ "collection": "project",
+ "title": "Issues",
+ "url": "https://github.com/systemd/systemd/issues"
+ },
+ {
+ "collection": "project",
+ "title": "Pull Requests",
+ "url": "https://github.com/systemd/systemd/pulls"
+ }
+]
--- /dev/null
+---
+title: Autopkgtest - Defining tests for Debian packages
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Test description
+
+Full system integration/acceptance testing is done through [autopkgtests](https://salsa.debian.org/ci-team/autopkgtest/-/blob/master/doc/README.package-tests.rst). These test the actual installed binary distribution packages. They are run in QEMU or containers and thus can do intrusive and destructive things such as installing arbitrary packages, modifying arbitrary files in the system (including grub boot parameters), rebooting, or loading kernel modules.
+
+The tests for systemd are defined in the [Debian package's debian/tests](https://salsa.debian.org/systemd-team/systemd/tree/master/debian/tests) directory. For validating a pull request, the Debian package is built using the unpatched code from that PR (via the [checkout-upstream](https://salsa.debian.org/systemd-team/systemd/blob/master/debian/extra/checkout-upstream) script), and the tests run against these built packages. Note that some tests which check Debian specific behaviour are skipped in "test upstream" mode.
+
+# Infrastructure
+
+systemd's GitHub project has webhooks that trigger autopkgtests on Ubuntu 18.04 LTS on three architectures:
+
+* i386: 32 bit x86, little endian, QEMU (OpenStack cloud instance)
+* amd64: 64 bit x86, little endian, QEMU (OpenStack cloud instance)
+* arm64: 64 bit ARM, little endian, QEMU (OpenStack cloud instance)
+* s390x: 64 bit IBM z/Series, big endian, LXC (this architecture is not yet available in Canonical's OpenStack and thus skips some tests)
+
+Please see the [Ubuntu CI infrastructure](https://wiki.ubuntu.com/ProposedMigration/AutopkgtestInfrastructure) documentation for details about how this works.
+
+# Manually retrying/triggering tests on the infrastructure
+
+The current tests are fairly solid by now, but rarely they fail on infrastructure/network issues or race conditions. If you encounter these, please notify @iainlane in the GitHub PR for debugging/fixing those -- transient infrastructure issues are supposed to be detected automatically, and tests auto-retry on those; and flaky tests should of course be fixed properly. But sometimes it is useful to trigger tests on a different Ubuntu release too, for example to test a PR on a newer kernel or against current build/binary dependencies (cgroup changes, util-linux, gcc, etc.).
+
+This can be done using the generic [retry-github-test](https://git.launchpad.net/autopkgtest-cloud/tree/charms/focal/autopkgtest-cloud-worker/autopkgtest-cloud/tools/retry-github-test) script from [Ubuntu's autopkgtest infrastructure](https://git.launchpad.net/autopkgtest-cloud): you need the parameterized URL from the [configured webhooks](https://github.com/systemd/systemd/settings/hooks) and the shared secret (Ubuntu's CI needs to restrict access to avoid DoSing and misuse).
+
+You can use Martin Pitt's [retry-gh-systemd-test](https://piware.de/gitweb/?p=bin.git;a=blob;f=retry-gh-systemd-test) shell wrapper around retry-github-test for that. You need to adjust the path where you put retry-github-test and the file with the shared secret, then you can call it like this:
+
+```sh
+$ retry-gh-systemd-test <#PR> <architecture> [release]
+```
+
+where `release` defaults to `bionic` (aka Ubuntu 18.04 LTS). For example:
+
+```sh
+$ retry-gh-systemd-test 1234 amd64
+$ retry-gh-systemd-test 2345 s390x cosmic
+```
+
+Please make sure to not trigger unknown [releases](https://launchpad.net/ubuntu/+series) or architectures as they will cause a pending test on the PR which never gets finished.
+
+# Test the code from the PR locally
+
+As soon as a test on the infrastructure finishes, the "Details" link in the PR "checks" section will point to the `log.gz` log. You can download the individual test log, built .debs, and other artifacts that tests leave behind (some dump a complete journal or the udev database on failure) by replacing `/log.gz` with `/artifacts.tar.gz` in that URL. You can then unpack the tarball and use `sudo dpkg -iO binaries/*.deb` to install the debs from the PR into an Ubuntu VM of the same release/architecture for manually testing a PR.
+
+# Run autopkgtests locally
+
+Preparations:
+
+* Get autopkgtest:
+ ```sh
+ git clone https://salsa.debian.org/ci-team/autopkgtest.git
+ ```
+
+* Install necessary dependencies; on Debian/Ubuntu you can simply run `sudo apt install autopkgtest` (instead of the above cloning), on Fedora do `yum install qemu-kvm dpkg-perl`
+
+* Build a test image based on Ubuntu cloud images for the desired release/arch:
+ ```sh
+ autopkgtest/tools/autopkgtest-buildvm-ubuntu-cloud -r bionic -a amd64
+ ```
+
+ This will build `autopkgtest-bionic-amd64.img`. This is normally being used through the `autopkgtest` command (see below), but you can boot this normally in QEMU (using `-snapshot` is highly recommended) to interactively poke around; this provides a easy throw-away test environment.
+
+
+The most basic mode of operation is to run the tests for the current distro packages:
+
+```sh
+autopkgtest/runner/autopkgtest systemd -- qemu autopkgtest-bionic-amd64.img
+```
+
+But autopkgtest allows lots of [different modes](https://salsa.debian.org/ci-team/autopkgtest/-/blob/master/doc/README.running-tests.rst) and [options](http://manpages.ubuntu.com/autopkgtest), like running a shell on failure (`-s`), running a single test only (`--test-name`), running the tests from a local checkout of the Debian source tree (possibly with modifications to the test) instead of from the distribution source, or running QEMU with more than one CPU (check the [autopkgtest-virt-qemu manpage](http://manpages.ubuntu.com/autopkgtest-virt-qemu).
+
+A common use case is to check out the Debian packaging git for getting/modifying the tests locally:
+
+```sh
+git clone https://salsa.debian.org/systemd-team/systemd.git /tmp/systemd-debian/
+```
+
+and running these against the binaries from a PR (see above), running only the `logind` test, getting a shell on failure, showing the boot output, and running with 2 CPUs:
+
+```sh
+autopkgtest/runner/autopkgtest --test-name logind /tmp/binaries/*.deb /tmp/systemd-debian/ -s -- \
+ qemu --show-boot --cpus 2 /srv/vm/autopkgtest-bionic-amd64.img
+```
+
+# Contact
+
+For troubles with the infrastructure, please notify [iainlane](https://github.com/iainlane) in the affected PR.
--- /dev/null
+---
+title: Backports
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Backports
+
+The upstream systemd git repo at [https://github.com/systemd/systemd](https://github.com/systemd/systemd) only contains the main systemd branch that progresses at a quick pace, continuously bringing both bugfixes and new features. Distributions usually prefer basing their releases on stabilized versions branched off from this, that receive the bugfixes but not the features.
+
+## Stable Branch Repository
+
+Stable branches are available from [https://github.com/systemd/systemd-stable](https://github.com/systemd/systemd-stable).
+
+Stable branches are started for certain releases of systemd and named after them, e.g. v208-stable. Stable branches are typically managed by distribution maintainers on an as needed basis. For example v208 has been chosen for stable as several distributions are shipping this version and the official/upstream cycle of v208-v209 was a long one due to kdbus work. If you are using a particular version and find yourself backporting several patches, you may consider pushing a stable branch here for that version so others can benefit. Please contact us if you are interested.
+
+The following types of commits are cherry-picked onto those branches:
+
+* bugfixes
+* documentation updates, when relevant to this version
+* hardware database additions, especially the keymap updates
+* small non-conflicting features deemed safe to add in a stable release
+
+Please try to ensure that anything backported to the stable repository is done with the `git cherry-pick -x` option such that text stating the original SHA1 is added into the commit message. This makes it easier to check where the code came from (as sometimes it is necessary to add small fixes as new code due to the upstream refactors that are deemed too invasive to backport as a stable patch.
--- /dev/null
+---
+title: systemd-boot UEFI Boot Manager
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# systemd-boot UEFI Boot Manager
+
+systemd-boot is a UEFI boot manager which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu.
+
+systemd-boot operates on the EFI System Partition (ESP) only. Configuration file fragments, kernels, initrds, other EFI images need to reside on the ESP. Linux kernels need to be built with CONFIG\_EFI\_STUB to be able to be directly executed as an EFI image.
+
+systemd-boot reads simple and entirely generic boot loader configuration files; one file per boot loader entry to select from. All files need to reside on the ESP.
+
+Pressing the Space key (or most other keys actually work too) during bootup will show an on-screen menu with all configured loader entries to select from. Pressing Enter on the selected entry loads and starts the EFI image.
+
+If no timeout is configured, which is the default setting, and no key pressed during bootup, the default entry is executed right away.
+
+
+
+All configuration files are expected to be 7-bit ASCII or valid UTF8. The loader configuration file understands the following keywords:
+
+| Config |
+|---------|------------------------------------------------------------|
+| default | pattern to select the default entry in the list of entries |
+| timeout | timeout in seconds for how long to show the menu |
+
+
+The entry configuration files understand the following keywords:
+
+| Entry |
+|--------|------------------------------------------------------------|
+| title | text to show in the menu |
+| version | version string to append to the title when the title is not unique |
+| machine-id | machine identifier to append to the title when the title is not unique |
+| efi | executable EFI image |
+| options | options to pass to the EFI image / kernel command line |
+| linux | linux kernel image (systemd-boot still requires the kernel to have an EFI stub) |
+| initrd | initramfs image (systemd-boot just adds this as option initrd=) |
+
+
+Examples:
+```
+/boot/loader/loader.conf
+timeout 3
+default 6a9857a393724b7a981ebb5b8495b9ea-*
+
+/boot/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf
+title Fedora 19 (Rawhide)
+version 3.8.0-2.fc19.x86_64
+machine-id 6a9857a393724b7a981ebb5b8495b9ea
+linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
+initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd
+options root=UUID=f8f83f73-df71-445c-87f7-31f70263b83b quiet
+
+/boot/loader/entries/custom-kernel.conf
+title My kernel
+efi /bzImage
+options root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08
+
+/boot/loader/entries/custom-kernel-initrd.conf
+title My kernel with initrd
+linux /bzImage
+initrd /initrd.img
+options root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08 quiet`
+```
+
+
+While the menu is shown, the following keys are active:
+
+| Keys |
+|--------|------------------------------------------------------------|
+| Up/Down | Select menu entry |
+| Enter | boot the selected entry |
+| d | select the default entry to boot (stored in a non-volatile EFI variable) |
+| t/T | adjust the timeout (stored in a non-volatile EFI variable) |
+| e | edit the option line (kernel command line) for this bootup to pass to the EFI image |
+| Q | quit |
+| v | show the systemd-boot and UEFI version |
+| P | print the current configuration to the console |
+| h | show key mapping |
+
+Hotkeys to select a specific entry in the menu, or when pressed during bootup to boot the entry right-away:
+
+
+
+| Keys |
+|--------|------------------------------------------------------------|
+| l | Linux |
+| w | Windows |
+| a | OS X |
+| s | EFI Shell |
+| 1-9 | number of entry |
+
+Some EFI variables control the loader or exported the loaders state to the started operating system. The vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` and the variable names are supposed to be shared across all loaders implementations which follow this scheme of configuration:
+
+| EFI Variables |
+|---------------|------------------------|-------------------------------|
+| LoaderEntryDefault | entry identifier to select as default at bootup | non-volatile |
+| LoaderConfigTimeout | timeout in seconds to show the menu | non-volatile |
+| LoaderEntryOneShot | entry identifier to select at the next and only the next bootup | non-volatile |
+| LoaderDeviceIdentifier | list of identifiers of the volume the loader was started from | volatile |
+| LoaderDevicePartUUID | partition GPT UUID of the ESP systemd-boot was executed from | volatile |
+
+
+Links:
+
+[https://github.com/systemd/systemd](https://github.com/systemd/systemd)
+
+[http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/](http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/)
+
--- /dev/null
+---
+title: Journal Message Catalogs
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Journal Message Catalogs
+
+Starting with 196 systemd includes a message catalog system which allows augmentation on display of journal log messages with short explanation texts, keyed off the MESSAGE\_ID= field of the entry. Many important log messages generated by systemd itself have message catalog entries. External packages can easily provide catalog data for their own messages.
+
+The message catalog has a number of purposes:
+
+* Provide the administrator, user or developer with further information about the issue at hand, beyond the actual message text
+* Provide links to further documentation on the topic of the specific message
+* Provide native language explanations for English language system messages
+* Provide links for support forums, hotlines or other contacts
+
+## Format
+
+Message catalog source files are simple text files that follow an RFC822 inspired format. To get an understanding of the format [here's an example file](http://cgit.freedesktop.org/systemd/systemd/plain/catalog/systemd.catalog), which includes entries for many important messages systemd itself generates. On installation of a package that includes message catalogs all installed message catalog source files get compiled into a binary index, which is then used to look up catalog data.
+
+journalctl's `-x` command line parameter may be used to augment on display journal log messages with message catalog data when browsing. `journalctl --list-catalog` may be used to print a list of all known catalog entries.
+
+To register additional catalog entries, packages may drop (text) catalog files into /usr/lib/systemd/catalog/ with a suffix of .catalog. The files are not accessed directly when needed, but need to be built into a binary index file with `journalctl --update-catalog`.
+
+Here's an example how a single catalog entry looks like in the text source format. Multiple of these may be listed one after the other per catalog source file:
+
+```
+-- fc2e22bc6ee647b6b90729ab34a250b1
+Subject: Process @COREDUMP_PID@ (@COREDUMP_COMM@) dumped core
+Defined-By: systemd
+Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel
+Documentation: man:core(5)
+Documentation: http://www.freedesktop.org/wiki/Software/systemd/catalog/@MESSAGE_ID@
+
+Process @COREDUMP_PID@ (@COREDUMP_COMM@) crashed and dumped core.
+
+This usually indicates a programming error in the crashing program and
+should be reported to its vendor as a bug.
+```
+
+
+The text format of the .catalog files is as follows:
+
+* Simple, UTF-8 text files, with usual line breaks at 76 chars. URLs and suchlike where line-breaks are undesirable may use longer lines. As catalog files need to be usable on text consoles it is essential that the 76 char line break rule is otherwise followed for human readable text.
+* Lines starting with `#` are ignored, and may be used for comments.
+* The files consist of a series of entries. For each message ID (in combination with a locale) only a single entry may be defined. Every entry consists of:
+ * A separator line beginning with `-- `, followed by a hexadecimal message ID formatted as lower case ASCII string. Optionally, the message ID may be suffixed by a space and a locale identifier, such as `de` or `fr\_FR`, if i10n is required.
+ * A series of entry headers, in RFC822-style but not supporting continuation lines. Some header fields may appear more than once per entry. The following header fields are currently known (but additional fields may be added later):
+ * Subject: A short, one-line human readable description of the message
+ * Defined-By: Who defined this message. Usually a package name or suchlike
+ * Support: A URI for getting further support. This can be a web URL or a telephone number in the tel:// namespace
+ * Documentation: URIs for further user, administrator or developer documentation on the log entry. URIs should be listed in order of relevance, the most relevant documentation first.
+ * An empty line
+ * The actual catalog entry payload, as human readable prose. Multiple paragraphs may be separated by empty lines. The prose should first describe the message and when it occurs, possibly followed by recommendations how to deal with the message and (if it is an error message) correct the problem at hand. This message text should be readable by users and administrators. Information for developers should be stored externally instead, and referenced via a Documentation= header field.
+* When a catalog entry is printed on screen for a specific log entry simple variable replacements are applied. Journal field names enclosed in @ will be replaced by their values, if such a field is available in an entry. If such a field is not defined in an entry the enclosing @ will be dropped but the variable name is kept. See [systemd's own message catalog](http://cgit.freedesktop.org/systemd/systemd/plain/catalog/systemd.catalog) for a complete example for a catalog file.
+
+## Adding Message Catalog Support to Your Program
+
+Note that the message catalog is only available for messages generated with the MESSAGE\_ID= journal meta data field, as this is need to find the right entry for a message. For more information on the MESSAGE\_ID= journal entry field see [systemd.journal-fields(7)](http://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html).
+
+To add message catalog entries for log messages your application generates, please follow the following guidelines:
+
+* Use the [native Journal logging APIs](http://0pointer.de/blog/projects/journal-submit.html) to generate your messages, and define message IDs for all messages you want to add catalog entries for. You may use `journalctl --new-id128` to allocate new message IDs.
+* Write a catalog entry file for your messages and ship them in your package and install them to `/usr/lib/systemd/catalog/` (if you package your software with RPM use `%_journalcatalogdir`)
+* Ensure that after installation of your application's RPM/DEB "`journalctl --update-catalog`" is executed, in order to update the binary catalog index. (if you package your software with RPM use the `%journal_catalog_update` macro to achieve that.)
+
--- /dev/null
+---
+title: New Control Group Interfaces
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# The New Control Group Interfaces
+
+> _aka "I want to make use of kernel cgroups, how do I do this in the new world order?"_
+
+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](http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups/) 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. On systemd systems PID 1 takes this role and hence needs to provide APIs for clients to take benefit of the control groups functionality of the kernel. Note that services running on systemd systems may manage their own subtrees of the cgroups tree, as long as they explicitly turn on delegation mode for them (see below).
+
+That means explicitly, that:
+
+1. The root control group may only be written to by systemd (PID 1). Services that create and manipulate control groups in the top level cgroup are in direct conflict with the kernel's requirement that each control group should have a single-writer only.
+2. Services must set Delegate=yes for the units they intend to manage subcgroups of. If they create and manipulate cgroups outside of units that have Delegate=yes set, they violate the access contract for control groups.
+
+For a more high-level background story, please have a look at this [Linux Foundation News Story](http://www.linuxfoundation.org/news-media/blogs/browse/2013/08/all-about-linux-kernel-cgroup%E2%80%99s-redesign).
+
+### Why this all again?
+
+- Objects placed in the same level of the cgroup tree frequently need to propagate properties from one to each other. For example, when using the "cpu" controller for one object then all objects on the same level need to do the same, otherwise the entire cgroup of the first object will be scheduled against the individual processes of the others, thus giving the first object a drastic malus on scheduling if it uses many processes.
+- Similar, some properties also require propagation up the tree.
+- The tree needs to be refreshed/built in scheduled steps as devices show up/go away as controllers like "blkio" or "devices" refer to devices via major/minor device node indexes, which are not fixed but determined only as a device appears.
+- The tree also needs refreshing/rebuilding as new services are installed/started/instantiated/stopped/uninstalled.
+- Many of the cgroup attributes are too low-level as API. For example, the major/minor device interface in order to be useful requires a userspace component for translating stable device paths into major/minor at the right time.
+- By unifying the cgroup logic under a single arbiter it is possible to write tools that can manage all objects the system contains, including services, virtual machines containers and whatever else applications register.
+- By unifying the cgroup logic under a single arbiter a good default that encompasses all kinds of objects may be shipped, thus making manual configuration unnecessary to take benefit of basic resource control.
+
+systemd through its "unit" concept already implements a dependency network between objects where propagation can take place and contains a powerful execution queue. Also, a major part of the objects resources need to be controlled for are already systemd objects, most prominently the services systemd manages.
+
+### Why is this not managed by a component independent of systemd?
+
+Well, as mentioned above, a dependency network between objects, usable for propagation, combined with a powerful execution engine is basically what systemd _is_. Since cgroups management requires precisely this it is an obvious choice to simply implement this in systemd itself.
+
+Implementing a similar propagation/dependency network with execution scheduler outside of systemd in an independent "cgroup" daemon would basically mean reimplementing systemd a second time. Also, accessing such an external service from PID 1 for managing other services would result in cyclic dependencies between PID 1 which would need this functionality to manage the cgroup service which would only be available however after that service finished starting up. Such cyclic dependencies can certainly be worked around, but make such a design complex.
+
+### I don't use systemd, what does this mean for me?
+
+Nothing. This page is about systemd's cgroups APIs. If you don't use systemd then the kernel cgroup rework will probably affect you eventually, but a different component will be the single writer userspace daemon managing the cgroup tree, with different APIs. Note that the APIs described here expose a lot of systemd-specific concepts and hence are unlikely to be available outside of systemd systems.
+
+### I want to write cgroup code that should work on both systemd systems and others (such as Ubuntu), what should I do?
+
+On systemd systems use the systemd APIs as described below. At this time we are not aware of any component that would take the cgroup managing role on Upstart/sysvinit systems, so we cannot help you with this. Sorry.
+
+### 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](http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups/) 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.
+
+## systemd's Resource Control Concepts
+
+Systemd provides three unit types that are useful for the purpose of resource control:
+
+- [_Services_](http://www.freedesktop.org/software/systemd/man/systemd.service.html) encapsulate a number of processes that are started and stopped by systemd based on configuration. Services are named in the style of `quux.service`.
+- [_Scopes_](http://www.freedesktop.org/software/systemd/man/systemd.scope.html) encapsulate a number of processes that are started and stopped by arbitrary processes via fork(), and then registered at runtime with PID1. Scopes are named in the style of `wuff.scope`.
+- [_Slices_](http://www.freedesktop.org/software/systemd/man/systemd.slice.html) may be used to group a number of services and scopes together in a hierarchial tree. Slices do not contain processes themselves, but the services and slices contained in them do. Slices are named in the style of `foobar-waldo.slice`, where the path to the location of the slice in the tree is encoded in the name with "-" as separator for the path components (`foobar-waldo.slice` is hence a subslice of `foobar.slice`). There's one special slices defined, `-.slice`, which is the root slice of all slices (`foobar.slice` is hence subslice of `-.slice`). This is similar how in regular file paths, "/" denotes the root directory.
+
+Service, scope and slice units directly map to objects in the cgroup tree. When these units are activated they each map to directly (modulo some character escaping) to cgroup paths built from the unit names. For example, a service `quux.service` in a slice `foobar-waldo.slice` is found in the cgroup `foobar.slice/foobar-waldo.slice/quux.service/`.
+
+Services, scopes and slices may be created freely by the administrator or dynamically by programs. However by default the OS defines a number of built-in services that are necessary to start-up the system. Also, there are four slices defined by default: first of all the root slice `-.slice` (as mentioned above), but also `system.slice`, `machine.slice`, `user.slice`. By default all system services are placed in the first slice, all virtual machines and containers in the second, and user sessions in the third. However, this is just a default, and the administrator my freely define new slices and assign services and scopes to them. Also note that all login sessions automatically are placed in an individual scope unit, as are VM and container processes. Finally, all users logging in will also get an implicit slice of their own where all the session scopes are placed.
+
+Here's an example how the cgroup tree could look like (as generated with `systemd-cgls(1)`, see below):
+
+```
+├─user.slice
+│ └─user-1000.slice
+│ ├─session-18.scope
+│ │ ├─703 login -- lennart
+│ │ └─773 -bash
+│ ├─session-1.scope
+│ │ ├─ 518 gdm-session-worker [pam/gdm-autologin]
+│ │ ├─ 540 gnome-session
+│ │ ├─ 552 dbus-launch --sh-syntax --exit-with-session
+│ │ ├─ 553 /bin/dbus-daemon --fork --print-pid 4 --print-address 6 --session
+│ │ ├─ 589 /usr/libexec/gvfsd
+│ │ ├─ 593 /usr/libexec//gvfsd-fuse -f /run/user/1000/gvfs
+│ │ ├─ 598 /usr/libexec/gnome-settings-daemon
+│ │ ├─ 617 /usr/bin/gnome-keyring-daemon --start --components=gpg
+│ │ ├─ 630 /usr/bin/pulseaudio --start
+│ │ ├─ 726 /usr/bin/gnome-shell
+│ │ ├─ 728 syndaemon -i 1.0 -t -K -R
+│ │ ├─ 736 /usr/libexec/gsd-printer
+│ │ ├─ 742 /usr/libexec/dconf-service
+│ │ ├─ 798 /usr/libexec/mission-control-5
+│ │ ├─ 802 /usr/libexec/goa-daemon
+│ │ ├─ 823 /usr/libexec/gvfsd-metadata
+│ │ ├─ 866 /usr/libexec/gvfs-udisks2-volume-monitor
+│ │ ├─ 880 /usr/libexec/gvfs-gphoto2-volume-monitor
+│ │ ├─ 886 /usr/libexec/gvfs-afc-volume-monitor
+│ │ ├─ 891 /usr/libexec/gvfs-mtp-volume-monitor
+│ │ ├─ 895 /usr/libexec/gvfs-goa-volume-monitor
+│ │ ├─ 999 /usr/libexec/telepathy-logger
+│ │ ├─ 1076 /usr/libexec/gnome-terminal-server
+│ │ ├─ 1079 gnome-pty-helper
+│ │ ├─ 1080 bash
+│ │ ├─ 1134 ssh-agent
+│ │ ├─ 1137 gedit l
+│ │ ├─ 1160 gpg-agent --daemon --write-env-file
+│ │ ├─ 1371 /usr/lib64/firefox/firefox
+│ │ ├─ 1729 systemd-cgls
+│ │ ├─ 1929 bash
+│ │ ├─ 2057 emacs src/login/org.freedesktop.login1.policy.in
+│ │ ├─ 2060 /usr/libexec/gconfd-2
+│ │ ├─29634 /usr/libexec/gvfsd-http --spawner :1.5 /org/gtk/gvfs/exec_spaw/0
+│ │ └─31416 bash
+│ └─user@1000.service
+│ ├─532 /usr/lib/systemd/systemd --user
+│ └─541 (sd-pam)
+└─system.slice
+ ├─1 /usr/lib/systemd/systemd --system --deserialize 22
+ ├─sshd.service
+ │ └─29701 /usr/sbin/sshd -D
+ ├─udisks2.service
+ │ └─743 /usr/lib/udisks2/udisksd --no-debug
+ ├─colord.service
+ │ └─727 /usr/libexec/colord
+ ├─upower.service
+ │ └─633 /usr/libexec/upowerd
+ ├─wpa_supplicant.service
+ │ └─488 /usr/sbin/wpa_supplicant -u -f /var/log/wpa_supplicant.log -c /etc/wpa_supplicant/wpa_supplicant.conf -u -f /var/log/wpa_supplicant.log -P /var/run/wpa_supplicant.pid
+ ├─bluetooth.service
+ │ └─463 /usr/sbin/bluetoothd -n
+ ├─polkit.service
+ │ └─443 /usr/lib/polkit-1/polkitd --no-debug
+ ├─alsa-state.service
+ │ └─408 /usr/sbin/alsactl -s -n 19 -c -E ALSA_CONFIG_PATH=/etc/alsa/alsactl.conf --initfile=/lib/alsa/init/00main rdaemon
+ ├─systemd-udevd.service
+ │ └─253 /usr/lib/systemd/systemd-udevd
+ ├─systemd-journald.service
+ │ └─240 /usr/lib/systemd/systemd-journald
+ ├─rtkit-daemon.service
+ │ └─419 /usr/libexec/rtkit-daemon
+ ├─rpcbind.service
+ │ └─475 /sbin/rpcbind -w
+ ├─cups.service
+ │ └─731 /usr/sbin/cupsd -f
+ ├─avahi-daemon.service
+ │ ├─417 avahi-daemon: running [delta.local]
+ │ └─424 avahi-daemon: chroot helper
+ ├─dbus.service
+ │ ├─418 /bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation
+ │ └─462 /usr/sbin/modem-manager
+ ├─accounts-daemon.service
+ │ └─416 /usr/libexec/accounts-daemon
+ ├─systemd-ask-password-wall.service
+ │ └─434 /usr/bin/systemd-tty-ask-password-agent --wall
+ ├─systemd-logind.service
+ │ └─415 /usr/lib/systemd/systemd-logind
+ ├─ntpd.service
+ │ └─429 /usr/sbin/ntpd -u ntp:ntp -g
+ ├─rngd.service
+ │ └─412 /sbin/rngd -f
+ ├─libvirtd.service
+ │ └─467 /usr/sbin/libvirtd
+ ├─irqbalance.service
+ │ └─411 /usr/sbin/irqbalance --foreground
+ ├─crond.service
+ │ └─421 /usr/sbin/crond -n
+ ├─NetworkManager.service
+ │ ├─ 410 /usr/sbin/NetworkManager --no-daemon
+ │ ├─1066 /sbin/dhclient -d -sf /usr/libexec/nm-dhcp-client.action -pf /var/run/dhclient-enp0s20u2.pid -lf /var/lib/NetworkManager/dhclient-35c8218b-9e45-4b1f-b79e-22334f687340-enp0s20u2.lease -cf /var/lib/NetworkManager/dhclient-enp0s20u2.conf enp0s20u2
+ │ └─1070 /sbin/dhclient -d -sf /usr/libexec/nm-dhcp-client.action -pf /var/run/dhclient-enp0s26u1u4i2.pid -lf /var/lib/NetworkManager/dhclient-f404f1ca-ccfe-4957-aead-dec19c126dea-enp0s26u1u4i2.lease -cf /var/lib/NetworkManager/dhclient-enp0s26u1u4i2.conf enp0s26u1u4i2
+ └─gdm.service
+ ├─420 /usr/sbin/gdm
+ ├─449 /usr/libexec/gdm-simple-slave --display-id /org/gnome/DisplayManager/Displays/_0
+ └─476 /usr/bin/Xorg :0 -background none -verbose -auth /run/gdm/auth-for-gdm-pJjwsi/database -seat seat0 -nolisten tcp vt1
+```
+
+As you can see, services and scopes contain process and are placed in slices, and slices do not contain processes of their own. Also note that the special "-.slice" is not shown as it is implicitly identified with the root of the entire tree.
+
+Resource limits may be set on services, scopes and slices the same way. All active service, scope and slice units may easily be viewed with the "systemctl" command. The hierarchy of services and scopes in the slice tree may be viewed with the "systemd-cgls" command.
+
+Service and slice units may be configured via unit files on disk, or alternatively be created dynamically at runtime via API calls to PID 1. Scope units may only be created at runtime via API calls to PID 1, but not from unit files on disk. Units that are created dynamically at runtime via API calls are called _transient_ units. Transient units exist only during runtime and are released automatically as soon as they finished/got deactivated or the system is rebooted.
+
+If a service/slice is configured via unit files on disk the resource controls may be configured with the settings documented in [systemd.resource-control(5)](http://www.freedesktop.org/software/systemd/man/systemd.resource-control.html). While the unit are started they may be reconfigured for services/slices/scopes (with changes applying instantly) with the a command line such as:
+
+```
+# systemctl set-property httpd.service CPUShares=500 MemoryLimit=500M
+```
+
+This will make these changes persistently, so that after the next reboot they are automatically applied right when the services are first started. By passing the `--runtime` switch the changes can alternatively be made in a volatile way so that they are lost on the next reboot.
+
+Note that the number of cgroup attributes currently exposed as unit properties is limited. This will be extended later on, as their kernel interfaces are cleaned up. For example cpuset or freezer are currently not exposed at all due to the broken inheritance semantics of the kernel logic. Also, migrating units to a different slice at runtime is not supported (i.e. altering the Slice= property for running units) as the kernel currently lacks atomic cgroup subtree moves.
+
+(Note that the resource control settings are actually also available on mount, swap and socket units. This is because they may also involve processes run for them. However, normally it should not be necessary to alter resource control settings on these unit types.)
+
+## The APIs
+
+Most relevant APIs are exposed via D-Bus, however some _passive_ interfaces are available as shared library, bypassing IPC so that they are much cheaper to call.
+
+### Creating and Starting
+
+To create and start a transient (scope, service or slice) unit in the cgroup tree use the `StartTransientUnit()` method on the `Manager` object exposed by systemd's PID 1 on the bus, see the [Bus API Documentation](http://www.freedesktop.org/wiki/Software/systemd/dbus/) for details. This call takes four arguments. The first argument is the full unit name you want this unit to be known under. This unit name is the handle to the unit, and is shown in the "systemctl" output and elsewhere. This name must be unique during runtime of the unit. You should generate a descriptive name for this that is useful for the administrator to make sense of it. The second parameter is the mode, and should usually be `replace` or `fail`. The third parameter contains an array of initial properties to set for the unit. It is an array of pairs of property names as string and values as variant. Note that this is an array and not a dictionary! This is that way in order to match the properties array of the `SetProperties()` call (see below). The fourth parameter is currently not used and should be passed as empty array. This call will first create the transient unit and then immediately queue a start job for it. This call returns an object path to a `Job` object for the start job of this unit.
+
+### Properties
+
+The properties array of `StartTransientUnit()` may take many of the settings that may also be configured in unit files. Not all parameters are currently accepted though, but we plan to cover more properties with future release. Currently you may set the `Description`, `Slice` and all dependency types of units, as well as `RemainAfterExit`, `ExecStart` for service units, `TimeoutStopUSec` and `PIDs` for scope units, and `CPUAccounting`, `CPUShares`, `BlockIOAccounting`, `BlockIOWeight`, `BlockIOReadBandwidth`, `BlockIOWriteBandwidth`, `BlockIODeviceWeight`, `MemoryAccounting`, `MemoryLimit`, `DevicePolicy`, `DeviceAllow` for services/scopes/slices. These fields map directly to their counterparts in unit files and as normal D-Bus object properties. The exception here is the `PIDs` field of scope units which is used for construction of the scope only and specifies the initial PIDs to add to the scope object.
+
+To alter resource control properties at runtime use the `SetUnitProperty()` call on the `Manager` object or `SetProperty()` on the individual Unit objects. This also takes an array of properties to set, in the same format as `StartTransientUnit()` takes. Note again that this is not a dictionary, and allows properties to be set multiple times with a single invocation. THis is useful for array properties: if a property is assigned the empty array it will be reset to the empty array itself, however if it is assigned a non-empty array then this array is appended to the previous array. This mimics behaviour of array settings in unit files. Note that most settings may only be set during creation of units with `StartTransientUnit()`, and may not be altered later on. The exception here are the resource control settings, more specifically `CPUAccounting`, `CPUShares`, `BlockIOAccounting`, `BlockIOWeight`, `BlockIOReadBandwidth`, `BlockIOWriteBandwidth`, `BlockIODeviceWeight`, `MemoryAccounting`, `MemoryLimit`, `DevicePolicy`, `DeviceAllow` for services/scopes/slices. Note that the standard D-Bus `org.freedesktop.DBus.Properties.Set()` call is currently not supported by any of the unit objects to set these properties, but might eventually (note however, that it is substantially less useful as it only allows setting a single property at a time, resulting in races).
+
+The [`systemctl set-property`](http://www.freedesktop.org/software/systemd/man/systemctl.html) command internally is little more than a wrapper around `SetUnitProperty()`. The [`systemd-run`](http://www.freedesktop.org/software/systemd/man/systemd-run.html) tool is a wrapper around `StartTransientUnit()`. It may be used to either run a process as a transient service in the background, where it is invoked from PID 1, or alternatively as a scope unit in the foreground, where it is run from the `systemd-run` process itself.
+
+### Enumeration
+
+To acquire a list of currently running units, use the `ListUnits()` call on the Manager bus object. To determine the scope/service unit and slice unit a process is running in use [`sd_pid_get_unit()`](http://www.freedesktop.org/software/systemd/man/sd_pid_get_unit.html) and `sd_pid_get_slice()`. These two calls are implemented in `libsystemd-login.so`. These call bypass the system bus (which they can because they are passive and do not require privileges) and are hence very effecient to invoke.
+
+### 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`](http://www.freedesktop.org/wiki/Software/systemd/machined/) interfaces since they provide integration with "ps" and similar tools beyond what mere cgroup registration provides. Also see [Writing VM and Container Managers](http://www.freedesktop.org/wiki/Software/systemd/writing-vm-managers/) for details.
+
+### Reading Accounting Information
+
+Note that there's currently no systemd API to retrieve accounting information from cgroups. For now, if you need to retrieve this information use `/proc/$PID/cgroup` to determine the cgroup path for your process in the `cpuacct` controller (or whichever controller matters to you), and then read the attributes directly from the cgroup tree.
+
+If you want to collect the exit status and other runtime parameters of your transient scope or service unit after the processes in them ended set the `RemainAfterExited` boolean property when creating it. This will has the effect that the unit will stay around even after all processes in it died, in the `SubState="exited"` state. Simply watch for state changes until this state is reached, then read the status details from the various properties you need, and finally terminate the unit via `StopUnit()` on the `Manager` object or `Stop()` on the `Unit` object itself.
+
+### Becoming a Controller
+
+Optionally, it is possible for a program that registers a scope unit (the "scope manager") for one or more of its child processes to hook into the shutdown logic of the scope unit. Normally, if this is not done, and the scope needs to be shut down (regardless if during normal operation when the user invokes `systemctl stop` -- or something equivalent -- on the scope unit, or during system shutdown), then systemd will simply send SIGTERM to its processes. After a timeout this will be followed by SIGKILL unless the scope processes exited by then. If a scope manager program wants to be involved in the shutdown logic of its scopes it may set the `Controller` property of the scope unit when creating it via `StartTransientUnit()`. It should be set to the bus name (either unique name or well-known name) of the scope manager program. If this is done then instead of SIGTERM to the scope processes systemd will send the RequestStop() bus signal to the specified name. If the name is gone by then it will automatically fallback to SIGTERM, in order to make this robust. As before in either case this will be followed by SIGKILL to the scope unit processes after a timeout.
+
+Scope units implement a special `Abandon()` method call. This method call is useful for informing the system manager that the scope unit is no longer managed by any scope manager process. Among other things it is useful for manager daemons which terminate but want to leave the scopes they started running. When a scope is abandoned its state will be set to "abandoned" which is shown in the usual systemctl output, as information to the user. Also, if a controller has been set for the scope, it will be unset. Note that there is not strictly need to ever invoke the `Abandon()` method call, however it is recommended for cases like the ones explained above.
+
+### Delegation
+
+Service and scope units know a special `Delegate` boolean property. If set, then the processes inside the scope or service may control their own control group subtree (that means: create subcgroups directly via /sys/fs/cgroup). The effect of the property is that:
+
+1. All controllers systemd knows are enabled for that scope/service, if the scope/service runs privileged code.
+2. Access to the cgroup directory of the scope/service is permitted, and files/and directories are updated to get write access for the user specified in `User=` if the scope/unit runs unprivileged. Note that in this case access to any controllers is not available.
+3. systemd will refrain from moving processes across the "delegation" boundary.
+
+Generally, the `Delegate` property is only useful for services that need to manage their own cgroup subtrees, such as container managers. After creating a unit with this property set, they should use `/proc/$PID/cgroup` to figure out the cgroup subtree path they may manage (the one from the name=systemd hierarchy!). Managers should refrain from making any changes to the cgroup tree outside of the subtrees for units they created with the `Delegate` flag turned on.
+
+Note that scope units created by `machined`'s `CreateMachine()` call have this flag set.
+
+### Example
+
+Please see the [systemd-run sources](http://cgit.freedesktop.org/systemd/systemd/plain/src/run/run.c) for a relatively simple example how to create scope or service units transiently and pass properties to them.
--- /dev/null
+---
+title: Inhibitor Locks
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Inhibitor Locks
+
+systemd 183 and newer include a logic to inhibit system shutdowns and sleep states. This is implemented as part of [systemd-logind.daemon(8)](http://www.freedesktop.org/software/systemd/man/systemd-logind.service.html) There are a couple of different use cases for this:
+
+- A CD burning application wants to ensure that the system is not turned off or suspended while the burn process is in progress.
+- A package manager wants to ensure that the system is not turned off while a package upgrade is in progress.
+- An office suite wants to be notified before system suspend in order to save all data to disk, and delay the suspend logic until all data is written.
+- A web browser wants to be notified before system hibernation in order to free its cache to minimize the amount of memory that needs to be virtualized.
+- A screen lock tool wants to bring up the screen lock right before suspend, and delay the suspend until that's complete.
+
+Applications which want to make use of the inhibition logic shall take an inhibitor lock via the [logind D-Bus API](http://www.freedesktop.org/wiki/Software/systemd/logind).
+
+Seven distinct inhibitor lock types may be taken, or a combination of them:
+
+1. _sleep_ inhibits system suspend and hibernation requested by (unprivileged) **users**
+2. _shutdown_ inhibits high-level system power-off and reboot requested by (unprivileged) **users**
+3. _idle_ inhibits that the system goes into idle mode, possibly resulting in **automatic** system suspend or shutdown depending on configuration.
+
+- _handle-power-key_ inhibits the low-level (i.e. logind-internal) handling of the system power **hardware** key, allowing (possibly unprivileged) external code to handle the event instead.
+
+4. Similar, _handle-suspend-key_ inhibits the low-level handling of the system **hardware** suspend key.
+5. Similar, _handle-hibernate-key_ inhibits the low-level handling of the system **hardware** hibernate key.
+6. Similar, _handle-lid-switch_ inhibits the low-level handling of the systemd **hardware** lid switch.
+
+Two different modes of locks are supported:
+
+1. _block_ inhibits operations entirely until the lock is released. If such a lock is taken the operation will fail (but still may be overridden if the user possesses the necessary privileges).
+2. _delay_ inhibits operations only temporarily, either until the lock is released or up to a certain amount of time. The InhibitDelayMaxSec= setting in [logind.conf(5)](http://www.freedesktop.org/software/systemd/man/logind.conf.html) controls the timeout for this. This is intended to be used by applications which need a synchronous way to execute actions before system suspend but shall not be allowed to block suspend indefinitely. This mode is only available for _sleep_ and _shutdown_ locks.
+
+Inhibitor locks are taken via the Inhibit() D-Bus call on the logind Manager object:
+
+```
+$ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1
+node /org/freedesktop/login1 {
+ interface org.freedesktop.login1.Manager {
+ methods:
+ Inhibit(in s what,
+ in s who,
+ in s why,
+ in s mode,
+ out h fd);
+ ListInhibitors(out a(ssssuu) inhibitors);
+ ...
+ signals:
+ PrepareForShutdown(b active);
+ PrepareForSleep(b active);
+ ...
+ properties:
+ readonly s BlockInhibited = '';
+ readonly s DelayInhibited = '';
+ readonly t InhibitDelayMaxUSec = 5000000;
+ readonly b PreparingForShutdown = false;
+ readonly b PreparingForSleep = false;
+ ...
+ };
+ ...
+};
+```
+
+**Inhibit()** is the only API necessary to take a lock. It takes four arguments:
+
+- _What_ is a colon-separated list of lock types, i.e. `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`. Example: "shutdown:idle"
+- _Who_ is a human-readable, descriptive string of who is taking the lock. Example: "Package Updater"
+- _Why_ is a human-readable, descriptive string of why the lock is taken. Example: "Package Update in Progress"
+- _Mode_ is one of `block` or `delay`, see above. Example: "block"
+
+Inhibit() returns a single value, a file descriptor that encapsulates the lock. As soon as the file descriptor is closed (and all its duplicates) the lock is automatically released. If the client dies while the lock is taken the kernel automatically closes the file descriptor so that the lock is automatically released. A delay lock taken this way should be released ASAP on reception of PrepareForShutdown(true) (see below), but of course only after execution of the actions the application wanted to delay the operation for in the first place.
+
+**ListInhibitors()** lists all currently active inhibitor locks. It returns an array of structs, each consisting of What, Who, Why, Mode as above, plus the PID and UID of the process that requested the lock.
+
+The **PrepareForShutdown()** and **PrepareForSleep()** signals are emitted when a system suspend or shutdown has been requested and is about to be executed, as well as after the the suspend/shutdown was completed (or failed). The signals carry a boolean argument. If _True_ the shutdown/sleep has been requested, and the preparation phase for it begins, if _False_ the operation has finished completion (or failed). If _True_, this should be used as indication for applications to quickly execute the operations they wanted to execute before suspend/shutdown and then release any delay lock taken. If _False_ the suspend/shutdown operation is over, either successfully or unsuccessfully (of course, this signal will never be sent if a shutdown request was successful). The signal with _False_ is generally delivered only after the system comes back from suspend, the signal with _True_ possibly as well, for example when no delay lock was taken in the first place, and the system suspend hence executed without any delay. The signal with _False_ is usually the signal on which applications request a new delay lock in order to be synchronously notified about the next suspend/shutdown cycle. Note that watching PrepareForShutdown(true)[?](//secure.freedesktop.org/write/www/ikiwiki.cgi?do=create&from=Software%2Fsystemd%2Finhibit&page=Software%2Fsystemd%2Finhibit%2FPrepareForSleep)/PrepareForSleep(true) without taking a delay lock is racy and should not be done, as any code that an application might want to execute on this signal might not actually finish before the suspend/shutdown cycle is executed. _Again_: if you watch PrepareForSuspend(true), then you really should have taken a delay lock first. PrepareForShutdown(false) may be subscribed to by applications which want to be notified about system resume events. Note that this will only be sent out for suspend/resume cycles done via logind, i.e. generally only for high-level user-induced suspend cycles, and not automatic, low-level kernel induced ones which might exist on certain devices with more aggressive power management.
+
+The **BlockInhibited** and **DelayInhibited** properties encode what types of locks are currently taken. These fields are a colon separated list of `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`. The list is basically the union of the What fields of all currently active locks of the specific mode.
+
+**InhibitDelayMaxUSec** contains the delay timeout value as configured in [logind.conf(5)](http://www.freedesktop.org/software/systemd/man/logind.conf.html).
+
+The **PreparingForShutdown** and **PreparingForSleep** boolean properties are true between the two PrepareForShutdown() resp PrepareForSleep() signals that are sent out. Note that these properties do not trigger PropertyChanged signals.
+
+## Taking Blocking Locks
+
+Here's the basic scheme for applications which need blocking locks such as a package manager or CD burning application:
+
+1. Take the lock
+2. Do your work you don't want to see interrupted by system sleep or shutdown
+3. Release the lock
+
+Example pseudo code:
+
+```
+fd = Inhibit("shutdown:idle", "Package Manager", "Upgrade in progress...", "block");
+/* ...
+ do your work
+ ... */
+close(fd);
+```
+
+## Taking Delay Locks
+
+Here's the basic scheme for applications which need delay locks such as a web browser or office suite:
+
+1. As you open a document, take the delay lock
+2. As soon as you see PrepareForSleep(true), save your data, then release the lock
+3. As soon as you see PrepareForSleep(false), take the delay lock again, continue as before.
+
+Example pseudo code:
+
+```
+int fd = -1;
+
+takeLock() {
+ if (fd >= 0)
+ return;
+
+ fd = Inhibit("sleep", "Word Processor", "Save any unsaved data in time...", "delay");
+}
+
+onDocumentOpen(void) {
+ takeLock();
+}
+
+onPrepareForSleep(bool b) {
+ if (b) {
+ saveData();
+ if (fd >= 0) {
+ close(fd);
+ fd = -1;
+ }
+ } else
+ takeLock();
+
+}
+
+```
+
+## Taking Key Handling Locks
+
+By default logind will handle the power and sleep keys of the machine, as well as the lid switch in all states. This ensures that this basic system behavior is guaranteed to work in all circumstances, on text consoles as well as on all graphical environments. However, some DE might want to do their own handling of these keys, for example in order to show a pretty dialog box before executing the relevant operation, or to simply disable the action under certain conditions. For these cases the handle-power-key, handle-suspend-key, handle-hibernate-key and handle-lid-switch type inhibitor locks are available. When taken, these locks simply disable the low-level handling of the keys, they have no effect on system suspend/hibernate/poweroff executed with other mechanisms than the hardware keys (such as the user typing "systemctl suspend" in a shell). A DE intending to do its own handling of these keys should simply take the locks at login time, and release them on logout; alternatively it might make sense to take this lock only temporarily under certain circumstances (e.g. take the lid switch lock only when a second monitor is plugged in, in order to support the common setup where people close their laptops when they have the big screen connected).
+
+These locks need to be taken in the "block" mode, "delay" is not supported for them.
+
+If a DE wants to ensure the lock screen for the eventual resume is on the screen before the system enters suspend state, it should do this via a suspend delay inhibitor block (see above).
+
+## Miscellanea
+
+Taking inhibitor locks is a privileged operation. Depending on the action _org.freedesktop.login1.inhibit-block-shutdown_, _org.freedesktop.login1.inhibit-delay-shutdown_, _org.freedesktop.login1.inhibit-block-sleep_, _org.freedesktop.login1.inhibit-delay-sleep_, _org.freedesktop.login1.inhibit-block-idle_, _org.freedesktop.login1.inhibit-handle-power-key_, _org.freedesktop.login1.inhibit-handle-suspend-key_, _org.freedesktop.login1.inhibit-handle-hibernate-key_,_org.freedesktop.login1.inhibit-handle-lid-switch_. In general it should be assumed that delay locks are easier to obtain than blocking locks, simply because their impact is much more minimal. Note that the policy checks for Inhibit() are never interactive.
+
+Inhibitor locks should not be misused. For example taking idle blocking locks without a very good reason might cause mobile devices to never auto-suspend. This can be quite detrimental for the battery.
+
+If an application finds a lock denied it should not consider this much of an error and just continue its operation without the protecting lock.
+
+The tool [systemd-inhibit(1)](http://www.freedesktop.org/software/systemd/man/systemd-inhibit.html) may be used to take locks or list active locks from the command line.
+
+Note that gnome-session also provides an [inhibitor API](http://people.gnome.org/~mccann/gnome-session/docs/gnome-session.html#org.gnome.SessionManager.Inhibit), which is very similar to the one of systemd. Internally, locks taken on gnome-session's interface will be forwarded to logind, hence both APIs are supported. While both offer similar functionality they do differ in some regards. For obvious reasons gnome-session can offer logout locks and screensaver avoidance locks which logind lacks. logind's API OTOH supports delay locks in addition to block locks like GNOME. Also, logind is available to system components, and centralizes locks from all users, not just those of a specific one. In general: if in doubt it is probably advisable to stick to the GNOME locks, unless there is a good reason to use the logind APIs directly. When locks are to be enumerated it is better to use the logind APIs however, since they also include locks taken by system services and other users.
--- /dev/null
+---
+title: Minimal Builds
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Minimal Builds
+
+systemd includes a variety of components. The core components are always built (which includes systemd itself, as well as udevd and journald). Many of the other components can be disabled at compile time with configure switches.
+
+For some uses the configure switches do not provide sufficient modularity. For example, they cannot be used to build only the man pages, or to build only the tmpfiles tool, only detect-virt or only udevd. If such modularity is required that goes beyond what we support in the configure script we can suggest you two options:
+
+1. Build systemd as usual, but pick only the built files you need from the result of "make install DESTDIR=<directory>", by using the file listing functionality of your packaging software. For example: if all you want is the tmpfiles tool, then build systemd normally, and list only /usr/bin/systemd-tmpfiles in the .spec file for your RPM package. This is simple to do, allows you to pick exactly what you need, but requires a larger number of build dependencies (but not runtime dependencies).
+2. If you want to reduce the build time dependencies (though only dbus and libcap are needed as build time deps) and you know the specific component you are interested in doesn't need it, then create a dummy .pc file for that dependency (i.e. basically empty), and configure systemd with PKG_CONFIG_PATH set to the path of these dummy .pc files. Then, build only the few bits you need with "make foobar", where foobar is the file you need.
+ We are open to merging patches for the build system that make more "fringe" components of systemd optional. However, please be aware that in order to keep the complexity of our build system small and its readability high, and to make our lives easier, we will not accept patches that make the minimal core components optional, i.e. systemd itself, journald and udevd.
+
+Note that the .pc file trick mentioned above currently doesn't work for libcap, since libcap doesn't provide a .pc file. We invite you to go ahead and post a patch to libcap upstream to get this corrected. We'll happily change our build system to look for that .pc file then. (a .pc file has been sent to upstream by Bryan Kadzban. It is also available at [http://kdzbn.homelinux.net/libcap-add-pkg-config.patch](http://kdzbn.homelinux.net/libcap-add-pkg-config.patch)).
--- /dev/null
+---
+title: systemd Optimizations
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# systemd Optimizations
+
+_So you are working on a Linux distribution or appliance and need very fast boot-ups?_
+
+systemd can already offer boot times of < 1s for the Core OS (userspace only, i.e. only the bits controlled by systemd) and < 2s for a complete up-to-date desktop environments on simpler (but modern, i.e. SSDs) laptops if configured properly (examples: [http://git.fenrus.org/tmp/bootchart-20120512-1036.svg](http://git.fenrus.org/tmp/bootchart-20120512-1036.svg)). In this page we want to suggest a couple of ideas how to achieve that, and if the resulting boot times do not suffice where we believe room for improvements are that we'd like to see implemented sooner or later. If you are interested in investing engineering manpower in systemd to get to even shorter boot times, this list hopefully includes a few good suggestions to start with.
+
+Of course, before optimizing you should instrument the boot to generate profiling data, so make sure you know your way around with systemd-bootchart, systemd-analyze and pytimechart! Optimizations without profiling are premature optimizations!
+
+Note that systemd's fast performance is a side effect of its design but wasn't the primary design goal. As it stands now systemd (and Fedora using it) has been optimized very little and still has a lot of room for improvements. There are still many low hanging fruits to pick!
+
+We are very interested in merging optimization work into systemd upstream. Note however that we are careful not to merge work that would drastically limit the general purpose usefulness or reliability of our code, or that would make systemd harder to maintain. So in case you work on optimizations for systemd, try to keep your stuff mainlineable. If in doubt, ask us.
+
+The distributions have adopted systemd to varying levels. While there are many compatibility scripts in the boot process on Debian for example, Fedora has much less (but still too many). For better performance consider disabling these scripts, or using a different distribution.
+
+It is our intention to optimize the upstream distributions by default (in particular Fedora) so that these optimizations won't be necessary. However, this will take some time, especially since making these changes is often not trivial when the general purpose usefulness cannot be compromised.
+
+What you can optimize (locally) without writing any code:
+
+1. Make sure not to use any fake block device storage technology such as LVM (as installed by default by various distributions, including Fedora) they result in the systemd-udev-settle.service unit to be pulled in. Settling device enumeration is slow, racy and mostly obsolete. Since LVM (still) hasn't been updated to handle Linux' event based design properly, settling device enumeration is still required for it, but it will slow down boot substantially. On Fedora, use "systemctl mask fedora-wait-storage.service fedora-storage-init-late.service fedora-storage-init.service" to get rid of all those storage technologies. Of course, don't try this if you actually installed your system with LVM. (The only fake block device storage technology that currently handles this all properly and doesn't require settling device enumerations is LUKS disk encryption.)
+2. Consider bypassing the initrd, if you use one. On Fedora, make sure to install the OS on a plain disk without encryption, and without LVM/RAID/... (encrypted /home is fine) when doing this. Then, simply edit grub.conf and remove the initrd from your configuration, and change the root= kernel command line parameter so that it uses kernel device names instead of UUIDs, i.e. "root=sda5" or what is appropriate for your system. Also specify the root FS type with "rootfstype=ext4" (or as appropriate). Note that using kernel devices names is not really that nice if you have multiple hard disks, but if you are doing this for a laptop (i.e. with a single hdd), this should be fine. Note that you shouldn't need to rebuild your kernel in order to bypass the initrd. Distribution kernels (at least Fedora's) work fine with and without initrd, and systemd supports both ways to be started.
+3. Consider disabling SELinux and auditing. We recommend leaving SELinux on, for security reasons, but truth be told you can save 100ms of your boot if you disable it. Use selinux=0 on the kernel cmdline.
+4. Consider disabling Plymouth. If userspace boots in less than 1s, a boot splash is hardly useful, hence consider passing plymouth.enable=0 on the kernel command line. Plymouth is generally quite fast, but currently still forces settling device enumerations for graphics cards, which is slow. Disabling plymouth removes this bit of the boot.
+5. Consider uninstalling syslog. The journal is used anyway on newer systemd systems, and is usually more than sufficient for desktops, and embedded, and even many servers. Just uninstall all syslog implementations and remember that "journalctl" will get you a pixel perfect copy of the classic /var/log/messages message log. To make journal logs persistent (i.e. so that they aren't lost at boot) make sure to run "mkdir -p /var/log/journal".
+6. Consider masking a couple of redundant distribution boot scripts, that artificially slow down the boot. For example, on Fedora it's a good idea to mask fedora-autoswap.service fedora-configure.service fedora-loadmodules.service fedora-readonly.service. Also remove all LVM/RAID/FCOE/iSCSI related packages which slow down the boot substantially even if no storage of the specific kind is used (and if these RPMs can't be removed because some important packages require them, at least mask the respective services).
+7. Console output is slow. So if you measure your boot times and ship your system, make sure to use "quiet" on the command line and disable systemd debug logging (if you enabled it before).
+8. Consider removing cron from your system and use systemd timer units instead. Timer units currently have no support for calendar times (i.e. cannot be used to spawn things "at 6 am every Monday", but can do "run this every 7 days"), but for the usual /etc/cron.daily/, /etc/cron.weekly/, ... should be good enough, if the time of day of the execution doesn't matter (just add four small service and timer units for supporting these dirs. Eventually we might support these out of the box, but until then, just write your own scriplets for this).
+9. If you work on an appliance, consider disabling readahead collection in the shipped devices, but leave readahead replay enabled.
+10. If you work on an appliance, make sure to build all drivers you need into the kernel, since module loading is slow. If you build a distribution at least built all the stuff 90% of all people need into your kernel, i.e. at least USB, AHCI and HDA!
+11. If it works, use libahci.ignore_sss=1 when booting.
+12. Use a modern desktop that doesn't pull in ConsoleKit anymore. For example GNOME 3.4.
+13. Get rid of a local MTA, if you are building a desktop or appliance. I.e. on Fedora remove the sendmail RPMs which are (still!) installed by default.
+14. If you build an appliance, don't forget that various components of systemd are optional and may be disabled during build time, see "./configure --help" for details. For example, get rid of the virtual console setup if you never have local console users (this is a major source of slowness, actually). In addition, if you never have local users at all, consider disabling logind. And there are more components that are frequently unnecessary on appliances.
+15. This goes without saying: the boot-up gets faster if you started less stuff at boot. So run "systemctl" and check if there's stuff you don't need and disable it, or even remove its package.
+16. Don't use debug kernels. Debug kernels are slow. Fedora exclusively uses debug kernels during the development phase of each release. If you care about boot performance, either recompile these kernels with debugging turned off or wait for the final distribution release. It's a drastic difference. That also means that if you publish boot performance data of a Fedora pre-release distribution you are doing something wrong. ;-) So much about the basics of how to get a quick boot. Now, here's an incomprehensive list of things we'd like to see improved in systemd (and elsewhere) over short or long and need a bit of hacking (sometimes more, and sometimes less):
+17. Get rid of systemd-cgroups-agent. Currently, whenever a systemd cgroup runs empty a tool "systemd-cgroups-agent" is invoked by the kernel which then notifies systemd about it. The need for this tool should really go away, which will save a number of forked processes at boot, and should make things faster (especially shutdown). This requires introduction of a new kernel interface to get notifications for cgroups running empty, for example via fanotify() on cgroupfs.
+18. Make use of EXT4_IOC_MOVE_EXT in systemd's readahead implementation. This allows reordering/defragmentation of the files needed for boot. According to the data from [http://e4rat.sourceforge.net/](http://e4rat.sourceforge.net/) this might shorten the boot time to 40%. Implementation is not trivial, but given that we already support btrfs defragmentation and example code for this exists (e4rat as linked) should be fairly straightforward.
+19. Compress readahead pack files with XZ or so. Since boot these days tends to be clearly IO bound (and not CPU bound) it might make sense to reduce the IO load for the pack file by compressing it. Since we already have a dependency on XZ we'd recommend using XZ for this.
+20. Update the readahead logic to also precache directories (in addition to files).
+21. Improve a couple of algorithms in the unit dependency graph calculation logic, as well as unit file loading. For example, right now when loading units we match them up with a subset of the other loaded units in order to add automatic dependencies between them where appropriate. Usually the set of units matched up is small, but the complexity is currently O(n^2), and this could be optimized. Since unit file loading and calculations in the dependency graphs is the only major, synchronous, computation-intensive bit of PID 1, and is executed before any services are started this should bring relevant improvements, especially on systems with big dependency graphs.
+22. Add socket activation to X. Due to the special socket allocation semantics of X this is useful only for display :0. This should allow parallelization of X startup with its clients.
+23. The usual housekeeping: get rid of shell-based services (i.e. SysV init scripts), replace them with unit files. Don't make use of Type=forking and ordering dependencies if possible, use socket activation with Type=simple instead. This allows drastically better parallelized start-up for your services. Also, if you cannot use socket activation, at least consider patching your services to support Type=notify in place of Type=forking. Consider making seldom used services activated on-demand (for example, printer services), and start frequently used services already at boot instead of delaying them until they are used.
+24. Consider making use of systemd for the session as well, the way Tizen is doing this. This still needs some love in systemd upstream to be a smooth ride, but we definitely would like to go this way sooner or later, even for the normal desktops.
+25. Add an option for service units to temporarily bump the CPU and IO priority of the startup code of important services. Note however, that we assume that this will not bring much and hence recommend looking into this only very late. Since boot-up tends to be IO bound, solutions such as readahead are probably more interesting than prioritizing service startup IO. Also, this would probably always require a certain amount of manual configuration since determining automatically which services are important is hard (if not impossible), because we cannot track properly which services other services wait for.
+26. Same as the previous item, but temporarily lower the CPU/IO priority of the startups part of unimportant leaf services. This is probably more useful than 11 as it is easier to determine which processes don't matter.
+27. Add a kernel sockopt for AF_UNIX to increase the maximum datagram queue length for SOCK_DGRAM sockets. This would allow us to queue substantially more logging datagrams in the syslog and journal sockets, and thus move the point where syslog/journal clients have to block before their message writes finish much later in the boot process. The current kernel default is rather low with 10. (As a temporary hack it is possible to increase /proc/sys/net/unix/max_dgram_qlen globally, but this has implications beyond systemd, and should probably be avoided.) The kernel patch to make this work is most likely trivial. In general, this should allow us to improve the level of parallelization between clients and servers for AF_UNIX sockets of type SOCK_DGRAM or SOCK_SEQPACKET. Again: the list above contains things we'd like to see in systemd anyway. We didn't do much profiling for these features, but we have enough indication to assume that these bits will bring some improvements. But yeah, if you work on this, keep your profiling tools ready at all times.
--- /dev/null
+---
+title: Presets
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Presets
+
+## Why?
+
+Different **distributions** have different policies on which services shall be enabled by default when the package they are shipped in is installed. On Fedora all services stay off by default, so that installing a package will not cause a service to be enabled (with some exceptions). On Debian all services are immediately enabled by default, so that installing a package will cause its service(s) to be enabled right-away.
+
+Different **spins** (flavours, remixes, whatever you might want to call them) of a distribution also have different policies on what services to enable, and what services to leave off. For example, the Fedora default will enable gdm as display manager by default, while the Fedora KDE spin will enable kdm instead.
+
+Different **sites** might also have different policies what to turn on by default and what to turn off. For example, one administrator would prefer to enforce the policy of "ssh should be always on, but everything else off", while another one might say "snmp always on, and for everything else use the distribution policy defaults".
+
+## The Logic
+
+Traditionally, policy about what services shall be enabled and what services shall not have been decided globally by the distributions, and were enforced in each package individually. This made it cumbersome to implement different policies per spin or per site, or to create software packages that do the right thing on more than one distribution. The enablement _mechanism_ was also encoding the enablement _policy_.
+
+systemd 32 and newer support package "preset" policies. These encode which units shall be enabled by default when they are installed, and which units shall not be enabled.
+
+Preset files may be written for specific distributions, for specific spins or for specific sites, in order to enforce different policies as needed. Preset policies are stored in .preset files in /usr/lib/systemd/system-preset/. If no policy exists the default implied policy of "enable everything" is enforced, i.e. in Debian style.
+
+The policy encoded in preset files is applied to a unit by invoking "systemctl preset ". It is recommended to use this command in all package post installation scriptlets. "systemctl preset " is identical to "systemctl enable " resp. "systemctl disable " depending on the policy.
+
+Preset files allow clean separation of enablement mechanism (inside the package scriptlets, by invoking "systemctl preset"), and enablement policy (centralized in the preset files).
+
+## Documentation
+
+Documentation for the preset policy file format is available here: [http://www.freedesktop.org/software/systemd/man/systemd.preset.html](http://www.freedesktop.org/software/systemd/man/systemd.preset.html)
+
+Documentation for "systemctl preset" you find here: [http://www.freedesktop.org/software/systemd/man/systemctl.html](http://www.freedesktop.org/software/systemd/man/systemctl.html)
+
+Documentation for the recommended package scriptlets you find here: [http://www.freedesktop.org/software/systemd/man/daemon.html](http://www.freedesktop.org/software/systemd/man/daemon.html)
+
+## How To
+
+For the preset logic to be useful, distributions need to implement a couple of steps:
+
+- The default distribution policy needs to be encoded in a preset file /usr/lib/systemd/system-preset/99-default.preset or suchlike, unless the implied policy of "enable everything" is the right choice. For a Fedora-like policy of "enable nothing" it is sufficient to include the single line "disable" into that file. The default preset file should be installed as part of one the core packages of the distribution.
+- All packages need to be updated to use "systemctl preset" in the post install scriptlets.
+- (Optionally) spins/remixes/flavours should define their own preset file, either overriding or extending the default distribution preset policy. Also see the fedora feature page: [https://fedoraproject.org/wiki/Features/PackagePresets](https://fedoraproject.org/wiki/Features/PackagePresets)
--- /dev/null
+---
+title: Writing syslog Daemons Which Cooperate Nicely With systemd
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Writing syslog Daemons Which Cooperate Nicely With systemd
+
+Here are a few notes on things to keep in mind when you work on a classic BSD syslog daemon for Linux, to ensure that your syslog daemon works nicely together with systemd. If your syslog implementation does not follow these rules, then it will not be compatible with systemd v38 and newer.
+
+A few notes in advance: systemd centralizes all log streams in the Journal daemon. Messages coming in via /dev/log, via the native protocol, via STDOUT/STDERR of all services and via the kernel are received in the journal daemon. The journal daemon then stores them to disk or in RAM (depending on the configuration of the Storage= option in journald.conf), and optionally forwards them to the console, the kernel log buffer, or to a classic BSD syslog daemon -- and that's where you come in.
+
+Note that it is now the journal that listens on /dev/log, no longer the BSD syslog daemon directly. If your logging daemon wants to get access to all logging data then it should listen on /run/systemd/journal/syslog instead via the syslog.socket unit file that is shipped along with systemd. On a systemd system it is no longer OK to listen on /dev/log directly, and your daemon may not bind to the /run/systemd/journal/syslog socket on its own. If you do that then you will lose logging from STDOUT/STDERR of services (as well as other stuff).
+
+Your BSD compatible logging service should alias `syslog.service` to itself (i.e. symlink) when it is _enabled_. That way [syslog.socket](http://cgit.freedesktop.org/systemd/systemd/plain/units/syslog.socket) will activate your service when things are logged. Of course, only one implementation of BSD syslog can own that symlink, and hence only one implementation can be enabled at a time, but that's intended as there can only be one process listening on that socket. (see below for details how to manage this symlink.) Note that this means that syslog.socket as shipped with systemd is _shared_ among all implementations, and the implementation that is in control is configured with where syslog.service points to.
+
+Note that journald tries hard to forward to your BSD syslog daemon as much as it can. That means you will get more than you traditionally got on /dev/log, such as stuff all daemons log on STDOUT/STDERR and the messages that are logged natively to systemd. Also, we will send stuff like the original SCM_CREDENTIALS along if possible.
+
+(BTW, journald is smart enough not to forward the kernel messages it gets to you, you should read that on your own, directly from /proc/kmsg, as you always did. It's also smart enough never to forward kernel messages back to the kernel, but that probably shouldn't concern you too much...)
+
+And here are the recommendations:
+
+- First of all, make sure your syslog daemon installs a native service unit file (SysV scripts are not sufficient!) and is socket activatable. Newer systemd versions (v35+) do not support non-socket-activated syslog daemons anymore and we do no longer recommend people to order their units after syslog.target. That means that unless your syslog implementation is socket activatable many services will not be able to log to your syslog implementation and early boot messages are lost entirely to your implementation. Note that your service should install only one unit file, and nothing else. Do not install socket unit files.
+- Make sure that in your unit file you set StandardOutput=null in the [Service] block. This makes sure that regardless what the global default for StandardOutput= is the output of your syslog implementation goes to /dev/null. This matters since the default StandardOutput= value for all units can be set to syslog and this should not create a feedback loop with your implementation where the messages your syslog implementation writes out are fed back to it. In other words: you need to explicitly opt out of the default standard output redirection we do for other services. (Also note that you do not need to set StandardError= explicitly, since that inherits the setting of StandardOutput= by default)
+- /proc/kmsg is your property, flush it to disk as soon as you start up.
+- Name your service unit after your daemon (e.g. rsyslog.service or syslog-ng.service) and make sure to include Alias=syslog.service in your [Install] section in the unit file. This is ensures that the symlink syslog.service is created if your service is enabled and that it points to your service. Also add WantedBy=multi-user.target so that your service gets started at boot, and add Requires=syslog.socket in [Unit] so that you pull in the socket unit.
+
+Here are a few other recommendations, that are not directly related to systemd:
+
+- Make sure to read the priority prefixes of the kmsg log messages the same way like from normal userspace syslog messages. When systemd writes to kmsg it will prefix all messages with valid priorities which include standard syslog facility values. OTOH for kernel messages the facility is always 0. If you need to know whether a message originated in the kernel rely on the facility value, not just on the fact that you read the message from /proc/kmsg! A number of userspace applications write messages to kmsg (systemd, udev, dracut, others), and they'll nowadays all set correct facility values.
+- When you read a message from the socket use SCM_CREDENTIALS to get information about the client generating it, and possibly patch the message with this data in order to make it impossible for clients to fake identities.
+
+The unit file you install for your service should look something like this:
+
+```
+[Unit]
+Description=System Logging Service
+Requires=syslog.socket
+
+[Service]
+ExecStart=/usr/sbin/syslog-ng -n
+StandardOutput=null
+
+[Install]
+Alias=syslog.service
+WantedBy=multi-user.target
+```
+
+And remember: don't ship any socket unit for /dev/log or /run/systemd/journal/syslog (or even make your daemon bind directly to these sockets)! That's already shipped along with systemd for you.
--- /dev/null
+---
+title: systemd File Hierarchy Requirements
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# systemd File Hierarchy Requirements
+
+There are various attempts to standardize the file system hierarchy of Linux systems. In systemd we leave much of the file system layout open to the operating system, but here's what systemd strictly requires:
+
+- /, /usr, /etc must be mounted when the host systemd is first invoked. This may be achieved either by using the kernel's built-in root disk mounting (in which case /, /usr and /etc need to be on the same file system), or via an initrd, which could mount the three directories from different sources.
+- /bin, /sbin, /lib (and /lib64 if applicable) should reside on /, or be symlinks to the /usr file system (recommended). All of them must be available before the host systemd is first executed.
+- /var does not have to be mounted when the host systemd is first invoked, however, it must be configured so that it is mounted writable before local-fs.target is reached (for example, by simply listing it in /etc/fstab).
+- /tmp is recommended to be a tmpfs (default), but doesn't have to. If configured, it must be mounted before local-fs.target is reached (for example, by listing it in /etc/fstab).
+- /dev must exist as an empty mount point and will automatically be mounted by systemd with a devtmpfs. Non-devtmpfs boots are not supported.
+- /proc and /sys must exist as empty mount points and will automatically be mounted by systemd with procfs and sysfs.
+- /run must exist as an empty mount point and will automatically be mounted by systemd with a tmpfs.
+
+The other directories usually found in the root directory (such as /home, /boot, /opt) are irrelevant to systemd. If they are defined they may be mounted from any source and at any time, though it is a good idea to mount them also before local-fs.target is reached.
--- /dev/null
+---
+title: The Case for the /usr Merge
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# The Case for the /usr Merge
+
+**Why the /usr Merge Makes Sense for Compatibility Reasons**
+
+_This is based on the [Fedora feature](https://fedoraproject.org/wiki/Features/UsrMove) for the same topic, put together by Harald Hoyer and Kay Sievers. This feature has been implemented successfully in Fedora 17._
+
+Note that this page discusses a topic that is actually independent of systemd. systemd supports both systems with split and with merged /usr, and the /usr merge also makes sense for systemd-less systems. That said we want to encourage distributions adopting systemd to also adopt the /usr merge.
+
+### What's Being Discussed Here?
+
+Fedora (and other distributions) have finished work on getting rid of the separation of /bin and /usr/bin, as well as /sbin and /usr/sbin, /lib and /usr/lib, and /lib64 and /usr/lib64. All files from the directories in / will be merged into their respective counterparts in /usr, and symlinks for the old directories will be created instead:
+
+```
+/bin → /usr/bin
+/sbin → /usr/sbin
+/lib → /usr/lib
+/lib64 → /usr/lib64
+```
+
+You are wondering why merging /bin, /sbin, /lib, /lib64 into their respective counterparts in /usr makes sense, and why distributions are pushing for it? You are wondering whether your own distribution should adopt the same change? Here are a few answers to these questions, with an emphasis on a compatibility point of view:
+
+### Compatibility: The Gist of It
+
+- Improved compatibility with other Unixes/Linuxes in _behavior_: After the /usr merge all binaries become available in both /bin and /usr/bin, resp. both /sbin and /usr/sbin (simply because /bin becomes a symlink to /usr/bin, resp. /sbin to /usr/sbin). That means scripts/programs written for other Unixes or other Linuxes and ported to your distribution will no longer need fixing for the file system paths of the binaries called, which is otherwise a major source of frustration. /usr/bin and /bin (resp. /usr/sbin and /sbin) become entirely equivalent.
+- Improved compatibility with other Unixes (in particular Solaris) in _appearance_: The primary commercial Unix implementation is nowadays Oracle Solaris. Solaris has already completed the same /usr merge in Solaris 11. By making the same change in Linux we minimize the difference towards the primary Unix implementation, thus easing portability from Solaris.
+- Improved compatibility with GNU build systems: The biggest part of Linux software is built with GNU autoconf/automake (i.e. GNU autotools), which are unaware of the Linux-specific /usr split. Maintaining the /usr split requires non-trivial project-specific handling in the upstream build system, and in your distribution's packages. With the /usr merge, this work becomes unnecessary and porting packages to Linux becomes simpler.
+- Improved compatibility with current upstream development: In order to minimize the delta from your Linux distribution to upstream development the /usr merge is key.
+
+### Compatibility: The Longer Version
+
+A unified filesystem layout (as it results from the /usr merge) is more compatible with UNIX than Linux’ traditional split of /bin vs. /usr/bin. Unixes differ in where individual tools are installed, their locations in many cases are not defined at all and differ in the various Linux distributions. The /usr merge removes this difference in its entirety, and provides full compatibility with the locations of tools of any Unix via the symlink from /bin to /usr/bin.
+
+#### Example
+
+- /usr/bin/foo may be called by other tools either via /usr/bin/foo or /bin/foo, both paths become fully equivalent through the /usr merge. The operating system ends up executing exactly the same file, simply because the symlink /bin just redirects the invocation to /usr/bin.
+
+The historical justification for a /bin, /sbin and /lib separate from /usr no longer applies today. ([More on the historical justification for the split](http://lists.busybox.net/pipermail/busybox/2010-December/074114.html), by Rob Landley) They were split off to have selected tools on a faster hard disk (which was small, because it was more expensive) and to contain all the tools necessary to mount the slower /usr partition. Today, a separate /usr partition already must be mounted by the initramfs during early boot, thus making the justification for a split-off moot. In addition a lot of tools in /bin and /sbin in the status quo already lost the ability to run without a pre-mounted /usr. There is no valid reason anymore to have the operating system spread over multiple hierarchies, it lost its purpose.
+
+Solaris implemented the core part of the /usr merge 15 years ago already, and completed it with the introduction of Solaris 11. Solaris has /bin and /sbin only as symlinks in the root file system, the same way as you will have after the /usr merge: [Transitioning From Oracle Solaris 10 to Oracle Solaris 11 - User Environment Feature Changes](http://docs.oracle.com/cd/E23824_01/html/E24456/userenv-1.html).
+
+Not implementing the /usr merge in your distribution will isolate it from upstream development. It will make porting of packages needlessly difficult, because packagers need to split up installed files into multiple directories and hard code different locations for tools; both will cause unnecessary incompatibilities. Several Linux distributions are agreeing with the benefits of the /usr merge and are already in the process to implement the /usr merge. This means that upstream projects will adapt quickly to the change, those making portability to your distribution harder.
+
+### Beyond Compatibility
+
+One major benefit of the /usr merge is the reduction of complexity of our system: the new file system hierarchy becomes much simpler, and the separation between (read-only, potentially even immutable) vendor-supplied OS resources and users resources becomes much cleaner. As a result of the reduced complexity of the hierarchy, packaging becomes much simpler too, since the problems of handling the split in the .spec files go away.
+
+The merged directory /usr, containing almost the entire vendor-supplied operating system resources, offers us a number of new features regarding OS snapshotting and options for enterprise environments for network sharing or running multiple guests on one host. Static vendor-supplied OS resources are monopolized at a single location, that can be made read-only easily, either for the whole system or individually for each service. Most of this is much harder to accomplish, or even impossible, with the current arbitrary split of tools across multiple directories.
+
+_With all vendor-supplied OS resources in a single directory /usr they may be shared atomically, snapshots of them become atomic, and the file system may be made read-only as a single unit._
+
+#### Example: /usr Network Share
+
+- With the merged /usr directory we can offer a read-only export of the vendor supplied OS to the network, which will contain almost the entire operating system resources. The client hosts will then only need a minimal host-specific root filesystem with symlinks pointing into the shared /usr filesystem. From a maintenance perspective this is the first time where sharing the operating system over the network starts to make sense. Without the merged /usr directory (like in traditional Linux) we can only share parts of the OS at a time, but not the core components of it that are located in the root file system. The host-specific root filesystem hence traditionally needs to be much larger, cannot be shared among client hosts and needs to be updated individually and often. Vendor-supplied OS resources traditionally ended up "leaking" into the host-specific root file system.
+
+#### Example: Multiple Guest Operating Systems on the Same Host
+
+- With the merged /usr directory, we can offer to share /usr read-only with multiple guest operating systems, which will shrink down the guest file system to a couple of MB. The ratio of the per-guest host-only part vs. the shared operating system becomes nearly optimal.
+ In the long run the maintenance burden resulting of the split-up tools in your distribution, and hard-coded deviating installation locations to distribute binaries and other packaged files into multiple hierarchies will very likely cause more trouble than the /usr merge itself will cause.
+
+## Myths and Facts
+
+**Myth #1**: Fedora is the first OS to implement the /usr merge
+
+**Fact**: Oracle Solaris has implemented the /usr merge in parts 15 years ago, and completed it in Solaris 11. Fedora is following suit here, it is not the pioneer.
+
+**Myth #2**: Fedora is the only Linux distribution to implement the /usr merge
+
+**Fact**: Multiple other Linux distributions have been working in a similar direction.
+
+**Myth #3**: The /usr merge decreases compatibility with other Unixes/Linuxes
+
+**Fact**: By providing all binary tools in /usr/bin as well as in /bin (resp. /usr/sbin + /sbin) compatibility with hard coded binary paths in scripts is increased. When a distro A installs a tool “foo” in /usr/bin, and distro B installs it in /bin, then we’ll provide it in both, thus creating compatibility with both A and B.
+
+**Myth #4**: The /usr merge’s only purpose is to look pretty, and has no other benefits
+
+**Fact**: The /usr merge makes sharing the vendor-supplied OS resources between a host and networked clients as well as a host and local light-weight containers easier and atomic. Snapshotting the OS becomes a viable option. The /usr merge also allows making the entire vendor-supplied OS resources read-only for increased security and robustness.
+
+**Myth #5**: Adopting the /usr merge in your distribution means additional work for your distribution's package maintainers
+
+**Fact**: When the merge is implemented in other distributions and upstream, not adopting the /usr merge in your distribution means more work, adopting it is cheap.
+
+**Myth #6**: A split /usr is Unix “standard”, and a merged /usr would be Linux-specific
+
+**Fact**: On SysV Unix /bin traditionally has been a symlink to /usr/bin. A non-symlinked version of that directory is specific to non-SysV Unix and Linux.
+
+**Myth #7**: After the /usr merge one can no longer mount /usr read-only, as it is common usage in many areas.
+
+**Fact**: Au contraire! One of the reasons we are actually doing this is to make a read-only /usr more thorough: the entire vendor-supplied OS resources can be made read-only, i.e. all of what traditionally was stored in /bin, /sbin, /lib on top of what is already in /usr.
+
+**Myth #8**: The /usr merge will break my old installation which has /usr on a separate partition.
+
+**Fact**: This is perfectly well supported, and one of the reasons we are actually doing this is to make placing /usr of a separate partition more thorough. What changes is simply that you need to boot with an initrd that mounts /usr before jumping into the root file system. Most distributions rely on initrds anyway, so effectively little changes.
+
+**Myth #9**: The /usr split is useful to have a minimal rescue system on the root file system, and the rest of the OS on /usr.
+
+**Fact**: On Fedora the root directory contains ~450MB already. This hasn't been minimal since a long time, and due to today's complex storage and networking technologies it's unrealistic to ever reduce this again. In fact, since the introduction of initrds to Linux the initrd took over the role as minimal rescue system that requires only a working boot loader to be started, but not a full file system.
+
+**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](http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken).
+
+**Myth #11**: Instead of merging / into /usr it would make a lot more sense to merge /usr into /.
+
+**Fact**: This would make the separation between vendor-supplied OS resources and machine-specific even worse, thus making OS snapshots and network/container sharing of it much harder and non-atomic, and clutter the root file system with a multitude of new directories.
+
+---
+
+If this page didn't answer your questions you may continue reading [on the Fedora feature page](https://fedoraproject.org/wiki/Features/UsrMove) and this [mail from Lennart](http://thread.gmane.org/gmane.linux.redhat.fedora.devel/155511/focus=155792).
--- /dev/null
+---
+title: Testing systemd during Development in Virtualization
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Testing systemd during Development in Virtualization
+
+For quickly testing systemd during development it us useful to boot it up in a container and in a QEMU VM.
+
+## Testing in a VM
+
+Here's a nice hack if you regularly build and test-boot systemd, are gutsy enough to install it into your host, but too afraid or too lazy to continuously reboot your host.
+
+Create a shell script like this:
+
+```
+#!/bin/sh
+
+sudo sync
+sudo /bin/sh -c 'echo 3 > /proc/sys/vm/drop_caches'
+sudo umount /
+sudo modprobe kvm-intel
+
+exec sudo qemu-kvm -smp 2 -m 512 -snapshot /dev/sda
+```
+
+This will boot your local host system as a throw-away VM guest. It will take your main harddisk, boot from it in the VM, allow changes to it, but these changes are all just buffered in memory and never hit the real disk. Any changes made in this VM will be lost when the VM terminates. I have called this script "q", and hence for test booting my own system all I do is type the following command in my systemd source tree and I can see if it worked.
+
+```
+$ make -j10 && sudo make install && q
+
+```
+
+The first three lines are necessary to ensure that the kernel's disk caches are all synced to disk before qemu takes the snapshot of it. Yes, invoking "umount /" will sync your file system to disk as a side effect, even though it will actually fail. When the machine boots up the file system will still be marked dirty (and hence you will get an fsck, usually), but it will work fine nonetheless in virtually all cases.
+
+Of course, if the host's hard disk changes while the VM is running this will be visible to the VM, and might confuse it. If you use this little hack you should keep changes on the host at a minimum, hence. Yeah this all is a hack, but a really useful and neat one.
+
+YMMV if you use LVM or btrfs.
+
+## Testing in a Container
+
+Test-booting systemd in a container has the benefit of being much easier to debug/instrument from the outside.
+
+**Important**: As preparation it is essential to turn off auditing entirely on your system. Auditing is broken with containers, and will trigger all kinds of error in containers if not turned off. Use `audit=0` on the host's kernel command line to turn it off.
+
+Then, as the first step I install Fedora into a container tree:
+
+```
+$ sudo yum -y --releasever=20 --installroot=$HOME/fedora-tree --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
+
+```
+
+You can do something similar with debootstrap on a Debian system. Now, we need to set a root password in order to be able to log in:
+
+```
+$ sudo systemd-nspawn -D ~/fedora-tree/
+# passwd
+...
+# ^D
+```
+
+As the next step we can already boot the container:
+
+```
+$ sudo systemd-nspawn -bD ~/fedora-tree/ 3
+
+```
+
+To test systemd in the container I then run this from my source tree on the host:
+
+```
+$ make -j10 && sudo DESTDIR=$HOME/fedora-tree make install && sudo systemd-nspawn -bD ~/fedora-tree/ 3
+
+```
+
+And that's already it.
--- /dev/null
+---
+title: Writing Desktop Environments
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Writing Desktop Environments
+
+_Or: how to hook up your favorite desktop environment with logind_
+
+systemd's logind service obsoletes ConsoleKit which was previously widely used on Linux distributions. This provides a number of new features, but also requires updating of the Desktop Environment running on it, in a few ways.
+
+This document should be read together with [Writing Display Managers](http://www.freedesktop.org/wiki/Software/systemd/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.
+
+To a certain level ConsoleKit and systemd-logind may be used side-by-side, but a number of features are not available if ConsoleKit is used.
+
+Please have a look at the [Bus API of logind](http://www.freedesktop.org/wiki/Software/systemd/logind) and the C API as documented in [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html). (Also see below)
+
+Here are the suggested changes:
+
+- Your session manager should listen to "Lock" and "Unlock" messages that are emitted from the session object logind exposes for your DE session, on the system bus. If "Lock" is received the screen lock should be activated, if "Unlock" is received it should be deactivated. This can easily be tested with "loginctl lock-sessions". See the [Bus API of logind](http://www.freedesktop.org/wiki/Software/systemd/logind) for further details.
+- Whenever the session gets idle the DE should invoke the SetIdleHint(True) call on the respective session object on the session bus. This is necessary for the system to implement auto-suspend when all sessions are idle. If the session gets used again it should call SetIdleHint(False). A session should be considered idle if it didn't receive user input (mouse movements, keyboard) in a while. See the [Bus API of logind](http://www.freedesktop.org/wiki/Software/systemd/logind) for further details.
+- To reboot/power-off/suspend/hibernate the machine from the DE use logind's bus calls Reboot(), PowerOff(), Suspend(), Hibernate(), HybridSleep(). For further details see [Bus API of logind](http://www.freedesktop.org/wiki/Software/systemd/logind).
+- 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](http://www.freedesktop.org/wiki/Software/systemd/inhibit) 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](http://www.freedesktop.org/wiki/Software/systemd/inhibit) 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).
+ And that's all! Thank you!
--- /dev/null
+---
+title: Writing Display Managers
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Writing Display Managers
+
+_Or: How to hook up your favorite X11 display manager with systemd_
+
+systemd's logind service obsoletes ConsoleKit which was previously widely used on Linux distributions. 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](http://www.freedesktop.org/wiki/Software/systemd/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.
+
+To a certain level ConsoleKit and systemd-logind may be used side-by-side, but a number of features are not available if ConsoleKit is used, for example automatic multi-seat support.
+
+Please have a look at the [Bus API of logind](http://www.freedesktop.org/wiki/Software/systemd/logind) and the C API as documented in [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html). (Also see below)
+
+Minimal porting (without multi-seat) requires the following:
+
+1. Remove/disable all code responsible for registering your service with ConsoleKit.
+2. Make sure to register your greeter session via the PAM session stack, and make sure the PAM session modules include pam_systemd. Also, make sure to set the session class to "greeter." This may be done by setting the environment variable XDG_SESSION_CLASS to "greeter" with pam_misc_setenv() or setting the "class=greeter" option in the pam_systemd module, in order to allow applications to filter out greeter sessions from normal login sessions.
+3. Make sure to register your logged in session via the PAM session stack as well, also including pam_systemd in it.
+4. Optionally, use pam_misc_setenv() to set the environment variables XDG_SEAT and XDG_VTNR. The former should contain "seat0", the latter the VT number your session runs on. pam_systemd can determine these values automatically but it's nice to pass these variables anyway.
+ In summary: porting a display manager from ConsoleKit to systemd primarily means removing code, not necessarily adding any new code. Here, a cheers to simplicity!
+
+Complete porting (with multi-seat) requires the following (Before you continue, make sure to read up on [Multi-Seat on Linux](http://www.freedesktop.org/wiki/Software/systemd/multiseat) first.):
+
+1. Subscribe to seats showing up and going away, via the systemd-logind D-Bus interface's SeatAdded and SeatRemoved signals. Take possession of each seat by spawning your greeter on it. However, do so exclusively for seats where the boolean CanGraphical property is true. Note that there are seats that cannot do graphical, and there are seats that are text-only first, and gain graphical support later on. Most prominently this is actually seat0 which comes up in text mode, and where the graphics driver is then loaded and probed during boot. This means display managers must watch PropertyChanged events on all seats, to see if they gain (or lose) the CanGraphical field.
+2. Use ListSeats() on the D-Bus interface to acquire a list of already available seats and also take possession of them.
+3. For each seat you spawn a greeter/user session on use the XDG_SEAT and XDG_VTNR PAM environment variables to inform pam_systemd about the seat name, resp. VT number you start them on. Note that only the special seat "seat0" actually knows kernel VTs, so you shouldn't pass the VT number on any but the main seat, since it doesn't make any sense there.
+4. Pass the seat name to the X server you start via the -seat parameter.
+5. At this time X interprets the -seat parameter natively only for input devices, not for graphics devices. To work around this limitation we provide a tiny wrapper /lib/systemd/systemd-multi-seat-x which emulates the enumeration for graphics devices too. This wrapper will eventually go away, as soon as X learns udev-based graphics device enumeration natively, instead of the current PCI based one. Hence it is a good idea to fall back to the real X when this wrapper is not found. You may use this wrapper exactly like the real X server, and internally it will just exec() it after putting together a minimal multi-seat configuration.
+ And that's already it.
+
+While most information about seats, sessions and users is available on systemd-logind's D-Bus interface, this is not the only API. The synchronous [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html) C interface is often easier to use and much faster too. In fact it is possible to implement the scheme above entirely without D-Bus relying only on this API. Note however, that this C API is purely passive, and if you want to execute an actually state changing operation you need to use the bus interface (for example, to switch sessions, or to kill sessions and suchlike). Also have a look at the [logind Bus API](http://www.freedesktop.org/wiki/Software/systemd/logind).
--- /dev/null
+---
+title: Writing Network Configuration Managers
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Writing Network Configuration Managers
+
+_Or: How to hook up your favourite network configuration manager's DNS logic with `systemd-resolved`_
+
+_(This is a longer explanation how to use some parts of `systemd-resolved` bus API. If you are just looking for an API reference, consult the [bus API documentation](https://wiki.freedesktop.org/www/Software/systemd/resolved/) instead.)_
+
+Since systemd 229 `systemd-resolved` offers a powerful bus API that may be used by network configuration managers (e.g. NetworkManager, connman, …, but also lower level DHCP, VPN or PPP daemons managing specific interfaces) to pass DNS server and DNSSEC configuration directly to `systemd-resolved`. Note that `systemd-resolved` also reads the DNS configuration data in `/etc/resolv.conf`, for compatibility. However, by passing the DNS configuration directly to `systemd-resolved` via the bus a couple of benefits are available:
+
+1. `systemd-resolved` maintains DNS configuration per-interface, instead of simply system-wide, and is capable of sending DNS requests to servers on multiple different network interfaces simultaneously, returning the first positive response (or if all fail, the last negative one). This allows effective "merging" of DNS views on different interfaces, which makes private DNS zones on multi-homed hosts a lot nicer to use. For example, if you are connected to a LAN and a VPN, and both have private DNS zones, then you will be able to resolve both, as long as they don't clash in names. By using the bus API to configure DNS settings, the per-interface configuration is opened up.
+2. Per-link configuration of DNSSEC is available. This is particularly interesting for network configuration managers that implement captive portal detection: as long as a verified connection to the Internet is not found DNSSEC should be turned off (as some captive portal systems alter the DNS in order to redirect clients to their internal pages).
+3. Per-link configuration of LLMNR and MulticastDNS is available.
+4. In contrast to changes to `/etc/resolv.conf` all changes made via the bus take effect immediately for all future lookups.
+5. Statistical data about executed DNS transactions is available, as well as information about whether DNSSEC is supported on the chosen DNS server.
+
+Note that `systemd-networkd` is already hooked up with `systemd-resolved`, exposing this functionality in full.
+
+## Suggested Mode of Operation
+
+Whenever a network configuration manager sets up an interface for operation, it should pass the DNS configuration information for the interface to `systemd-resolved`. It's recommended to do that after the Linux network interface index ("ifindex") has been allocated, but before the interface has beeen upped (i.e. `IFF_UP` turned on). That way, `systemd-resolved` will be able to use the configuration the moment the network interface is available. (Note that `systemd-resolved` watches the kernel interfaces come and go, and will make use of them as soon as they are suitable to be used, which among other factors requires `IFF_UP` to be set). That said it is OK to change DNS configuration dynamically any time: simply pass the new data to resolved, and it is happy to use it.
+
+In order to pass the DNS configuration information to resolved, use the following methods of the `org.freedesktop.resolve1.Manager` interface of the `/org/freedesktop/resolve1` object, on the `org.freedesktop.resolve1` service:
+
+1. To set the DNS server IP addresses for a network interface, use `SetLinkDNS()`
+2. To set DNS search and routing domains for a network interface, use `SetLinkDomains()`
+3. To configure the DNSSEC mode for a network interface, use `SetLinkDNSSEC()`
+4. To configure DNSSEC Negative Trust Anchors (NTAs, i.e. domains for which not to do DNSSEC validation), use `SetLinkDNSSECNegativeTrustAnchors()`
+5. To configure the LLMNR and MulticastDNS mode, use `SetLinkLLMNR()` and `SetLinkMulticastDNS()`
+
+For details about these calls see the [full resolved bus API documentation](https://wiki.freedesktop.org/www/Software/systemd/resolved/).
+
+The calls should be pretty obvious to use: they simply take an interface index and the parameters to set. IP addresses are encoded as an address family specifier (an integer, that takes the usual `AF_INET` and `AF_INET6` constants), followed by a 4 or 16 byte array with the address in network byte order.
+
+`systemd-resolved` distinguishes between "search" and "routing" domains. Routing domains are used to route DNS requests of specific domains to particular interfaces. i.e. requests for a hostname `foo.bar.com` will be routed to any interface that has `bar.com` as routing domain. The same routing domain may be defined on multiple interfaces, in which case the request is routed to all of them in parallel. Resolver requests for hostnames that do not end in any defined routing domain of any interface will be routed to all suitable interfaces. Search domains work like routing domain, but are also used to qualify single-label domain names. They hence are identical to the traditional search domain logic on UNIX. The `SetLinkDomains()` call may used to define both search and routing domains.
+
+The most basic support of `systemd-resolved` in a network configuration manager would be to simply invoke `SetLinkDNS()` and `SetLinkDomains()` for the specific interface index with the data traditionally written to `/etc/resolv.conf`. More advanced integration could mean the network configuration manager also makes the DNSSEC mode, the DNSSEC NTAs and the LLMNR/MulticastDNS modes available for configuration.
+
+It is strongly recommended for network configuration managers that implement captive portal detection to turn off DNSSEC validation during the detection phase, so that captive portals that modify DNS do not result in all DNSSEC look-ups to fail.
+
+If a network configuration manager wants to reset specific settings to the defaults (such as the DNSSEC, LLMNR or MulticastDNS mode), it may simply call the function with an empty argument. To reset all per-link changes it made it may call `RevertLink()`.
+
+To read back the various settings made, use `GetLink()` to get a `org.freedesktop.resolve1.Link` object for a specific network interface. It exposes the current settings in its bus properties. See the [full bus API documentation](https://wiki.freedesktop.org/www/Software/systemd/resolved/) for details on this.
+
+In order to translate a network interface name to an interface index, use the usual glibc `if_nametoindex()` call.
+
+If the network configuration UI shall expose information about whether the selected DNS server supports DNSSEC, check the `DNSSECSupported` on the link object.
+
+Note that it is fully OK if multiple different daemons push DNS configuration data into `systemd-resolved` as long as they do this only for the network interfaces they own and manage.
+
+## Handling of `/etc/resolv.conf`
+
+`systemd-resolved` receives DNS configuration from a number of sources, via the bus, as well as directly from `systemd-networkd` or user configuration. It uses this data to write a file that is compatible with the traditional Linux `/etc/resolv.conf` file. This file is stored in `/run/systemd/resolve/resolv.conf`. It is recommended to symlink `/etc/resolv.conf` to this file, in order to provide compatibility with programs reading the file directly and not going via the NSS and thus `systemd-resolved`.
+
+For network configuration managers it is recommended to rely on this resolved-provided mechanism to update `resolv.conf`. Specifically, the network configuration manager should stop modifying `/etc/resolv.conf` directly if it notices it being a symlink to `/run/systemd/resolve/resolv.conf`.
+
+If a system configuration manager desires to be compatible both with systems that use `systemd-resolved` and those which do not, it is recommended to first push any discovered DNS configuration into `systemd-resolved`, and deal gracefully with `systemd-resolved` not being available on the bus. If `/etc/resolv.conf` is a not a symlink to `/run/systemd/resolve/resolv.conf` the manager may then proceed and also update `/etc/resolv.conf`. With this mode of operation optimal compatibility is provided, as `systemd-resolved` is used for `/etc/resolv.conf` management when this is configured, but transparent compatibility with non-`systemd-resolved` systems is maintained. Note that `systemd-resolved` is part of systemd, and hence likely to be pretty universally available on Linux systems soon.
+
+By allowing `systemd-resolved` to manage `/etc/resolv.conf` ownership issues regarding different programs overwriting each other's DNS configuration are effectively removed.
--- /dev/null
+---
+title: Writing Resolver Clients
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Writing Resolver Clients
+
+_Or: How to look up hostnames and arbitrary DNS Resource Records via \_systemd-resolved_'s bus APIs\_
+
+_(This is a longer explanation how to use some parts of \_systemd-resolved_ bus API. If you are just looking for an API reference, consult the [bus API documentation](https://wiki.freedesktop.org/www/Software/systemd/resolved/) instead.)\_
+
+_systemd-resolved_ provides a set of APIs on the bus for resolving DNS resource records. These are:
+
+1. _ResolveHostname()_ for resolving hostnames to acquire their IP addresses
+2. _ResolveAddress()_ for the reverse operation: acquire the hostname for an IP address
+3. _ResolveService()_ for resolving a DNS-SD or SRV service
+4. _ResolveRecord()_ for resolving arbitrary resource records.
+
+Below you'll find examples for two of these calls, to show how to use them. Note that glibc offers similar (and more portable) calls in _getaddrinfo()_, _getnameinfo()_ and _res_query()_. Of these _getaddrinfo()_ and _getnameinfo()_ are directed to the calls above via the _nss-resolve_ NSS module, but _req_query()_ is not. There are a number of reasons why it might be preferable to invoke _systemd-resolved_'s bus calls rather than the glibc APIs:
+
+1. Bus APIs are naturally asynchronous, which the glibc APIs generally are not.
+2. The bus calls above pass back substantially more information about the resolved data, including where and how the data was found (i.e. which protocol was used: DNS, LLMNR, MulticastDNS, and on which network interface), and most importantly, whether the data could be authenticated via DNSSEC. This in particular makes these APIs useful for retrieving certificate data from the DNS, in order to implement DANE, SSHFP, OPENGPGKEY and IPSECKEY clients.
+3. _ResolveService()_ knows no counterpart in glibc, and has the benefit of being a single call that collects all data necessary to connect to a DNS-SD or pure SRV service in one step.
+4. _ResolveRecord()_ in contrast to _res_query()_ supports LLMNR and MulticastDNS as protocols on top of DNS, and makes use of _systemd-resolved_'s local DNS record cache. The processing of the request is done in the sandboxed _systemd-resolved_ process rather than in the local process, and all packets are pre-validated. Because this relies on _systemd-resolved_ the per-interface DNS zone handling is supported.
+
+Of course, by using _systemd-resolved_ you lose some portability, but this could be handled via an automatic fallback to the glibc counterparts.
+
+Note that the various resolver calls provided by _systemd-resolved_ will consult _/etc/hosts_ and synthesize resource records for these entries in order to ensure that this file is honoured fully.
+
+The examples below use the _sd-bus_ D-Bus client implementation, which is part of _libsystemd_. Any other D-Bus library, including the original _libdbus_ or _GDBus_ may be used too.
+
+## Resolving a Hostname
+
+To resolve a hostname use the _ResolveHostname()_ call. For details on the function parameters see the [bus API documentation](https://wiki.freedesktop.org/www/Software/systemd/resolved/).
+
+This example specifies _AF_UNSPEC_ as address family for the requested address. This means both an _AF_INET_ (A) and an _AF_INET6_ (AAAA) record is looked for, depending on whether the local system has configured IPv4 and/or IPv6 connectivity. It is generally recommended to request _AF_UNSPEC_ addresses for best compatibility with both protocols, in particular on dual-stack systems.
+
+The example specifies a network interface index of "0", i.e. does not specify any at all, so that the request may be done on any. Note that the interface index is primarily relevant for LLMNR and MulticastDNS lookups, which distinguish different scopes for each network interface index.
+
+This examples makes no use of either the input flags parameter, nor the output flags parameter. See the _ResolveRecord()_ example below for information how to make use of the _SD_RESOLVED_AUTHENTICATED_ bit in the returned flags paramter.
+
+```
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/socket.h>
+#include <systemd/sd-bus.h>
+
+int main(int argc, char*argv[]) {
+ sd_bus_error error = SD_BUS_ERROR_NULL;
+ sd_bus_message *reply = NULL;
+ const char *canonical;
+ sd_bus *bus = NULL;
+ uint64_t flags;
+ int r;
+
+ r = sd_bus_open_system(&bus);
+ if (r < 0) {
+ fprintf(stderr, "Failed to open system bus: %s\n", strerror(-r));
+ goto finish;
+ }
+
+ r = sd_bus_call_method(bus,
+ "org.freedesktop.resolve1",
+ "/org/freedesktop/resolve1",
+ "org.freedesktop.resolve1.Manager",
+ "ResolveHostname",
+ &error,
+ &reply,
+ "isit",
+ 0, /* Network interface index where to look (0 means any) */
+ argc >= 2 ? argv[1] : "www.github.com", /* Hostname */
+ AF_UNSPEC, /* Which address family to look for */
+ UINT64_C(0)); /* Input flags parameter */
+ if (r < 0) {
+ fprintf(stderr, "Failed to resolve hostnme: %s\n", error.message);
+ sd_bus_error_free(&error);
+ goto finish;
+ }
+
+ r = sd_bus_message_enter_container(reply, 'a', "(iiay)");
+ if (r < 0)
+ goto parse_failure;
+
+ for (;;) {
+ char buf[INET6_ADDRSTRLEN];
+ int ifindex, family;
+ const void *data;
+ size_t length;
+
+ r = sd_bus_message_enter_container(reply, 'r', "iiay");
+ if (r < 0)
+ goto parse_failure;
+ if (r == 0) /* Reached end of array */
+ break;
+ r = sd_bus_message_read(reply, "ii", &ifindex, &family);
+ if (r < 0)
+ goto parse_failure;
+ r = sd_bus_message_read_array(reply, 'y', &data, &length);
+ if (r < 0)
+ goto parse_failure;
+ r = sd_bus_message_exit_container(reply);
+ if (r < 0)
+ goto parse_failure;
+
+ printf("Found IP address %s on interface %i.\n", inet_ntop(family, data, buf, sizeof(buf)), ifindex);
+ }
+
+ r = sd_bus_message_exit_container(reply);
+ if (r < 0)
+ goto parse_failure;
+ r = sd_bus_message_read(reply, "st", &canonical, &flags);
+ if (r < 0)
+ goto parse_failure;
+
+ printf("Canonical name is %s\n", canonical);
+ goto finish;
+
+parse_failure:
+ fprintf(stderr, "Parse failure: %s\n", strerror(-r));
+
+finish:
+ sd_bus_message_unref(reply);
+ sd_bus_flush_close_unref(bus);
+ return r < 0 ? EXIT_FAILURE : EXIT_SUCCESS;
+}
+```
+
+Compile this with a command line like the following (under the assumption you save the sources above as `addrtest.c`):
+
+```
+gcc addrtest.c -o addrtest -Wall `pkg-config --cflags --libs libsystemd`
+```
+
+## Resolving an Abitrary DNS Resource Record
+
+Use `ResolveRecord()` in order to resolve arbitrary resource records. The call will return the binary RRset data. This calls is useful to acquire resource records for which no high-level calls such as ResolveHostname(), ResolveAddress() and ResolveService() exist. In particular RRs such as MX, SSHFP, TLSA, CERT, OPENPGPKEY or IPSECKEY may be requested via this API.
+
+This example also shows how to determine whether the acquired data has been authenticated via DNSSEC (or another means) by checking the `SD_RESOLVED_AUTHENTICATED` bit in the
+returned `flags` parameter.
+
+This example contains a simple MX record parser. Note that the data comes pre-validated from `systemd-resolved`, hence we allow the example to parse the record slightly sloppily, to keep the example brief. For details on the MX RR binary format, see [RFC 1035](https://www.rfc-editor.org/rfc/rfc1035.txt).
+
+For details on the function parameters see the [bus API documentation](https://wiki.freedesktop.org/www/Software/systemd/resolved/).
+
+```
+#include <assert.h>
+#include <endian.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <systemd/sd-bus.h>
+
+#define DNS_CLASS_IN 1U
+#define DNS_TYPE_MX 15U
+
+#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9)
+
+static const uint8_t* print_name(const uint8_t* p) {
+ bool dot = false;
+ for (;;) {
+ if (*p == 0)
+ return p + 1;
+ if (dot)
+ putchar('.');
+ else
+ dot = true;
+ printf("%.*s", (int) *p, (const char*) p + 1);
+ p += *p + 1;
+ }
+}
+
+static void process_mx(const void *rr, size_t sz) {
+ uint16_t class, type, rdlength, preference;
+ const uint8_t *p = rr;
+ uint32_t ttl;
+
+ fputs("Found MX: ", stdout);
+ p = print_name(p);
+
+ memcpy(&type, p, sizeof(uint16_t));
+ p += sizeof(uint16_t);
+ memcpy(&class, p, sizeof(uint16_t));
+ p += sizeof(uint16_t);
+ memcpy(&ttl, p, sizeof(uint32_t));
+ p += sizeof(uint32_t);
+ memcpy(&rdlength, p, sizeof(uint16_t));
+ p += sizeof(uint16_t);
+ memcpy(&preference, p, sizeof(uint16_t));
+ p += sizeof(uint16_t);
+
+ assert(be16toh(type) == DNS_TYPE_MX);
+ assert(be16toh(class) == DNS_CLASS_IN);
+ printf(" preference=%u ", be16toh(preference));
+
+ p = print_name(p);
+ putchar('\n');
+
+ assert(p == (const uint8_t*) rr + sz);
+}
+
+int main(int argc, char*argv[]) {
+ sd_bus_error error = SD_BUS_ERROR_NULL;
+ sd_bus_message *reply = NULL;
+ sd_bus *bus = NULL;
+ uint64_t flags;
+ int r;
+
+ r = sd_bus_open_system(&bus);
+ if (r < 0) {
+ fprintf(stderr, "Failed to open system bus: %s\n", strerror(-r));
+ goto finish;
+ }
+
+ r = sd_bus_call_method(bus,
+ "org.freedesktop.resolve1",
+ "/org/freedesktop/resolve1",
+ "org.freedesktop.resolve1.Manager",
+ "ResolveRecord",
+ &error,
+ &reply,
+ "isqqt",
+ 0, /* Network interface index where to look (0 means any) */
+ argc >= 2 ? argv[1] : "gmail.com", /* Domain name */
+ DNS_CLASS_IN, /* DNS RR class */
+ DNS_TYPE_MX, /* DNS RR type */
+ UINT64_C(0)); /* Input flags parameter */
+ if (r < 0) {
+ fprintf(stderr, "Failed to resolve record: %s\n", error.message);
+ sd_bus_error_free(&error);
+ goto finish;
+ }
+
+ r = sd_bus_message_enter_container(reply, 'a', "(iqqay)");
+ if (r < 0)
+ goto parse_failure;
+
+ for (;;) {
+ uint16_t class, type;
+ const void *data;
+ size_t length;
+ int ifindex;
+
+ r = sd_bus_message_enter_container(reply, 'r', "iqqay");
+ if (r < 0)
+ goto parse_failure;
+ if (r == 0) /* Reached end of array */
+ break;
+ r = sd_bus_message_read(reply, "iqq", &ifindex, &class, &type);
+ if (r < 0)
+ goto parse_failure;
+ r = sd_bus_message_read_array(reply, 'y', &data, &length);
+ if (r < 0)
+ goto parse_failure;
+ r = sd_bus_message_exit_container(reply);
+ if (r < 0)
+ goto parse_failure;
+
+ process_mx(data, length);
+ }
+
+ r = sd_bus_message_exit_container(reply);
+ if (r < 0)
+ goto parse_failure;
+ r = sd_bus_message_read(reply, "t", &flags);
+ if (r < 0)
+ goto parse_failure;
+
+ printf("Response is authenticated: %s\n", flags & SD_RESOLVED_AUTHENTICATED ? "yes" : "no");
+ goto finish;
+
+parse_failure:
+ fprintf(stderr, "Parse failure: %s\n", strerror(-r));
+
+finish:
+ sd_bus_message_unref(reply);
+ sd_bus_flush_close_unref(bus);
+ return r < 0 ? EXIT_FAILURE : EXIT_SUCCESS;
+ }
+```
+
+Compile this with a command line like the following (under the assumption you save the sources above as `rrtest.c`):
+
+```
+gcc rrtest.c -o rrtest -Wall `pkg-config --cflags --libs libsystemd`
+```
--- /dev/null
+---
+title: Writing VM and Container Managers
+category: Documentation for Developers
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+
+# Writing VM and Container Managers
+
+_Or: How to hook up your favorite VM or container manager with systemd_
+
+Nomenclature: a _Virtual Machine_ shall refer to a system running on virtualized hardware consisting of a full OS with its own kernel. A _Container_ shall refer to a system running on the same shared kernel of the host, but running a mostly complete OS with its own init system. Both kinds of virtualized systems shall collectively be called "machines".
+
+systemd provides a number of integration points with virtual machine and container managers, such as libvirt, LXC or systemd-nspawn. On one hand there are integration points of the VM/container manager towards the host OS it is running on, and on the other there integration points for container managers towards the guest OS it is managing.
+
+Note that this document does not cover lightweight containers for the purpose of application sandboxes, i.e. containers that do _not_ run a init system of their own.
+
+## Host OS Integration
+
+All virtual machines and containers should be registered with the [machined](http://www.freedesktop.org/wiki/Software/systemd/machined) mini service that is part of systemd. This provides integration into the core OS at various points. For example, tools like ps, cgls, gnome-system-manager use this registration information to show machine information for running processes, as each of the VM's/container's processes can reliably attributed to a registered machine. The various systemd tools (like systemctl, journalctl, loginctl, systemd-run, ...) all support a -M switch that operates on machines registered with machined. "machinectl" may be used to execute operations on any such machine. When a machine is registered via machined its processes will automatically be placed in a systemd scope unit (that is located in the machines.slice slice) and thus appear in "systemctl" and similar commands. The scope unit name is based on the machine meta information passed to machined at registration.
+
+For more details on the APIs provided by machine consult [the bus API interface documentation](http://www.freedesktop.org/wiki/Software/systemd/machined).
+
+## 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](http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface).
+
+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. This is read in the guest via /sys/class/dmi/id/product_uuid, and used as configuration source for /etc/machine-id if in the guest, if that file is not initialized yet. Note that this is currently only supported for kvm hosts, but may be extended to other managers as well.
Before continuing, please read up on these basic concepts:
-* [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)
+* [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
# JSON Group Records
Long story short: JSON Group Records are to `struct group` what
-[JSON User Records](USER_RECORD.md) 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
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.md). It is recommended to bring the
+[`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. Since the user record is cryptographically signed, the
Before reading on, please read up on the basic concepts, specifically:
-* [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)
+* [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.md).
+[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.md)
-and [JSON Group Records](GROUP_RECORD.md) 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.md) 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.md) 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
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.md). 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.
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.md) for
+`/etc/shadow`). 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. This concept allows distinguishing
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.md)
+ [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.md).
+ 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.md)._
+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.md)._
+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)._
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.md)
+[Journal Export Format or Journal JSON Format](JOURNAL_EXPORT_FORMATS)
instead! This document is primarily for your entertainment and education.
Thank you!_
| [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.md) | Environment, flag files | yes | yes | mkosi, 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 |
+| [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.md) | `/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.md) | File format | yes | yes | - | maybe | - | no |
+| [Journal File Format](JOURNAL_FILE_FORMAT) | 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](PASSWORD_AGENTS.md) | Socket+Files | yes | yes | - | yes | - | 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 |
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.md) 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.md).
+* Consider having a look at the [initrd Interface of systemd](INITRD_INTERFACE).
--- /dev/null
+---
+title: API File Systems
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# API File Systems
+
+_So you are seeing all kinds of weird file systems in the output of mount(8) that are not listed in `/etc/fstab`, and you wonder what those are, how you can get rid of them, or at least change their mount options._
+
+The Linux kernel provides a number of different ways for userspace to communicate with it. For many facilities there are system calls, others are hidden behind Netlink interfaces, and even others are exposed via virtual file systems such as `/proc` or `/sys`. These file systems are programming interfaces, they are not actually backed by real, persistent storage. They simply use the file system interface of the kernel as interface to various unrelated mechanisms. Similarly, there are file systems that userspace uses for its own API purposes, to store shared memory segments, shared temporary files or sockets. In this article we want to discuss all these kind of _API file systems_. More specifically, here's a list of these file systems typical Linux systems currently have:
+
+* `/sys` for exposing kernel devices, drivers and other kernel information to userspace
+* `/proc` for exposing kernel settings, processes and other kernel information to userspace
+* `/dev` for exposing kernel device nodes to userspace
+* `/run` as location for userspace sockets and files
+* `/tmp` as location for volatile, temporary userspace file system objects (X)
+* `/sys/fs/cgroup` (and file systems below that) for exposing the kernel control group hierarchy
+* `/sys/kernel/security`, `/sys/kernel/debug` (X), `/sys/kernel/config` (X) for exposing special purpose kernel objects to userspace
+* `/sys/fs/selinux` for exposing SELinux security data to userspace
+* `/dev/shm` as location for userspace shared memory objects
+* `/dev/pts` for exposing kernel pseudo TTY device nodes to userspace
+* `/proc/sys/fs/binfmt_misc` for registering additional binary formats in the kernel (X)
+* `/dev/mqueue` for exposing mqueue IPC objects to userspace (X)
+* `/dev/hugepages` as a userspace API for allocating "huge" memory pages (X)
+* `/sys/fs/fuse/connections` for exposing kernel FUSE connections to userspace (X)
+* `/sys/firmware/efi/efivars` for exposing firmware variables to userspace
+
+All these _API file systems_ are mounted during very early boot-up of systemd and are generally not listed in `/etc/fstab`. Depending on the used kernel configuration some of these API file systems might not be available and others might exist instead. As these interfaces are important for kernel-to-userspace and userspace-to-userspace communication they are mounted automatically and without configuration or interference by the user. Disabling or changing their parameters might hence result in applications breaking as they can no longer access the interfaces they need.
+
+Even though the default settings of these file systems should normally be suitable for most setups, in some cases it might make sense to change the mount options, or possibly even disable some of these file systems.
+
+Even though normally none of these API file systems are listed in `/etc/fstab` they may be added there. If so, any options specified therein will be applied to that specific API file system. Hence: to alter the mount options or other parameters of these file systems, simply add them to `/etc/fstab` with the appropriate settings and you are done. Using this technique it is possible to change the source, type of a file system in addition to simply changing mount options. That is useful to turn `/tmp` to a true file system backed by a physical disk.
+
+It is possible to disable the automatic mounting of some (but not all) of these file systems, if that is required. These are marked with (X) in the list above. You may disable them simply by masking them:
+
+```sh
+systemctl mask dev-hugepages.mount
+```
+
+This has the effect that the huge memory page API FS is not mounted by default, starting with the next boot. See [Three Levels of Off](http://0pointer.de/blog/projects/three-levels-of-off.html) for more information on masking.
+
+The systemd service [systemd-remount-fs.service](http://www.freedesktop.org/software/systemd/man/systemd-remount-fs.service.html) is responsible for applying mount parameters from `/etc/fstab` to the actual mounts.
+
+## Why are you telling me all this? I just want to get rid of the tmpfs backed /tmp!
+
+You have three options:
+
+1. Disable any mounting on `/tmp` so that it resides on the same physical file system as the root directory. For that, execute `systemctl mask tmp.mount`
+2. Mount a different, physical file system to `/tmp`. For that, simply create an entry for it in `/etc/fstab` as you would do for any other file system.
+3. Keep `/tmp` but increase/decrease the size of it. For that, also just create an entry for it in `/etc/fstab` as you would do for any other `tmpfs` file system, and use the right `size=` option.
+
--- /dev/null
+---
+title: Socket Activation with Popular Daemons
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+## nginx
+
+nginx includes an undocumented, internal socket-passing mechanism based on the `NGINX` environmental variable. It uses this to perform reloads without having to close and reopen its sockets, but it's also useful for socket activation.
+
+**/etc/nginx/my-nginx.conf**
+
+```
+http {
+ server {
+ listen [::]:80 ipv6only=on;
+ listen 80;
+ }
+}
+```
+
+**/etc/systemd/system/my-nginx.service**
+
+```
+[Service]
+User=nginx
+Group=nginx
+Environment=NGINX=3:4;
+ExecStart=/usr/sbin/nginx -c/etc/nginx/my-nginx.conf
+PrivateNetwork=true
+```
+
+
+**/etc/systemd/system/my-nginx.socket**
+
+```
+[Socket]
+ListenStream=80
+ListenStream=0.0.0.0:80
+BindIPv6Only=ipv6-only
+After=network.target
+Requires=network.target
+
+[Install]
+WantedBy=sockets.target
+```
+
+
+## PHP-FPM
+
+Like nginx, PHP-FPM includes a socket-passing mechanism an environmental variable. In PHP-FPM's case, it's `FPM_SOCKETS`.
+
+This configuration is possible with any web server that supports FastCGI (like Apache, Lighttpd, or nginx). The web server does not need to know anything special about the socket; use a normal PHP-FPM configuration.
+
+Paths are based on a Fedora 19 system.
+
+### First, the configuration files
+
+**/etc/php-fpm.d/my-php-fpm-pool.conf**
+
+```
+[global]
+pid = /run/my-php-fpm-pool.pid ; Not really used by anything with daemonize = no, but needs to be writable.
+error_log = syslog ; Will aggregate to the service's systemd journal.
+daemonize = no ; systemd handles the forking.
+
+[www]
+listen = /var/run/my-php-fpm-pool.socket ; Must match systemd socket unit.
+user = nginx ; Ignored but required.
+group = nginx ; Ignored but required.
+pm = static
+pm.max_children = 10
+slowlog = syslog
+```
+
+
+**/etc/systemd/system/my-php-fpm-pool.service**
+
+```
+[Service]
+User=nginx
+Group=nginx
+Environment="FPM_SOCKETS=/var/run/my-php-fpm-pool.socket=3"
+ExecStart=/usr/sbin/php-fpm --fpm-config=/etc/php-fpm.d/my-php-fpm-pool.conf
+KillMode=process
+```
+
+
+**/etc/systemd/system/my-php-fpm-pool.socket**
+
+```
+[Socket]
+ListenStream=/var/run/my-php-fpm-pool.socket
+
+[Install]
+WantedBy=sockets.target
+```
+
+
+### Second, the setup commands
+
+```sh
+sudo systemctl --system daemon-reload
+sudo systemctl start my-php-fpm-pool.socket
+sudo systemctl enable my-php-fpm-pool.socket
+```
+
+
+After accessing the web server, the service should be running.
+
+```sh
+sudo systemctl status my-php-fpm-pool.service
+```
+
+
+It's possible to shut down the service and re-activate it using the web browser, too. It's necessary to stop and start the socket to reset some shutdown PHP-FPM does that otherwise breaks reactivation.
+
+```sh
+sudo systemctl stop my-php-fpm-pool.socket my-php-fpm-pool.service
+sudo systemctl start my-php-fpm-pool.socket
+```
+
--- /dev/null
+---
+title: Diagnosing Boot Problems
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Diagnosing Boot Problems
+
+If your machine gets stuck during boot, first check if the hang happens before or after control passes to systemd.
+
+Try to boot without `rhgb` and `quiet` on the kernel command line. If you see some messages like these:
+
+* Welcome to Fedora _VERSION_ (_codename_)!"
+* Starting _name_...
+* \[ OK \] Started _name_.
+
+then systemd is running. (See an actual [screenshot](f17boot.png).)
+
+Debugging always gets easier if you can get a shell. If you do not get a login prompt, try switching to a different virtual terminal using CTRL+ALT+F\_\_. Problems with a display server startup may manifest themselves as a missing login on tty1, but other VTs working.
+
+If the boot stops without presenting you with a login on any virtual console, let it retry for _up to 5 minutes_ before declaring it definitely stuck. There is a chance that a service that has trouble starting will be killed after this timeout and the boot will continue normally. Another possibility is that a device for an important mountpoint will fail to appear and you will be presented with _emergency mode_.
+
+## If You Get No Shell
+
+If you get neither a normal login nor the emergency mode shell, you will need to do additional steps to get debugging information out of the machine.
+
+* Try CTRL+ALT+DEL to reboot.
+ * If it does not reboot, mention it in your bugreport. Meanwhile force the reboot with [SysRq](http://fedoraproject.org/wiki/QA/Sysrq) or hard reset.
+* When booting the next time, you will have to add some kernel command line arguments depending on which of the debugging strategies you choose from the following options.
+
+### Debug Logging to a Serial Console
+
+If you have a hardware serial console available or if you are debugging in a virtual machine (e.g. using virt-manager you can switch your view to a serial console in the menu View -> Text Consoles or connect from the terminal using `virsh console MACHINE`), you can ask systemd to log lots of useful debugging information to it by booting with:
+
+```sh
+systemd.log_level=debug systemd.log_target=console console=ttyS0,38400 console=tty1
+```
+
+
+The above is useful if pid 1 is failing, but if a later but critical boot service is broken (such as networking), you can configure journald to forward to the console by using:
+
+```sh
+systemd.journald.forward_to_console=1 console=ttyS0,38400 console=tty1
+```
+
+console= can be specified multiple times, systemd will output to all of them.
+
+### Booting into Rescue or Emergency Targets
+
+To boot directly into rescue target add `systemd.unit=rescue.target` or just `1` to the kernel command line. This target is useful if the problem occurs somewhere after the basic system is brought up, during the starting of "normal" services. If this is the case, you should be able to disable the bad service from here. If the rescue target will not boot either, the more minimal emergency target might.
+
+To boot directly into emergency shell add `systemd.unit=emergency.target` or `emergency` to the kernel command line. Note that in the emergency shell you will have to remount the root filesystem read-write by yourself before editing any files:
+
+```sh
+mount -o remount,rw /
+```
+
+Common issues that can be resolved in the emergency shell are bad lines in **/etc/fstab**. After fixing **/etc/fstab**, run `systemctl daemon-reload` to let systemd refresh its view of it.
+
+If not even the emergency target works, you can boot directly into a shell with `init=/bin/sh`. This may be necessary in case systemd itself or some libraries it depends on are damaged by filesystem corruption. You may need to reinstall working versions of the affected packages.
+
+If `init=/bin/sh` does not work, you must boot from another medium.
+
+### Early Debug Shell
+
+You can enable shell access to be available very early in the startup process to fall back on and diagnose systemd related boot up issues with various systemctl commands. Enable it using:
+
+```sh
+systemctl enable debug-shell.service
+```
+
+or by specifying
+
+```sh
+systemd.debug-shell=1
+```
+
+on the kernel command line.
+
+**Tip**: If you find yourself in a situation where you cannot use systemctl to communicate with a running systemd (e.g. when setting this up from a different booted system), you can avoid communication with the manager by specifying `--root=`:
+
+```sh
+systemctl --root=/ enable debug-shell.service
+```
+
+Once enabled, the next time you boot you will be able to switch to tty9 using CTRL+ALT+F9 and have a root shell there available from an early point in the booting process. You can use the shell for checking the status of services, reading logs, looking for stuck jobs with `systemctl list-jobs`, etc.
+
+**Warning:** Use this shell only for debugging! Do not forget to disable systemd-debug-shell.service after you've finished debugging your boot problems. Leaving the root shell always available would be a security risk.
+
+It is also possible to alias `kbrequest.target` to `debug-shell.service` to start the debug shell on demand. This has the same security implications, but avoids running the shell always.
+
+### verify prerequisites
+
+A (at least partly) populated `/dev` is required. Depending on your setup (e.g. on embedded systems), check that the Linux kernel config options `CONFIG_DEVTMPFS` and `CONFIG_DEVTMPFS_MOUNT` are set. Also support for cgroups and fanotify is recommended for a flawless operation, so check that the Linux kernel config options `CONFIG_CGROUPS` and `CONFIG_FANOTIFY` are set. The message "Failed to get D-Bus connection: No connection to service manager." during various `systemctl` operations is an indicator that these are missing.
+
+## If You Can Get a Shell
+
+When you have systemd running to the extent that it can provide you with a shell, please use it to extract useful information for debugging. Boot with these parameters on the kernel command line:
+
+```sh
+systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M printk.devkmsg=on
+```
+
+in order to increase the verbosity of systemd, to let systemd write its logs to the kernel log buffer, to increase the size of the kernel log buffer, and to prevent the kernel from discarding messages. After reaching the shell, look at the log:
+
+```sh
+journalctl -b
+```
+
+When reporting a bug, pipe that to a file and attach it to the bug report.
+
+To check for possibly stuck jobs use:
+
+```sh
+systemctl list-jobs
+```
+
+The jobs that are listed as "running" are the ones that must complete before the "waiting" ones will be allowed to start executing.
+
+
+# Diagnosing Shutdown Problems
+
+Just like with boot problems, when you encounter a hang during shutting down, make sure you wait _at least 5 minutes_ to distinguish a permanent hang from a broken service that's just timing out. Then it's worth testing whether the system reacts to CTRL+ALT+DEL in any way.
+
+If shutdown (whether it be to reboot or power-off) of your system gets stuck, first test if the kernel itself is able to reboot or power-off the machine forcedly using one of these commands:
+
+```sh
+reboot -f
+poweroff -f
+```
+
+If either one of the commands does not work, it's more likely to be a kernel, not systemd bug.
+
+## Shutdown Completes Eventually
+
+If normal reboot or poweroff work, but take a suspiciously long time, then
+
+* boot with the debug options:
+
+```sh
+systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M printk.devkmsg=on enforcing=0
+```
+
+* save the following script as **/usr/lib/systemd/system-shutdown/debug.sh** and make it executable:
+
+```sh
+#!/bin/sh
+mount -o remount,rw /
+dmesg > /shutdown-log.txt
+mount -o remount,ro /
+```
+
+* reboot
+
+
+Look for timeouts logged in the resulting file **shutdown-log.txt** and/or attach it to a bugreport.
+
+## Shutdown Never Finishes
+
+If normal reboot or poweroff never finish even after waiting a few minutes, the above method to create the shutdown log will not help and the log must be obtained using other methods. Two options that are useful for debugging boot problems can be used also for shutdown problems:
+
+* use a serial console
+* use a debug shell - not only is it available from early boot, it also stays active until late shutdown.
+
+
+# Status and Logs of Services
+
+When the start of a service fails, systemctl will give you a generic error message:
+
+```sh
+# systemctl start foo.service
+Job failed. See system journal and 'systemctl status' for details.
+```
+
+The service may have printed its own error message, but you do not see it, because services run by systemd are not related to your login session and their outputs are not connected to your terminal. That does not mean the output is lost though. By default the stdout, stderr of services are directed to the systemd _journal_ and the logs that services produce via `syslog(3)` go there too. systemd also stores the exit code of failed services. Let's check:
+
+```sh
+# systemctl status foo.service
+foo.service - mmm service
+ Loaded: loaded (/etc/systemd/system/foo.service; static)
+ Active: failed (Result: exit-code) since Fri, 11 May 2012 20:26:23 +0200; 4s ago
+ Process: 1329 ExecStart=/usr/local/bin/foo (code=exited, status=1/FAILURE)
+ CGroup: name=systemd:/system/foo.service
+
+May 11 20:26:23 scratch foo[1329]: Failed to parse config
+```
+
+
+In this example the service ran as a process with PID 1329 and exited with error code 1. If you run systemctl status as root or as a user from the `adm` group, you will get a few lines from the journal that the service wrote. In the example the service produced just one error message.
+
+To list the journal, use the `journalctl` command.
+
+If you have a syslog service (such as rsyslog) running, the journal will also forward the messages to it, so you'll find them in **/var/log/messages** (depending on rsyslog's configuration).
+
+
+# Reporting systemd Bugs
+
+Be prepared to include some information (logs) about your system as well. These should be complete (no snippets please), not in an archive, uncompressed.
+
+Please report bugs to your distribution's bug tracker first. If you are sure that you are encountering an upstream bug, then first check [for existing bug reports](https://github.com/systemd/systemd/issues/), and if your issue is not listed [file a new bug](https://github.com/systemd/systemd/issues/new).
+
+## Information to Attach to a Bug Report
+
+Whenever possible, the following should be mentioned and attached to your bug report:
+
+* The exact kernel command-line used. Typically from the bootloader configuration file (e.g. **/boot/grub2/grub.cfg**) or from **/proc/cmdline**
+* The journal (the output of `journalctl -b > journal.txt`)
+ * ideally after booting with `systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M printk.devkmsg=on`
+* The output of a systemd dump: `systemd-analyze dump > systemd-dump.txt`
+* The output of `/usr/lib/systemd/systemd --test --system --log-level=debug > systemd-test.txt 2>&1`
+
--- /dev/null
+---
+title: Frequently Asked Questions
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Frequently Asked Questions
+
+Also check out the [Tips & Tricks](../TIPS_AND_TRICKS)!
+
+**Q: How do I change the current runlevel?**
+
+A: In systemd runlevels are exposed via "target units". You can change them like this:
+
+```sh
+# systemctl isolate runlevel5.target
+```
+
+Note however, that the concept of runlevels is a bit out of date, and it is usually nicer to use modern names for this. e.g.:
+
+```sh
+# systemctl isolate graphical.target
+```
+
+This will only change the current runlevel, and has no effect on the next boot.
+
+**Q: How do I change the default runlevel to boot into?**
+
+A: The symlink /etc/systemd/system/default.target controls where we boot into by default. Link it to the target unit of your choice. For example, like this:
+
+```sh
+# ln -sf /usr/lib/systemd/system/multi-user.target /etc/systemd/system/default.target
+```
+
+or
+
+```sh
+# ln -sf /usr/lib/systemd/system/graphical.target /etc/systemd/system/default.target
+```
+
+**Q: How do I figure out the current runlevel?**
+
+A: Note that there might be more than one target active at the same time. So the question regarding _the_ runlevel might not always make sense. Here's how you would figure out all targets that are currently active:
+
+```sh
+$ systemctl list-units --type=target
+```
+
+If you are just interested in a single number, you can use the venerable _runlevel_ command, but again, its output might be misleading.
+
+**Q: I want to change a service file, but rpm keeps overwriting it in /usr/lib/systemd/system all the time, how should I handle this?**
+
+A: The recommended way is to copy the service file from /usr/lib/systemd/system to /etc/systemd/system and edit it there. The latter directory takes precedence over the former, and rpm will never overwrite it. If you want to use the distributed service file again you can simply delete (or rename) the service file in /etc/systemd/system again.
+
+**Q: My service foo.service as distributed by my operating system vendor is only started when (a connection comes in or some hardware is plugged in). I want to have it started always on boot, too. What should I do?**
+
+A: Simply place a symlink from that service file in the multi-user.target.wants/ directory (which is where you should symlink everything you want to run in the old runlevel 3, i.e. the normal boot-up without graphical UI. It is pulled in by graphical.target too, so will be started for graphical boot-ups, too):
+
+```sh
+# ln -sf /usr/lib/systemd/system/foobar.service /etc/systemd/system/multi-user.target.wants/foobar.service
+# systemctl daemon-reload
+```
+
+**Q: I want to enable another getty, how would I do that?**
+
+A: Simply instantiate a new getty service for the port of your choice (internally, this places another symlink for instantiating another serial getty in the getty.target.wants/ directory).
+```sh
+# systemctl enable serial-getty@ttyS2.service
+# systemctl start serial-getty@ttyS2.service
+```
+
+Note that gettys on the virtual console are started on demand. You can control how many you get via the NAutoVTs= setting in [logind.conf(7)](http://www.freedesktop.org/software/systemd/man/logind.html). Also see [this blog story](http://0pointer.de/blog/projects/serial-console.html).
+
+**Q: How to I figure out which service a process belongs to?**
+
+A: You may either use ps for that:
+
+```sh
+$ alias psc='ps xawf -eo pid,user,cgroup,args'
+$ psc
+...
+```
+
+Or you can even check /proc/$PID/cgroup directly. Also see [this blog story](http://0pointer.de/blog/projects/systemd-for-admins-2.html).
+
+**Q: Why don't you use inotify to reload the unit files automatically on change?**
+
+A: Unfortunately that would be a racy operation. For an explanation why and how we tried to improve the situation, see [the bugzilla report about this](https://bugzilla.redhat.com/show_bug.cgi?id=615527).
+
+**Q: I have a native systemd service file and a SysV init script installed which share the same basename, e.g. /usr/lib/systemd/system/foobar.service vs. /etc/init.d/foobar -- which one wins?**
+
+A: If both files are available the native unit file always takes precedence and the SysV init script is ignored, regardless whether either is enabled or disabled. Note that a SysV service that is enabled but overridden by a native service does not have the effect that the native service would be enabled, too. Enabling of native and SysV services is completely independent. Or in other words: you cannot enable a native service by enabling a SysV service by the same name, and if a SysV service is enabled but the respective native service is not, this will not have the effect that the SysV script is executed.
+
+**Q: How can I use journalctl to display full (= not truncated) messages even if less is not used?**
+
+A: Use:
+
+```sh
+# journalctl --full
+```
+
+
+**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.
+
+**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)
+
+**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)
+
--- /dev/null
+---
+title: Compatibility with SysV
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Compatibility with SysV
+
+systemd provides a fair degree of compatibility with the behavior exposed by the SysV init system as implemented by many distributions. Compatibility is provided both for the user experience and the SysV scripting APIs. However, there are some areas where compatibility is limited due to technical reasons or design decisions of systemd and the distributions. All of the following applies to SysV init scripts handled by systemd, however a number of them matter only on specific distributions. Many of the incompatibilities are specific to distribution-specific extensions of LSB/SysV init.
+
+* If your distribution removes SysV init scripts in favor of systemd unit files typing "/etc/init.d/foobar start" to start a service will not work, since the script will not be available. Use the more correct "/sbin/service foobar start" instead, and your command will be forwarded to systemd. Note that invoking the init script directly has always been suboptimal since too much of the caller's execution context (environment block, umask, resource limits, audit trails, ...) ended up being inherited by the service, and invocation via "/sbin/service" used to clean this up at least partially. Invocation via /sbin/service works on both SysV and systemd systems. Also, LSB only standardizes invocation via "/sbin/service" anyway. (Note that some distributions ship both systemd unit files and SysV scripts for the services. For these invoking the init scripts will work as expected and the request be forwarded to systemd in any case.)
+* 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))
+* 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".
+* systemd only stops running services. On traditional SysV a K link installed for shutdown was executed when going down regardless whether the service was started before or not. systemd is more strict here and does not stop service that weren't started in the first place.
+* Note that neither S nor K links for runlevels 0 and 6 have any effect. Running services will be terminated anyway when shutting down, and no new SysV services are started at shut down.
+* If systemd doesn't know which PID is the main PID of a service, it will not be able to track its runtime, and hence a service exiting on its own will not make systemd consider it stopped. Use the Red Hat "pidfile:" syntax in the SysV script header comment block to let systemd know which PID file (and hence PID) belongs to your service. Note that systemd cannot know if a SysV service is one of the kind where the runtime is defined by a specific process or whether it is one where there is none, hence the requirement of explicit configuration of a PID file in order to make systemd track the process lifetime. (Note that the Red Hat "pidfile:" stanza may only appear once in init scripts.)
+* Runlevels are supported in a limited fashion only. SysV runlevels are mapped to systemd target units, however not all systemd target units map back to SysV runlevels. This is due to the fact that systemd targets are a lot more flexible and expressive than SysV runlevels. That means that checks for the current runlevel (with /sbin/runlevel or so) may well return "N" (i.e. unknown runlevel) during normal operation. Scripts that rely on explicit runlevel checks are incompatible with many setups. Avoid runlevel checks like these.
+* Tools like /sbin/chkconfig might return misleading information when used to list enablement status of services. First of all, the tool will only see SysV services, not native units. Secondly, it will only show runlevel-related information (which does not fully map to systemd targets). Finally, the information shown might be overridden by a native unit file.
+* By default runlevels 2,3,4 are all aliases for "multi-user.target". If a service is enabled in one of these runlevels, they'll be enabled in all of these. This is only a default however, and users can easily override the mappings, and split them up into individual runlevels if they want. However, we recommend moving on from runlevels and using the much more expressive target units of systemd.
+* Early boot runlevels as they are used by some distributions are no longer supported. i.e. "fake", distribution-specific runlevels such as "S" or "b" cannot be used with systemd.
+* On SysV systems changes to init scripts or any other files that define the boot process (such as /etc/fstab) usually had an immediate effect on everything started later. This is different on systemd-based systems where init script information and other boot-time configuration files are only reread when "systemctl daemon-reload" is issued. (Note that some commands, notably "systemctl enable"/"systemctl disable" do this implicitly however.) This is by design, and a safety feature, since it ensures that half-completed changes are not read at the wrong time.
+* Multiple entries for the same mount path in /etc/fstab are not supported. In systemd there's only a single unit definition for each mount path read at any time. Also the listing order of mounts in /etc/fstab has no effect, mounts are executed in parallel and dependencies between them generated automatically depending on path prefixes and source paths.
+* systemd's handling of the existing "nofail" mount option in /etc/fstab is stricter than it used to be on some sysvinit distributions: mount points that fail and are not listed as "nofail" will cause the boot to be stopped, for security reasons, as we we should not permit unprivileged code to run without everything listed — and not expressly exempted through "nofail" — being around. Hence, please mark all mounts where booting shall proceed regardless whether they succeeded or not with "nofail"
+* Some SysV systems support an "rc.local" script that is supposed to be called "last" during boot. In systemd, the script is supported, but the semantics are less strict, as there is simply no concept of "last service", as the boot process is event- and request-based, parallelized and compositive. In general, it's a good idea to write proper unit files with properly defined dependncies, and avoid making use of rc.local.
+* systemd assumes that the UID boundary between system and regular users is a choice the distribution makes, and not the administrator. Hence it expects this setting as compile-time option to be picked by the distribution. It will _not_ check /etc/login.defs during runtime.
+
+Note that there are some areas where systemd currently provides a certain amount of compatibility where we expect this compatibility to be removed eventually.
--- /dev/null
+---
+title: My Service Can't Get Realtime!
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# My Service Can't Get Realtime!
+
+_So, you have a service that requires real-time scheduling. When you run this service on your systemd system it is unable to acquire real-time scheduling, even though it is full root and has all possible privileges. And now you are wondering what is going on and what you can do about it?_
+
+## What is Going on?
+
+By default systemd places all system services into their own control groups in the "cpu" hierarchy. This has the benefit that the CPU usage of services with many worker threads or processes (think: Apache with all its gazillion CGIs and stuff) gets roughly the same amount of CPU as a service with very few worker threads (think: MySQL). Instead of evening out CPU _per process_ this will cause CPU to be evened out _per service_.
+
+Now, the "cpu" cgroup controller of the Linux kernel has one major shortcoming: if a cgroup is created it needs an explicit, absolute RT time budget assigned, or otherwise RT is not available to any process in the group, and an attempt to acquire it will fail with EPERM. systemd will not assign any RT time budgets to the "cpu" cgroups it creates, simply because there is no feasible way to do that, since the budget needs to be specified in absolute time units and comes from a fixed pool. Or in other words: we'd love to assign a budget, but there are no sane values we could use. Thus, in its default configuration RT scheduling is simply not available for any system services.
+
+## Working Around the Issue
+
+Of course, that's quite a limitation, so here's how you work around this:
+
+* One option is to simply globally turn off that systemd creates a "cpu" cgroup for each of the system services. For that, edit `/etc/systemd/system.conf` and set `DefaultControllers=` to the empty string, then reboot. (An alternative is to disable the "cpu" controller in your kernel, entirely. systemd will not attempt to make use of controllers that aren't available in the kernel.)
+* Another option is to turn this off for the specific service only. For that, edit your service file, and add `ControlGroup=cpu:/` to its `[Service]` section. This overrides the default logic for this one service only, and places all its processes back in the root cgroup of the "cpu" hierarchy, which has the full RT budget assigned.
+* A third option is to simply assign your service a realtime budget. For that use `ControlGroupAttribute=cpu.rt_runtime_us 500000` in its `[Service]` or suchlike. See [the kernel documentation](http://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt) for details. The latter two options are not available for System V services. A possible solution is to write a small wrapper service file that simply calls the SysV script's start verb in `ExecStart=` and the stop verb in `ExecStop=`. (It also needs to set `RemainAfterExit=1` and `Type=forking`!)
+
+Note that this all only applies to services. By default, user applications run in the root cgroup of the "cpu" hierarchy, which avoids these problems for normal user applications.
+
+In the long run we hope that the kernel is fixed to not require an RT budget to be assigned for any cgroup created before a process can acquire RT (i.e. a process' RT budget should be derived from the nearest ancestor cgroup which has a budget assigned, rather than unconditionally its own uninitialized budget.) Ideally, we'd also like to create a per-user cgroup by default, so that users with many processes get roughly the same amount of CPU as users with very few.
+
--- /dev/null
+---
+title: Booting Without /usr is Broken
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Booting Without /usr is Broken
+
+You probably discovered this page because your shiny new systemd system referred you here during boot time, when it warned you that booting without /usr pre-mounted wasn't supported anymore. And now you wonder what this all is about. Here's an attempt of an explanation:
+
+One thing in advance: systemd itself is actually mostly fine with /usr on a separate file system that is not pre-mounted at boot time. However, the common basic set of OS components of modern Linux machines is not, and has not been in quite some time. And it is unlikely that this is going to be fixed any time soon, or even ever.
+
+Most of the failures you will experience with /usr split off and not pre-mounted in the initramfs are graceful failures: they won't become directly visible, however certain features become unavailable due to these failures. Quite a number of programs these days hook themselves into the early boot process at various stages. A popular way to do this is for example via udev rules. The binaries called from these rules are sometimes located on /usr/bin, or link against libraries in /usr/lib, or use data files from /usr/share. If these rules fail udev will proceed with the next one, however later on applications will then not properly detect these udev devices or features of these devices. Here's a short, very in-comprehensive list of software we are aware of that currently are not able to provide the full set of functionality when /usr is split off and not pre-mounted at boot: udev-pci-db/udev-usb-db and all rules depending on this (using the PCI/USB database in /usr/share), PulseAudio, NetworkManager, ModemManager, udisks, libatasmart, usb\_modeswitch, gnome-color-manager, usbmuxd, ALSA, D-Bus, CUPS, Plymouth, LVM, hplip, multipath, Argyll, VMWare, the locale logic of most programs and a lot of other stuff.
+
+You don't believe us? Well, here's a command line that reveals a few obvious cases of udev rules that will silently fail to work if /usr is split off and not pre-mounted: `egrep 'usb-db|pci-db|FROM_DATABASE|/usr' /*/udev/rules.d/*` -- and you find a lot more if you actually look for it. On my fresh Fedora 15 install that's 23 obvious cases.
+
+## The Status Quo
+
+Due to this, many upstream developers have decided to consider the problem of a separate /usr that is not mounted during early boot an outdated question, and started to close bugs regarding these issues as WONTFIX. We certainly cannot blame them, as the benefit of supporting this is questionable and brings a lot of additional work with it.
+
+And let's clarify a few things:
+
+1. **It isn't systemd's fault.** systemd mostly works fine with /usr on a separate file system that is not pre-mounted at boot.
+2. **systemd is merely the messenger.** Don't shoot the messenger.
+3. **There's no news in all of this.** The message you saw is just a statement of fact, describing the status quo. Things have been this way since a while.
+4. **The message is merely a warning.** You can choose to ignore it.
+5. **Don't blame us**, don't abuse us, it's not our fault. We have been working on the Linux userspace since quite some time, and simply have enough of the constant bug reports regarding these issues, since they are actually very hard to track down because the failures are mostly graceful. Hence we placed this warning into the early boot process of every systemd Linux system with a split off and not pre-mounted /usr, so that people understand what is going on.
+
+## Going Forward
+
+/usr on its own filesystem is useful in some custom setups. But instead of expecting the traditional Unix way to (sometimes mindlessly) distributing tools between /usr and /, and require more and more tools to move to /, we now just expect /usr to be pre-mounted from inside the initramfs, to be available before 'init' starts. The duty of the minimal boot system that consisted of /bin, /sbin and /lib on traditional Unix, has been taken over by the initramfs of modern Linux. An initramfs that supports mounting /usr on top of / before it starts 'init', makes all existing setups work properly.
+
+There is no way to reliably bring up a modern system with an empty /usr. There are two alternatives to fix it: move /usr back to the rootfs or use an initramfs which can hide the split-off from the system.
+
+On the Fedora distribution we have succeeded to clean up the situation and the confusion the current split between / and /usr has created. We have moved all tools that over time have been moved to / back to /usr (where they belong), and the root file system only contains compatibility symlinks for /bin and /sbin into /usr. All binaries of the system are exclusively located within the /usr hierarchy.
+
+In this new definition of /usr, the directory can be mounted read-only by default, while the rootfs may be either read-write or read-only (for stateless systems) and contains only the empty mount point directories, compat-symlinks to /usr and the host-specific data like /etc, /root, /srv. In comparison to today's setups, the rootfs will be very small. The host-specific data will be properly separated from the installed operating system. The new /usr could also easily be shared read-only across several systems. Such a setup would be more efficient, can provide additional security, is more flexible to use, provides saner options for custom setups, and is much simpler to setup and maintain.
+
+For more information on this please continue to [The Case for the /usr Merge](../THE_CASE_FOR_THE_USR_MERGE).
+
--- /dev/null
+---
+title: Tips And Tricks
+category: Manuals and Documentation for Users and Administrators
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Tips & Tricks
+
+Also check out the [Frequently Asked Questions](http://www.freedesktop.org/wiki/Software/systemd/FrequentlyAskedQuestions)!
+
+## Listing running services
+
+```sh
+$ systemctl
+UNIT LOAD ACTIVE SUB JOB DESCRIPTION
+accounts-daemon.service loaded active running Accounts Service
+atd.service loaded active running Job spooling tools
+avahi-daemon.service loaded active running Avahi mDNS/DNS-SD Stack
+bluetooth.service loaded active running Bluetooth Manager
+colord-sane.service loaded active running Daemon for monitoring attached scanners and registering them with colord
+colord.service loaded active running Manage, Install and Generate Color Profiles
+crond.service loaded active running Command Scheduler
+cups.service loaded active running CUPS Printing Service
+dbus.service loaded active running D-Bus System Message Bus
+...
+```
+
+## Showing runtime status
+
+```sh
+$ systemctl status udisks2.service
+udisks2.service - Storage Daemon
+ Loaded: loaded (/usr/lib/systemd/system/udisks2.service; static)
+ Active: active (running) since Wed, 27 Jun 2012 20:49:25 +0200; 1 day and 1h ago
+ Main PID: 615 (udisksd)
+ CGroup: name=systemd:/system/udisks2.service
+ └ 615 /usr/lib/udisks2/udisksd --no-debug
+
+Jun 27 20:49:25 epsilon udisksd[615]: udisks daemon version 1.94.0 starting
+Jun 27 20:49:25 epsilon udisksd[615]: Acquired the name org.freedesktop.UDisks2 on the system message bus
+```
+
+## cgroup tree
+
+```sh
+$ systemd-cgls
+└ system
+├ 1 /usr/lib/systemd/systemd --system --deserialize 18
+├ ntpd.service
+│ └ 8471 /usr/sbin/ntpd -u ntp:ntp -g
+├ upower.service
+│ └ 798 /usr/libexec/upowerd
+├ wpa_supplicant.service
+│ └ 751 /usr/sbin/wpa_supplicant -u -f /var/log/wpa_supplicant.log -c /etc/wpa_supplicant/wpa_supplicant.conf -u -f /var/log/wpa_supplicant.log -P /var/run/wpa_supplicant.pid
+├ nfs-idmap.service
+│ └ 731 /usr/sbin/rpc.idmapd
+├ nfs-rquotad.service
+│ └ 753 /usr/sbin/rpc.rquotad
+├ nfs-mountd.service
+│ └ 732 /usr/sbin/rpc.mountd
+├ nfs-lock.service
+│ └ 704 /sbin/rpc.statd
+├ rpcbind.service
+│ └ 680 /sbin/rpcbind -w
+├ postfix.service
+│ ├ 859 /usr/libexec/postfix/master
+│ ├ 877 qmgr -l -t fifo -u
+│ └ 32271 pickup -l -t fifo -u
+├ colord-sane.service
+│ └ 647 /usr/libexec/colord-sane
+├ udisks2.service
+│ └ 615 /usr/lib/udisks2/udisksd --no-debug
+├ colord.service
+│ └ 607 /usr/libexec/colord
+├ prefdm.service
+│ ├ 567 /usr/sbin/gdm-binary -nodaemon
+│ ├ 602 /usr/libexec/gdm-simple-slave --display-id /org/gnome/DisplayManager/Display1
+│ ├ 612 /usr/bin/Xorg :0 -br -verbose -auth /var/run/gdm/auth-for-gdm-O00GPA/database -seat seat0 -nolisten tcp
+│ └ 905 gdm-session-worker [pam/gdm-password]
+├ systemd-ask-password-wall.service
+│ └ 645 /usr/bin/systemd-tty-ask-password-agent --wall
+├ atd.service
+│ └ 544 /usr/sbin/atd -f
+├ ksmtuned.service
+│ ├ 548 /bin/bash /usr/sbin/ksmtuned
+│ └ 1092 sleep 60
+├ dbus.service
+│ ├ 586 /bin/dbus-daemon --system --address=systemd: --nofork --systemd-activation
+│ ├ 601 /usr/libexec/polkit-1/polkitd --no-debug
+│ └ 657 /usr/sbin/modem-manager
+├ cups.service
+│ └ 508 /usr/sbin/cupsd -f
+├ avahi-daemon.service
+│ ├ 506 avahi-daemon: running [epsilon.local]
+│ └ 516 avahi-daemon: chroot helper
+├ system-setup-keyboard.service
+│ └ 504 /usr/bin/system-setup-keyboard
+├ accounts-daemon.service
+│ └ 502 /usr/libexec/accounts-daemon
+├ systemd-logind.service
+│ └ 498 /usr/lib/systemd/systemd-logind
+├ crond.service
+│ └ 486 /usr/sbin/crond -n
+├ NetworkManager.service
+│ ├ 484 /usr/sbin/NetworkManager --no-daemon
+│ └ 8437 /sbin/dhclient -d -4 -sf /usr/libexec/nm-dhcp-client.action -pf /var/run/dhclient-wlan0.pid -lf /var/lib/dhclient/dhclient-903b6f6aa7a1-46c8-82a9-7f637dfbb3e4-wlan0.lease -cf /var/run/nm-d...
+├ libvirtd.service
+│ ├ 480 /usr/sbin/libvirtd
+│ └ 571 /sbin/dnsmasq --strict-order --bind-interfaces --pid-file=/var/run/libvirt/network/default.pid --conf-file= --except-interface lo --listenaddress 192.168.122.1 --dhcp-range 192.168.122.2,1...
+├ bluetooth.service
+│ └ 479 /usr/sbin/bluetoothd -n
+├ systemd-udev.service
+│ └ 287 /usr/lib/systemd/systemd-udevd
+└ systemd-journald.service
+└ 280 /usr/lib/systemd/systemd-journald
+```
+
+### ps with cgroups
+
+```sh
+$ alias psc='ps xawf -eo pid,user,cgroup,args'
+$ psc
+ PID USER CGROUP COMMAND
+...
+ 1 root name=systemd:/systemd-1 /bin/systemd systemd.log_target=kmsg systemd.log_level=debug selinux=0
+ 415 root name=systemd:/systemd-1/sysinit.service /sbin/udevd -d
+ 928 root name=systemd:/systemd-1/atd.service /usr/sbin/atd -f
+ 930 root name=systemd:/systemd-1/ntpd.service /usr/sbin/ntpd -n
+ 932 root name=systemd:/systemd-1/crond.service /usr/sbin/crond -n
+ 935 root name=systemd:/systemd-1/auditd.service /sbin/auditd -n
+ 943 root name=systemd:/systemd-1/auditd.service \_ /sbin/audispd
+ 964 root name=systemd:/systemd-1/auditd.service \_ /usr/sbin/sedispatch
+ 937 root name=systemd:/systemd-1/acpid.service /usr/sbin/acpid -f
+ 941 rpc name=systemd:/systemd-1/rpcbind.service /sbin/rpcbind -f
+ 944 root name=systemd:/systemd-1/rsyslog.service /sbin/rsyslogd -n -c 4
+ 947 root name=systemd:/systemd-1/systemd-logger.service /lib/systemd/systemd-logger
+ 950 root name=systemd:/systemd-1/cups.service /usr/sbin/cupsd -f
+ 955 dbus name=systemd:/systemd-1/messagebus.service /bin/dbus-daemon --system --address=systemd: --nofork --systemd-activation
+ 969 root name=systemd:/systemd-1/getty@.service/tty6 /sbin/mingetty tty6
+ 970 root name=systemd:/systemd-1/getty@.service/tty5 /sbin/mingetty tty5
+ 971 root name=systemd:/systemd-1/getty@.service/tty1 /sbin/mingetty tty1
+ 973 root name=systemd:/systemd-1/getty@.service/tty4 /sbin/mingetty tty4
+ 974 root name=systemd:/user/lennart/2 login -- lennart
+ 1824 lennart name=systemd:/user/lennart/2 \_ -bash
+ 975 root name=systemd:/systemd-1/getty@.service/tty3 /sbin/mingetty tty3
+ 988 root name=systemd:/systemd-1/polkitd.service /usr/libexec/polkit-1/polkitd
+ 994 rtkit name=systemd:/systemd-1/rtkit-daemon.service /usr/libexec/rtkit-daemon
+...
+```
+
+## Changing the Default Boot Target
+
+```sh
+$ ln -sf /usr/lib/systemd/system/multi-user.target /etc/systemd/system/default.target
+```
+
+This line makes the multi user target (i.e. full system, but no graphical UI) the default target to boot into. This is kinda equivalent to setting runlevel 3 as the default runlevel on Fedora/sysvinit systems.
+
+```sh
+$ ln -sf /usr/lib/systemd/system/graphical.target /etc/systemd/system/default.target
+```
+
+This line makes the graphical target (i.e. full system, including graphical UI) the default target to boot into. Kinda equivalent to runlevel 5 on fedora/sysvinit systems. This is how things are shipped by default.
+
+## What other units does a unit depend on?
+
+For example, if you want to figure out which services a target like multi-user.target pulls in, use something like this:
+
+```sh
+$ systemctl show -p "Wants" multi-user.target
+Wants=rc-local.service avahi-daemon.service rpcbind.service NetworkManager.service acpid.service dbus.service atd.service crond.service auditd.service ntpd.service udisks.service bluetooth.service cups.service wpa_supplicant.service getty.target modem-manager.service portreserve.service abrtd.service yum-updatesd.service upowerd.service test-first.service pcscd.service rsyslog.service haldaemon.service remote-fs.target plymouth-quit.service systemd-update-utmp-runlevel.service sendmail.service lvm2-monitor.service cpuspeed.service udev-post.service mdmonitor.service iscsid.service livesys.service livesys-late.service irqbalance.service iscsi.service netfs.service
+```
+
+Instead of "Wants" you might also try "WantedBy", "Requires", "RequiredBy", "Conflicts", "ConflictedBy", "Before", "After" for the respective types of dependencies and their inverse.
+
+## What would get started if I booted into a specific target?
+
+If you want systemd to calculate the "initial" transaction it would execute on boot, try something like this:
+
+```sh
+$ systemd --test --system --unit=foobar.target
+```
+
+for a boot target foobar.target. Note that this is mostly a debugging tool that actually does a lot more than just calculate the initial transaction, so don't build scripts based on this.
+
Other parts include a logging daemon, utilities to control basic system configuration like the hostname, date, locale, maintain a list of logged-in users and running containers and virtual machines, system accounts, runtime directories and settings, and daemons to manage simple network configuration, network time synchronization, log forwarding, and name resolution.
---
+## Project
+{% for page in site.data.project %}
+* [{{ page.title }}]({{ page.url | relative_url }}){% endfor %}
+
+<!-- Collections -->
+{% for c in site.collections %}
+<!-- hide autegenerated posts collection -->
+{% if c.label != "posts" %}
+## {{ c.title }}
+{% for item in site[c.label] %}
+* [{{ item.title }}]({{ item.url | relative_url }}){% endfor %}
+{% endif %}
+{% endfor %}
-{% assign by_category = site.pages | group_by:"category" %}
-{% assign extra_pages = site.data.extra_pages | group_by:"category" %}
-{% assign merged = by_category | concat: extra_pages | sort:"name" %}
+<!-- external pages -->
+{% assign external_pages = site.data.extra_pages | group_by:"category" %}
-{% for pair in merged %}
- {% if pair.name != "" %}
-## {{ pair.name }}
-{% assign sorted = pair.items | sort:"title" %}{% for page in sorted %}
+{% for category in external_pages %}
+## {{ category.name }}
+{% assign sorted = category.items | sort:"title" %}{% for page in sorted %}
* [{{ page.title }}]({{ page.url | relative_url }}){% endfor %}
- {% endif %}
{% endfor %}
## See also
'LICENSE.LGPL2.1',
'NEWS',
'README',
- 'docs/CODING_STYLE.md',
- 'docs/DISTRO_PORTING.md',
- 'docs/ENVIRONMENT.md',
- 'docs/HACKING.md',
- 'docs/TRANSIENT-SETTINGS.md',
- 'docs/TRANSLATORS.md',
- 'docs/UIDS-GIDS.md',
+ 'docs/_contributing/CODING_STYLE.md',
+ 'docs/_concepts/DISTRO_PORTING.md',
+ 'docs/_interfaces/ENVIRONMENT.md',
+ 'docs/_contributing/HACKING.md',
+ 'docs/_interfaces/TRANSIENT-SETTINGS.md',
+ 'docs/_contributing/TRANSLATORS.md',
+ 'docs/_groups/UIDS-GIDS.md',
install_dir : docdir)
install_subdir('LICENSES',
export PAGER=
# Create a couple of user/group records to test io.systemd.DropIn
-# See docs/USER_RECORD.md and docs/GROUP_RECORD.md
+# See docs/_groups/USER_RECORD.md and docs/_groups/GROUP_RECORD.md
mkdir -p /run/userdb/
cat >"/run/userdb/dropingroup.group" <<\EOF
{
projects / thirdparty / systemd.git / commitdiff
