proxmox-mirrors/systemd
1
0
Fork 0
mirror of https://git.proxmox.com/git/systemd synced 2025-05-28 08:02:26 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

New upstream version 246

Browse Source
This commit is contained in:
Michael Biebl 2020-07-30 21:55:53 +02:00
parent 478ed93856
commit a10f5d05b9
1606 changed files with 73178 additions and 25045 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
.clang-format Normal file
View File

@ -0,0 +1,126 @@
# This configuration file can be used to auto-format the code base.
# Not all guidelines specified in CODING_STYLE are followed, so the
# result MUST NOT be committed indiscriminately, but each automated
# change should be reviewed and only the appropriate ones commited.
#
# The easiest way to apply the formatting to your changes ONLY,
# is to use the git-clang-format script (usually installed with clang-format).
#
# - Fix up formatting before committing
# 1. Edit and stage your files.
# 2. Run `git clang-format`.
# 3. Verify + correct + (un)stage changes.
# 4. Commit.
#
# - Fix up formatting after committing
# 1. Commit your changes.
# 2. Run `git clang-format HEAD~` - Refer the commit *before* your changes here.
# 3. Verify + correct changes, `git difftool -d` can help here.
# 4. Stage + commit, potentially with `--amend` (means to fixup the last commit).
#
# To run clang-format on all sourcefiles, use the following line:
# $ git ls-files 'src/*.[ch]' 'src/*.cc' | xargs clang-format -i -style=file
#
# You can find more information on the different config parameters in this file here:
# https://clang.llvm.org/docs/ClangFormatStyleOptions.html
---
AccessModifierOffset: -4
AlignAfterOpenBracket: AlwaysBreak
AlignEscapedNewlines: Left
AlignOperands: false
AllowShortFunctionsOnASingleLine: None
AlwaysBreakBeforeMultilineStrings: true
AlwaysBreakTemplateDeclarations: Yes
BinPackArguments: false
BinPackParameters: false
BraceWrapping:
AfterEnum: false
SplitEmptyFunction: false
SplitEmptyRecord: false
SplitEmptyNamespace: false
BreakBeforeBraces: Custom
BreakInheritanceList: BeforeComma
BreakBeforeTernaryOperators: false
BreakStringLiterals: false
ColumnLimit: 109
CompactNamespaces: true
ConstructorInitializerAllOnOneLineOrOnePerLine: true
ConstructorInitializerIndentWidth: 8
ContinuationIndentWidth: 8
Cpp11BracedListStyle: false
ForEachMacros:
- BITMAP_FOREACH
- CMSG_FOREACH
- _DNS_ANSWER_FOREACH
- DNS_ANSWER_FOREACH
- _DNS_ANSWER_FOREACH_FLAGS
- DNS_ANSWER_FOREACH_FLAGS
- _DNS_ANSWER_FOREACH_FULL
- DNS_ANSWER_FOREACH_FULL
- _DNS_ANSWER_FOREACH_IFINDEX
- DNS_ANSWER_FOREACH_IFINDEX
- _DNS_QUESTION_FOREACH
- DNS_QUESTION_FOREACH
- FDSET_FOREACH
- FOREACH_BTRFS_IOCTL_SEARCH_HEADER
- FOREACH_DEVICE
- FOREACH_DEVICE_AND_SUBSYSTEM
- FOREACH_DEVICE_DEVLINK
- FOREACH_DEVICE_PROPERTY
- FOREACH_DEVICE_SYSATTR
- FOREACH_DEVICE_TAG
- FOREACH_DIRENT
- FOREACH_DIRENT_ALL
- FOREACH_INOTIFY_EVENT
- FOREACH_STRING
- FOREACH_SUBSYSTEM
- _FOREACH_WORD
- FOREACH_WORD
- FOREACH_WORD_SEPARATOR
- HASHMAP_FOREACH
- HASHMAP_FOREACH_IDX
- HASHMAP_FOREACH_KEY
- JOURNAL_FOREACH_DATA_RETVAL
- JSON_VARIANT_ARRAY_FOREACH
- JSON_VARIANT_OBJECT_FOREACH
- LIST_FOREACH
- LIST_FOREACH_AFTER
- LIST_FOREACH_BEFORE
- LIST_FOREACH_OTHERS
- LIST_FOREACH_SAFE
- MESSAGE_FOREACH_PART
- NULSTR_FOREACH
- NULSTR_FOREACH_PAIR
- OBJECT_PATH_FOREACH_PREFIX
- ORDERED_HASHMAP_FOREACH
- ORDERED_HASHMAP_FOREACH_KEY
- ORDERED_SET_FOREACH
- PATH_FOREACH_PREFIX
- PATH_FOREACH_PREFIX_MORE
- SD_HWDB_FOREACH_PROPERTY
- SD_JOURNAL_FOREACH
- SD_JOURNAL_FOREACH_BACKWARDS
- SD_JOURNAL_FOREACH_DATA
- SD_JOURNAL_FOREACH_FIELD
- SD_JOURNAL_FOREACH_UNIQUE
- SECCOMP_FOREACH_LOCAL_ARCH
- SET_FOREACH
- SET_FOREACH_MOVE
- STRV_FOREACH
- STRV_FOREACH_BACKWARDS
- STRV_FOREACH_PAIR
IndentPPDirectives: AfterHash
IndentWidth: 8
IndentWrappedFunctionNames: true
MaxEmptyLinesToKeep: 2
PenaltyBreakAssignment: 65
PenaltyBreakBeforeFirstCallParameter: 16
PenaltyBreakComment: 320
PenaltyBreakFirstLessLess: 50
PenaltyBreakString: 0
PenaltyExcessCharacter: 10
PenaltyReturnTypeOnItsOwnLine: 100
SpaceAfterCStyleCast: true
SpacesInAngles: true
TabWidth: 8
UseCRLF: false

4
.editorconfig
View File

@ -26,3 +26,7 @@ indent_size = 4
[meson.build]
indent_style = space
indent_size = 8
[man/*.xml]
indent_size = 2
indent_style = space

3
.github/ISSUE_TEMPLATE/Bug_report.md vendored
View File

@ -7,7 +7,8 @@ about: A report of an error in a recent systemd version
**systemd version the issue has been seen with**
> ...
<!-- **NOTE:** Do not submit bug reports about anything but the two most recently released systemd versions upstream! -->
<!-- **NOTE:** Do not submit bug reports about anything but the two most recently released (non-rc) systemd versions upstream! -->
<!-- See https://github.com/systemd/systemd/releases for the list of most recent releases. -->
<!-- For older version please use distribution trackers (see https://systemd.io/CONTRIBUTING#filing-issues). -->
**Used distribution**

28
.github/workflows/build_test.yml vendored Normal file
View File

@ -0,0 +1,28 @@
---
# vi: ts=2 sw=2 et:
#
name: Build test
on:
pull_request:
paths:
- '**/meson.build'
- '.github/workflows/**'
- 'meson_options.txt'
- 'src/**'
- 'test/fuzz/**'
jobs:
build:
runs-on: ubuntu-18.04
strategy:
fail-fast: false
matrix:
env:
- { COMPILER: "gcc", COMPILER_VERSION: "10" }
- { COMPILER: "clang", COMPILER_VERSION: "10" }
env: ${{ matrix.env }}
steps:
- name: Repository checkout
uses: actions/checkout@v1
- name: Build check (${{ env.COMPILER }}-${{ env.COMPILER_VERSION }})
run: sudo -E .github/workflows/ubuntu-build-check.sh

47
.github/workflows/cifuzz.yml vendored Normal file
View File

@ -0,0 +1,47 @@
---
# vi: ts=2 sw=2 et:
# See: https://google.github.io/oss-fuzz/getting-started/continuous-integration/
name: CIFuzz
on:
pull_request:
paths:
- '**/meson.build'
- '.github/workflows/**'
- 'meson_options.txt'
- 'src/**'
- 'test/fuzz/**'
- 'tools/oss-fuzz.sh'
push:
branches:
- master
jobs:
Fuzzing:
runs-on: ubuntu-latest
if: github.repository == 'systemd/systemd'
strategy:
fail-fast: false
matrix:
sanitizer: [address, undefined, memory]
steps:
- name: Build Fuzzers (${{ matrix.sanitizer }})
id: build
uses: google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master
with:
oss-fuzz-project-name: 'systemd'
dry-run: false
allowed-broken-targets-percentage: 0
sanitizer: ${{ matrix.sanitizer }}
- name: Run Fuzzers (${{ matrix.sanitizer }})
uses: google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@master
with:
oss-fuzz-project-name: 'systemd'
fuzz-seconds: 600
dry-run: false
sanitizer: ${{ matrix.sanitizer }}
- name: Upload Crash
uses: actions/upload-artifact@v1
if: failure() && steps.build.outcome == 'success'
with:
name: ${{ matrix.sanitizer }}-artifacts
path: ./out/artifacts

117
.github/workflows/ubuntu-build-check.sh vendored Executable file
View File

@ -0,0 +1,117 @@
#!/bin/bash
set -ex
info() { echo -e "\033[33;1m$1\033[0m"; }
fatal() { echo >&2 -e "\033[31;1m$1\033[0m"; exit 1; }
success() { echo >&2 -e "\033[32;1m$1\033[0m"; }
ARGS=(
"--optimization=0"
"--optimization=2"
"--optimization=s"
"--optimization=3 -Db_lto=true"
"--optimization=3 -Db_lto=false"
"-Db_ndebug=true"
)
PACKAGES=(
cryptsetup-bin
expect
fdisk
gettext
iptables-dev
iputils-ping
isc-dhcp-client
itstool
kbd
libblkid-dev
libcap-dev
libcurl4-gnutls-dev
libfdisk-dev
libgpg-error-dev
liblz4-dev
liblzma-dev
libmicrohttpd-dev
libmount-dev
libp11-kit-dev
libpwquality-dev
libqrencode-dev
libssl-dev
libxkbcommon-dev
libzstd-dev
mount
net-tools
perl
python-lxml
python3-evdev
python3-lxml
python3-pip
python3-pyparsing
python3-setuptools
quota
strace
unifont
util-linux
zstd
)
COMPILER="${COMPILER:?}"
COMPILER_VERSION="${COMPILER_VERSION:?}"
RELEASE="$(lsb_release -cs)"
bash -c "echo 'deb-src http://archive.ubuntu.com/ubuntu/ $RELEASE main restricted universe multiverse' >>/etc/apt/sources.list"
# Note: As we use postfixed clang/gcc binaries, we need to override $AR
# as well, otherwise meson falls back to ar from binutils which
# doesn't work with LTO
if [[ "$COMPILER" == clang ]]; then
CC="clang-$COMPILER_VERSION"
CXX="clang++-$COMPILER_VERSION"
AR="llvm-ar-$COMPILER_VERSION"
# Latest LLVM stack deb packages provided by https://apt.llvm.org/
# Following snippet was borrowed from https://apt.llvm.org/llvm.sh
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -
add-apt-repository -y "deb http://apt.llvm.org/$RELEASE/ llvm-toolchain-$RELEASE-$COMPILER_VERSION main"
PACKAGES+=(clang-$COMPILER_VERSION lldb-$COMPILER_VERSION lld-$COMPILER_VERSION clangd-$COMPILER_VERSION)
elif [[ "$COMPILER" == gcc ]]; then
CC="gcc-$COMPILER_VERSION"
CXX="g++-$COMPILER_VERSION"
AR="gcc-ar-$COMPILER_VERSION"
# Latest gcc stack deb packages provided by
# https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test
sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
PACKAGES+=(gcc-$COMPILER_VERSION)
else
fatal "Unknown compiler: $COMPILER"
fi
# PPA with some newer build dependencies (like zstd)
add-apt-repository -y ppa:upstream-systemd-ci/systemd-ci
apt-get -y update
apt-get -y build-dep systemd
apt-get -y install "${PACKAGES[@]}"
# Install the latest meson and ninja form pip, since the distro versions don't
# support all the features we need (like --optimization=). Since the build-dep
# command above installs the distro versions, let's install the pip ones just
# locally and add the local bin directory to the $PATH.
pip3 install --user -U meson ninja
export PATH="$HOME/.local/bin:$PATH"
$CC --version
for args in "${ARGS[@]}"; do
SECONDS=0
info "Checking build with $args"
if ! AR="$AR" CC="$CC" CXX="$CXX" CFLAGS="-Werror" CXXFLAGS="-Werror" meson -Dtests=unsafe -Dslow-tests=true --werror $args build; then
fatal "meson failed with $args"
fi
ninja --version
if ! ninja -C build; then
fatal "ninja failed with $args"
fi
git clean -dxf
success "Build with $args passed in $SECONDS seconds"
done

4
.gitignore vendored
View File

@ -12,6 +12,8 @@
.config.args
.gdb_history
.deps/
.mypy_cache/
__pycache__/
/*.gcda
/*.gcno
/*.tar.bz2
@ -33,5 +35,5 @@
/.mkosi-*
/mkosi.builddir/
/mkosi.output/
/mkosi.default
/tags
__pycache__/

3
.mailmap
View File

@ -118,6 +118,7 @@ Michael Olbrich <m.olbrich@pengutronix.de>
Michal Soltys <soltys@ziu.info> <nozo@ziu.info>
Michal Suchanek <msuchanek@suse.de>
Michal Suchanek <msuchanek@suse.de> <hramrach@gmail.com>
Michal Sekletár <msekleta@redhat.com>
Michał Szczepański <skrzatu@hotmail.com> <skrzatu@gmail.com>
Michel Kraus <github@demonsphere.de> <27o@users.noreply.github.com>
Miklos Vajna <vmiklos@frugalware.org> <vmiklos@gmail.com>
@ -206,3 +207,5 @@ Roger James <roger@beardandsandals.co.uk>
Stephan Edel <se@se-it.eu>
Andrey Yashkin <38919268+AndreyYashkin@users.noreply.github.com>
Ronald Tschalär <ronald@innovation.ch>
Jay Burger <jay.burger@fujitsu.com> <root@new-host-3.home>
Yi Gao <ymuemc@163.com>

3
.mkosi/mkosi.arch
View File

@ -3,7 +3,7 @@
# Copyright © 2016 Zeal Jagannatha
# This is a settings file for OS image generation using mkosi (https://github.com/systemd/mkosi).
# Simply invoke "mkosi" in the project directory to build an OS image.
# Symlink this file to mkosi.default in the project root directory and invoke "mkosi" to build an OS image.
[Distribution]
Distribution=arch
@ -52,6 +52,7 @@ BuildPackages=
python-lxml
qrencode
xz
zstd
Packages=
libidn2

4
.mkosi/mkosi.debian
View File

@ -1,7 +1,7 @@
# SPDX-License-Identifier: LGPL-2.1+
# This is a settings file for OS image generation using mkosi (https://github.com/systemd/mkosi).
# Simply invoke "mkosi" in the project directory to build an OS image.
# Symlink this file to mkosi.default in the project root directory and invoke "mkosi" to build an OS image.
[Distribution]
Distribution=debian
@ -50,6 +50,7 @@ BuildPackages=
libsmartcols-dev
libtool
libxkbcommon-dev
libzstd-dev
m4
meson
pkg-config
@ -59,6 +60,7 @@ BuildPackages=
uuid-dev
xsltproc
xz-utils
zstd
Packages=
libqrencode4

17
.mkosi/mkosi.fedora
View File

@ -1,11 +1,11 @@
# SPDX-License-Identifier: LGPL-2.1+
# This is a settings file for OS image generation using mkosi (https://github.com/systemd/mkosi).
# Simply invoke "mkosi" in the project directory to build an OS image.
# Symlink this file to mkosi.default in the project root directory and invoke "mkosi" to build an OS image.
[Distribution]
Distribution=fedora
Release=31
Release=32
[Output]
Format=gpt_ext4
@ -31,7 +31,6 @@ BuildPackages=
gnu-efi-devel
gnutls-devel
gperf
hostname
iptables-devel
kmod-devel
libacl-devel
@ -48,6 +47,7 @@ BuildPackages=
libselinux-devel
libxkbcommon-devel
libxslt
libzstd-devel
lz4
lz4-devel
m4
@ -63,16 +63,13 @@ BuildPackages=
tree
valgrind-devel
xz-devel
zstd
Packages=
coreutils
cryptsetup-libs
kmod-libs
e2fsprogs
libidn2
libseccomp
# libzstd can be dropped once the Fedora RPM gets a dependency on it
libzstd
# procps-ng provides a set of useful utilies (ps, free, etc)
procps-ng
util-linux
BuildDirectory=mkosi.builddir
Cache=mkosi.cache

78
.mkosi/mkosi.opensuse Normal file
View File

@ -0,0 +1,78 @@
# SPDX-License-Identifier: LGPL-2.1+
# This is a settings file for OS image generation using mkosi (https://github.com/systemd/mkosi).
# Symlink this file to mkosi.default in the project root directory and invoke "mkosi" to build an OS image.
[Distribution]
Distribution=opensuse
Release=tumbleweed
[Output]
Format=raw_btrfs
Bootable=yes
[Partitions]
RootSize=3G
[Packages]
# Uncomment to share system RPM cache (works only with Tumbleweed)
#Cache=/var/cache/zypp/packages
BuildDirectory=mkosi.builddir
BuildPackages=
docbook-xsl-stylesheets
fdupes
gcc
gnu-efi
gperf
intltool
libacl-devel
libapparmor-devel
libblkid-devel
libbz2-devel
libcap-devel
libcryptsetup-devel
libcurl-devel
libgcrypt-devel
libkmod-devel
liblz4-devel
libmicrohttpd-devel
libmount-devel
libseccomp-devel
libselinux-devel
libxslt-tools
m4
meson
pam-devel
pciutils-devel
pcre-devel
python3
python3-lxml
qrencode-devel
system-user-nobody
systemd-sysvinit
zlib-devel
# to satisfy tests
acl
diffutils
glibc-locale
system-group-obsolete
system-user-bin
system-user-daemon
system-user-root
timezone
Packages=
# brought in via meson->python3
libp11-kit0
# --bootable=no
dbus-1
libapparmor1
libcrypt1
libcryptsetup12
libkmod2
liblz4-1
libmount1
libqrencode4
libseccomp2
pam
util-linux

12
.mkosi/mkosi.ubuntu
View File

@ -1,11 +1,11 @@
# SPDX-License-Identifier: LGPL-2.1+
# This is a settings file for OS image generation using mkosi (https://github.com/systemd/mkosi).
# Simply invoke "mkosi" in the project directory to build an OS image.
# Symlink this file to mkosi.default in the project root directory and invoke "mkosi" to build an OS image.
[Distribution]
Distribution=ubuntu
Release=bionic
Release=focal
Repositories=main,universe
[Output]
@ -25,7 +25,6 @@ BuildPackages=
git
gnu-efi
gperf
iptables-dev
libacl1-dev
libaudit-dev
libblkid-dev
@ -39,6 +38,8 @@ BuildPackages=
libgcrypt20-dev
libgnutls28-dev
libidn2-0-dev
libip4tc-dev
libip6tc-dev
libkmod-dev
liblz4-dev
liblz4-tool
@ -51,6 +52,8 @@ BuildPackages=
libsmartcols-dev
libtool
libxkbcommon-dev
libxtables-dev
libzstd-dev
m4
meson
pkg-config
@ -61,8 +64,9 @@ BuildPackages=
uuid-dev
xsltproc
xz-utils
zstd
Packages=
libqrencode3
libqrencode4
locales
libidn2-0

222
.travis.yml
View File

@ -1,158 +1,84 @@
sudo: required
dist: xenial
---
# vi: ts=2 sw=2 et:
language: bash
dist: bionic
services:
- docker
- docker
env:
global:
- AUTHOR_EMAIL="$(git log -1 $TRAVIS_COMMIT --pretty=\"%aE\")"
- CI_MANAGERS="$TRAVIS_BUILD_DIR/travis-ci/managers"
- CI_TOOLS="$TRAVIS_BUILD_DIR/travis-ci/tools"
- REPO_ROOT="$TRAVIS_BUILD_DIR"
global:
- AUTHOR_EMAIL="$(git log -1 $TRAVIS_COMMIT --pretty=\"%aE\")"
- CI_MANAGERS="$TRAVIS_BUILD_DIR/travis-ci/managers"
- CI_TOOLS="$TRAVIS_BUILD_DIR/travis-ci/tools"
- REPO_ROOT="$TRAVIS_BUILD_DIR"
jobs:
- DEBIAN_RELEASE=testing PHASE="RUN_GCC"
- DEBIAN_RELEASE=testing PHASE="RUN_GCC_ASAN_UBSAN"
- DEBIAN_RELEASE=testing PHASE="RUN_CLANG"
- DEBIAN_RELEASE=testing PHASE="RUN_CLANG_ASAN_UBSAN"
stages:
- name: Build & test
if: type != cron
- name: Fuzzit-Fuzzing
if: type = cron
- name: Fuzzit-Regression
if: type != cron
# 'Test' is the default stage (for matrix jobs)
- name: Test
if: type != cron
# Run Coverity periodically instead of for each commit/PR
- name: Coverity
if: type = cron
- name: Coverity
if: type = cron
# Matrix job definition - this is run for each combination of env variables
# from the env.jobs array above
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
- $CI_MANAGERS/debian.sh SETUP
script:
- $CI_MANAGERS/debian.sh $PHASE || travis_terminate 1
after_script:
- $CI_MANAGERS/debian.sh CLEANUP
# Inject another (single) job into the matrix for Coverity
jobs:
include:
- stage: Build & test
name: Debian Testing
language: bash
env:
- DEBIAN_RELEASE="testing"
- CONT_NAME="systemd-debian-$DEBIAN_RELEASE"
- DOCKER_EXEC="docker exec -ti $CONT_NAME"
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
- $CI_MANAGERS/debian.sh SETUP
script:
- set -e
# Build systemd
- $CI_MANAGERS/debian.sh RUN
- set +e
after_script:
- $CI_MANAGERS/debian.sh CLEANUP
include:
- stage: Coverity
language: bash
env:
- FEDORA_RELEASE="31"
- TOOL_BASE="/var/tmp/coverity-scan-analysis"
- CONT_NAME="coverity-fedora-$FEDORA_RELEASE"
- DOCKER_EXEC="docker exec -ti $CONT_NAME"
- DOCKER_RUN="docker run -v $TOOL_BASE:$TOOL_BASE:rw --env-file .cov-env"
# Coverity env variables
- PLATFORM="$(uname)"
- TOOL_ARCHIVE="/var/tmp/cov-analysis-$PLATFORM.tgz"
- SCAN_URL="https://scan.coverity.com"
- UPLOAD_URL="https://scan.coverity.com/builds"
- COVERITY_SCAN_PROJECT_NAME="$TRAVIS_REPO_SLUG"
- COVERITY_SCAN_NOTIFICATION_EMAIL="${AUTHOR_EMAIL}"
- COVERITY_SCAN_BRANCH_PATTERN="$TRAVIS_BRANCH"
# Encrypted COVERITY_SCAN_TOKEN env variable
# Generated using `travis encrypt -r systemd/systemd COVERITY_SCAN_TOKEN=xxxx`
- secure: "jKSz+Y1Mv8xMpQHh7g5lzW7E6HQGndFz/vKDJQ1CVShwFoyjV3Zu+MFS3UYKlh1236zL0Z4dvsYFx/b3Hq8nxZWCrWeZs2NdXgy/wh8LZhxwzcGYigp3sIA/cYdP5rDjFJO0MasNkl25/rml8+eZWz+8/xQic98UQHjSco/EOWtssoRcg0J0c4eDM7bGLfIQWE73NNY1Q1UtWjKmx1kekVrM8dPmHXJ9aERka7bmcbJAcKd6vabs6DQ5AfWccUPIn/EsRYqIJTRxJrFYU6XizANZ1a7Vwk/DWHZUEn2msxcZw5BbAMDTMx0TbfrNkKSHMHuvQUCu6KCBAq414i+LgkMfmQ2SWwKiIUsud1kxXX3ZPl9bxDv1HkvVdcniC/EM7lNEEVwm4meOnjuhI2lhOyOjmP3FTSlMHGP7xlK8DS2k9fqL58vn0BaSjwWgd+2+HuL2+nJmxcK1eLGzKqaostFxrk2Xs2vPZkUdV2nWY/asUrcWHml6YlWDn2eP83pfwxHYsMiEHY/rTKvxeVY+iirO/AphoO+eaYu7LvjKZU1Yx5Z4u/SnGWAiCH0yhMis0bWmgi7SCbw+sDd2uya+aoiLIGiB2ChW7hXHXCue/dif6/gLU7b+L8R00pQwnWdvKUPoIJCmZJYCluTeib4jpW+EmARB2+nR8wms2K9FGKM="
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
# Install Coverity on the host
- $CI_TOOLS/get-coverity.sh
# Export necessary env variables for Coverity
- env | grep -E "TRAVIS|COV|TOOL|URL" > .cov-env
# Pull a Docker image and start a new container
- $CI_MANAGERS/fedora.sh SETUP
script:
- set -e
# Preconfigure with meson to prevent Coverity from capturing meson metadata
- $DOCKER_EXEC meson cov-build -Dman=false
# Run Coverity
- $DOCKER_EXEC tools/coverity.sh build
- $DOCKER_EXEC tools/coverity.sh upload
- name: Debian Testing (ASan+UBSan)
language: bash
env:
- DEBIAN_RELEASE="testing"
- CONT_NAME="systemd-debian-$DEBIAN_RELEASE"
- DOCKER_EXEC="docker exec -ti $CONT_NAME"
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
- $CI_MANAGERS/debian.sh SETUP
script:
- set -e
- $CI_MANAGERS/debian.sh RUN_ASAN
- set +e
after_script:
- $CI_MANAGERS/debian.sh CLEANUP
- name: Debian Testing (clang)
language: bash
env:
- DEBIAN_RELEASE="testing"
- CONT_NAME="systemd-debian-$DEBIAN_RELEASE"
- DOCKER_EXEC="docker exec -ti $CONT_NAME"
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
- $CI_MANAGERS/debian.sh SETUP
script:
- set -e
- $CI_MANAGERS/debian.sh RUN_CLANG
- set +e
after_script:
- $CI_MANAGERS/debian.sh CLEANUP
- name: Debian Testing (clang ASan+UBSan)
language: bash
env:
- DEBIAN_RELEASE="testing"
- CONT_NAME="systemd-debian-$DEBIAN_RELEASE"
- DOCKER_EXEC="docker exec -ti $CONT_NAME"
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
- $CI_MANAGERS/debian.sh SETUP
script:
- set -e
- $CI_MANAGERS/debian.sh RUN_CLANG_ASAN
- set +e
after_script:
- $CI_MANAGERS/debian.sh CLEANUP
- stage: Fuzzit-Regression
name: Continuous Fuzzing via Fuzzit (regression)
language: bash
script:
- set -e
- $CI_MANAGERS/fuzzit.sh regression
- set +e
- stage: Fuzzit-Fuzzing
name: Continuous Fuzzing via Fuzzit (fuzzing daily)
language: bash
script:
- set -e
- $CI_MANAGERS/fuzzit.sh fuzzing
- set +e
- stage: Coverity
language: bash
env:
- FEDORA_RELEASE="latest"
- CONT_NAME="coverity-fedora-$FEDORA_RELEASE"
- DOCKER_EXEC="docker exec -ti $CONT_NAME"
- TOOL_BASE="/var/tmp/coverity-scan-analysis"
- DOCKER_RUN="docker run -v $TOOL_BASE:$TOOL_BASE:rw --env-file .cov-env"
# Coverity env variables
- PLATFORM="$(uname)"
- TOOL_ARCHIVE="/var/tmp/cov-analysis-$PLATFORM.tgz"
- SCAN_URL="https://scan.coverity.com"
- UPLOAD_URL="https://scan.coverity.com/builds"
- COVERITY_SCAN_PROJECT_NAME="$TRAVIS_REPO_SLUG"
- COVERITY_SCAN_NOTIFICATION_EMAIL="${AUTHOR_EMAIL}"
- COVERITY_SCAN_BRANCH_PATTERN="$TRAVIS_BRANCH"
# Encrypted COVERITY_SCAN_TOKEN env variable
# Generated using `travis encrypt -r systemd/systemd COVERITY_SCAN_TOKEN=xxxx`
- secure: "jKSz+Y1Mv8xMpQHh7g5lzW7E6HQGndFz/vKDJQ1CVShwFoyjV3Zu+MFS3UYKlh1236zL0Z4dvsYFx/b3Hq8nxZWCrWeZs2NdXgy/wh8LZhxwzcGYigp3sIA/cYdP5rDjFJO0MasNkl25/rml8+eZWz+8/xQic98UQHjSco/EOWtssoRcg0J0c4eDM7bGLfIQWE73NNY1Q1UtWjKmx1kekVrM8dPmHXJ9aERka7bmcbJAcKd6vabs6DQ5AfWccUPIn/EsRYqIJTRxJrFYU6XizANZ1a7Vwk/DWHZUEn2msxcZw5BbAMDTMx0TbfrNkKSHMHuvQUCu6KCBAq414i+LgkMfmQ2SWwKiIUsud1kxXX3ZPl9bxDv1HkvVdcniC/EM7lNEEVwm4meOnjuhI2lhOyOjmP3FTSlMHGP7xlK8DS2k9fqL58vn0BaSjwWgd+2+HuL2+nJmxcK1eLGzKqaostFxrk2Xs2vPZkUdV2nWY/asUrcWHml6YlWDn2eP83pfwxHYsMiEHY/rTKvxeVY+iirO/AphoO+eaYu7LvjKZU1Yx5Z4u/SnGWAiCH0yhMis0bWmgi7SCbw+sDd2uya+aoiLIGiB2ChW7hXHXCue/dif6/gLU7b+L8R00pQwnWdvKUPoIJCmZJYCluTeib4jpW+EmARB2+nR8wms2K9FGKM="
before_install:
- sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-ce
- docker --version
install:
# Install Coverity on the host
- $CI_TOOLS/get-coverity.sh
# Export necessary env variables for Coverity
- env | grep -E "TRAVIS|COV|TOOL|URL" > .cov-env
# Pull a Docker image and start a new container
- $CI_MANAGERS/fedora.sh SETUP
script:
- set -e
# Preconfigure with meson to prevent Coverity from capturing meson metadata
- $DOCKER_EXEC meson cov-build -Dman=false
# Run Coverity
- $DOCKER_EXEC tools/coverity.sh build
- $DOCKER_EXEC tools/coverity.sh upload
- set +e
after_script:
- $CI_MANAGERS/fedora.sh CLEANUP
- set +e
after_script:
- $CI_MANAGERS/fedora.sh CLEANUP

683
NEWS
View File

@ -1,5 +1,609 @@
systemd System and Service Manager
CHANGES WITH 246:
* The service manager gained basic support for cgroup v2 freezer. Units
can now be suspended or resumed either using new systemctl verbs,
freeze and thaw respectively, or via D-Bus.
* PID 1 may now automatically load pre-compiled AppArmor policies from
/etc/apparmor/earlypolicy during early boot.
* The CPUAffinity= setting in service unit files now supports a new
special value "numa" that causes the CPU affinity masked to be set
based on the NUMA mask.
* systemd will now log about all left-over processes remaining in a
unit when the unit is stopped. It will now warn about services using
KillMode=none, as this is generally an unsafe thing to make use of.
* Two new unit file settings
ConditionPathIsEncrypted=/AssertPathIsEncrypted= have been
added. They may be used to check whether a specific file system path
resides on a block device that is encrypted on the block level
(i.e. using dm-crypt/LUKS).
* Another pair of new settings ConditionEnvironment=/AssertEnvironment=
has been added that may be used for simple environment checks. This
is particularly useful when passing in environment variables from a
container manager (or from PAM in case of the systemd --user
instance).
* .service unit files now accept a new setting CoredumpFilter= which
allows configuration of the memory sections coredumps of the
service's processes shall include.
* .mount units gained a new ReadWriteOnly= boolean option. If set
it will not be attempted to mount a file system read-only if mounting
in read-write mode doesn't succeed. An option x-systemd.rw-only is
available in /etc/fstab to control the same.
* .socket units gained a new boolean setting PassPacketInfo=. If
enabled, the kernel will attach additional per-packet metadata to all
packets read from the socket, as an ancillary message. This controls
the IP_PKTINFO, IPV6_RECVPKTINFO, NETLINK_PKTINFO socket options,
depending on socket type.
* .service units gained a new setting RootHash= which may be used to
specify the root hash for verity enabled disk images which are
specified in RootImage=. RootVerity= may be used to specify a path to
the Verity data matching a RootImage= file system. (The latter is
only useful for images that do not contain the Verity data embedded
into the same image that carries a GPT partition table following the
Discoverable Partition Specification). Similarly, systemd-nspawn
gained a new switch --verity-data= that takes a path to a file with
the verity data of the disk image supplied in --image=, if the image
doesn't contain the verity data itself.
* .service units gained a new setting RootHashSignature= which takes
either a base64 encoded PKCS#7 signature of the root hash specified
with RootHash=, or a path to a file to read the signature from. This
allows validation of the root hash against public keys available in
the kernel keyring, and is only supported on recent kernels
(>= 5.4)/libcryptsetup (>= 2.30). A similar switch has been added to
systemd-nspawn and systemd-dissect (--root-hash-sig=). Support for
this mechanism has also been added to systemd-veritysetup.
* .service unit files gained two new options
TimeoutStartFailureMode=/TimeoutStopFailureMode= that may be used to
tune behaviour if a start or stop timeout is hit, i.e. whether to
terminate the service with SIGTERM, SIGABRT or SIGKILL.
* Most options in systemd that accept hexadecimal values prefixed with
0x in additional to the usual decimal notation now also support octal
notation when the 0o prefix is used and binary notation if the 0b
prefix is used.
* Various command line parameters and configuration file settings that
configure key or certificate files now optionally take paths to
AF_UNIX sockets in the file system. If configured that way a stream
connection is made to the socket and the required data read from
it. This is a simple and natural extension to the existing regular
file logic, and permits other software to provide keys or
certificates via simple IPC services, for example when unencrypted
storage on disk is not desired. Specifically, systemd-networkd's
Wireguard and MACSEC key file settings as well as
systemd-journal-gatewayd's and systemd-journal-remote's PEM
key/certificate parameters support this now.
* Unit files, tmpfiles.d/ snippets, sysusers.d/ snippets and other
configuration files that support specifier expansion learnt six new
specifiers: %a resolves to the current architecture, %o/%w/%B/%W
resolve to the various ID fields from /etc/os-release, %l resolves to
the "short" hostname of the system, i.e. the hostname configured in
the kernel truncated at the first dot.
* Support for the .include syntax in unit files has been removed. The
concept has been obsolete for 6 years and we started warning about
its pending removal 2 years ago (also see NEWS file below). It's
finally gone now.
* StandardError= and StandardOutput= in unit files no longer support
the "syslog" and "syslog-console" switches. They were long removed
from the documentation, but will now result in warnings when used,
and be converted to "journal" and "journal+console" automatically.
* If the service setting User= is set to the "nobody" user, a warning
message is now written to the logs (but the value is nonetheless
accepted). Setting User=nobody is unsafe, since the primary purpose
of the "nobody" user is to own all files whose owner cannot be mapped
locally. It's in particular used by the NFS subsystem and in user
namespacing. By running a service under this user's UID it might get
read and even write access to all these otherwise unmappable files,
which is quite likely a major security problem.
* tmpfs mounts automatically created by systemd (/tmp, /run, /dev/shm,
and others) now have a size and inode limits applied (50% of RAM for
/tmp and /dev/shm, 10% of RAM for other mounts, etc.)
* nss-mymachines lost support for resolution of users and groups, and
now only does resolution of hostnames. This functionality is now
provided by nss-systemd. Thus, the 'mymachines' entry should be
removed from the 'passwd:' and 'group:' lines in /etc/nsswitch.conf
(and 'systemd' added if it is not already there).
* A new kernel command line option systemd.hostname= has been added
that allows controlling the hostname that is initialized early during
boot.
* A kernel command line option "udev.blockdev_read_only" has been
added. If specified all hardware block devices that show up are
immediately marked as read-only by udev. This option is useful for
making sure that a specific boot under no circumstances modifies data
on disk. Use "blockdev --setrw" to undo the effect of this, per
device.
* A new boolean kernel command line option systemd.swap= has been
added, which may be used to turn off automatic activation of swap
devices listed in /etc/fstab.
* New kernel command line options systemd.condition-needs-update= and
systemd.condition-first-boot= have been added, which override the
result of the ConditionNeedsUpdate= and ConditionFirstBoot=
conditions.
* A new kernel command line option systemd.clock-usec= has been added
that allows setting the system clock to the specified time in µs
since Jan 1st, 1970 early during boot. This is in particular useful
in order to make test cases more reliable.
* The fs.suid_dumpable sysctl is set to 2 / "suidsafe". This allows
systemd-coredump to save core files for suid processes. When saving
the core file, systemd-coredump will use the effective uid and gid of
the process that faulted.
* The /sys/module/kernel/parameters/crash_kexec_post_notifiers file is
now automatically set to "Y" at boot, in order to enable pstore
generation for collection with systemd-pstore.
* A new 'hwdb' file has been added that collects information about PCI
and USB devices that correctly support auto-suspend, on top of the
databases for this we import from the ChromiumOS project. If you have
a device that supports auto-suspend correctly and where it should be
enabled by default, please submit a patch that adds it to the
database (see /usr/lib/udev/hwdb.d/60-autosuspend.hwdb).
* systemd-udevd gained the new configuration option timeout_signal= as well
as a corresponding kernel command line option udev.timeout_signal=.
The option can be used to configure the UNIX signal that the main
daemon sends to the worker processes on timeout. Setting the signal
to SIGABRT is useful for debugging.
* .link files managed by systemd-udevd gained options RxFlowControl=,
TxFlowControl=, AutoNegotiationFlowControl= in the [Link] section, in
order to configure various flow control parameters. They also gained
RxMiniBufferSize= and RxJumboBufferSize= in order to configure jumbo
frame ring buffer sizes.
* networkd.conf gained a new boolean setting ManageForeignRoutes=. If
enabled systemd-networkd manages all routes configured by other tools.
* .network files managed by systemd-networkd gained a new section
[SR-IOV], in order to configure SR-IOV capable network devices.
* systemd-networkd's [IPv6Prefix] section in .network files gained a
new boolean setting Assign=. If enabled an address from the prefix is
automatically assigned to the interface.
* systemd-networkd gained a new section [DHCPv6PrefixDelegation] which
controls delegated prefixes assigned by DHCPv6 client. The section
has three settings: SubnetID=, Assign=, and Token=. The setting
SubnetID= allows explicit configuration of the preferred subnet that
systemd-networkd's Prefix Delegation logic assigns to interfaces. If
Assign= is enabled (which is the default) an address from any acquired
delegated prefix is automatically chosen and assigned to the
interface. The setting Token= specifies an optional address generation
mode for Assign=.
* systemd-networkd's [Network] section gained a new setting
IPv4AcceptLocal=. If enabled the interface accepts packets with local
source addresses.
* systemd-networkd gained support for configuring the HTB queuing
discipline in the [HierarchyTokenBucket] and
[HierarchyTokenBucketClass] sections. Similar the "pfifo" qdisc may
be configured in the [PFIFO] section, "GRED" in
[GenericRandomEarlyDetection], "SFB" in [StochasticFairBlue], "cake"
in [CAKE], "PIE" in [PIE], "DRR" in [DeficitRoundRobinScheduler] and
[DeficitRoundRobinSchedulerClass], "BFIFO" in [BFIFO],
"PFIFOHeadDrop" in [PFIFOHeadDrop], "PFIFOFast" in [PFIFOFast], "HHF"
in [HeavyHitterFilter], "ETS" in [EnhancedTransmissionSelection] and
"QFQ" in [QuickFairQueueing] and [QuickFairQueueingClass].
* systemd-networkd gained support for a new Termination= setting in the
[CAN] section for configuring the termination resistor. It also
gained a new ListenOnly= setting for controlling whether to only
listen on CAN interfaces, without interfering with traffic otherwise
(which is useful for debugging/monitoring CAN network
traffic). DataBitRate=, DataSamplePoint=, FDMode=, FDNonISO= have
been added to configure various CAN-FD aspects.
* systemd-networkd's [DHCPv6] section gained a new option WithoutRA=.
When enabled, DHCPv6 will be attempted right-away without requiring an
Router Advertisement packet suggesting it first (i.e. without the 'M'
or 'O' flags set). The [IPv6AcceptRA] section gained a boolean option
DHCPv6Client= that may be used to turn off the DHCPv6 client even if
the RA packets suggest it.
* systemd-networkd's [DHCPv4] section gained a new setting UseGateway=
which may be used to turn off use of the gateway information provided
by the DHCP lease. A new FallbackLeaseLifetimeSec= setting may be
used to configure how to process leases that lack a lifetime option.
* systemd-networkd's [DHCPv4] and [DHCPServer] sections gained a new
setting SendVendorOption= allowing configuration of additional vendor
options to send in the DHCP requests/responses. The [DHCPv6] section
gained a new SendOption= setting for sending arbitrary DHCP
options. RequestOptions= has been added to request arbitrary options
from the server. UserClass= has been added to set the DHCP user class
field.
* systemd-networkd's [DHCPServer] section gained a new set of options
EmitPOP3=/POP3=, EmitSMTP=/SMTP=, EmitLPR=/LPR= for including server
information about these three protocols in the DHCP lease. It also
gained support for including "MUD" URLs ("Manufacturer Usage
Description"). Support for "MUD" URLs was also added to the LLDP
stack, configurable in the [LLDP] section in .network files.
* The Mode= settings in [MACVLAN] and [MACVTAP] now support 'source'
mode. Also, the sections now support a new setting SourceMACAddress=.
* systemd-networkd's .netdev files now support a new setting
VLANProtocol= in the [Bridge] section that allows configuration of
the VLAN protocol to use.
* systemd-networkd supports a new Group= setting in the [Link] section
of the .network files, to control the link group.
* systemd-networkd's [Network] section gained a new
IPv6LinkLocalAddressGenerationMode= setting, which specifies how IPv6
link local address is generated.
* A new default .network file is now shipped that matches TUN/TAP
devices that begin with "vt-" in their name. Such interfaces will
have IP routing onto the host links set up automatically. This is
supposed to be used by VM managers to trivially acquire a network
interface which is fully set up for host communication, simply by
carefully picking an interface name to use.
* systemd-networkd's [DHCPv6] section gained a new setting RouteMetric=
which sets the route priority for routes specified by the DHCP server.
* systemd-networkd's [DHCPv6] section gained a new setting VendorClass=
which configures the vendor class information sent to DHCP server.
* The BlackList= settings in .network files' [DHCPv4] and
[IPv6AcceptRA] sections have been renamed DenyList=. The old names
are still understood to provide compatibility.
* networkctl gained the new "forcerenew" command for forcing all DHCP
server clients to renew their lease. The interface "status" output
will now show numerous additional fields of information about an
interface. There are new "up" and "down" commands to bring specific
interfaces up or down.
* systemd-resolved's DNS= configuration option now optionally accepts a
port number (after ":") and a host name (after "#"). When the host
name is specified, the DNS-over-TLS certificate is validated to match
the specified hostname. Additionally, in case of IPv6 addresses, an
interface may be specified (after "%").
* systemd-resolved may be configured to forward single-label DNS names.
This is not standard-conformant, but may make sense in setups where
public DNS servers are not used.
* systemd-resolved's DNS-over-TLS support gained SNI validation.
* systemd-nspawn's --resolv-conf= switch gained a number of new
supported values. Specifically, options starting with "replace-" are
like those prefixed "copy-" but replace any existing resolv.conf
file. And options ending in "-uplink" and "-stub" can now be used to
propagate other flavours of resolv.conf into the container (as
defined by systemd-resolved).
* The various programs included in systemd can now optionally output
their log messages on stderr prefixed with a timestamp, controlled by
the $SYSTEMD_LOG_TIME environment variable.
* systemctl gained a new "-P" switch that is a shortcut for "--value
--property=…".
* "systemctl list-units" and "systemctl list-machines" no longer hide
their first output column with --no-legend. To hide the first column,
use --plain.
* "systemctl reboot" takes the option "--reboot-argument=".
The optional positional argument to "systemctl reboot" is now
being deprecated in favor of this option.
* systemd-run gained a new switch --slice-inherit. If specified the
unit it generates is placed in the same slice as the systemd-run
process itself.
* systemd-journald gained support for zstd compression of large fields
in journal files. The hash tables in journal files have been hardened
against hash collisions. This is an incompatible change and means
that journal files created with new systemd versions are not readable
with old versions. If the $SYSTEMD_JOURNAL_KEYED_HASH boolean
environment variable for systemd-journald.service is set to 0 this
new hardening functionality may be turned off, so that generated
journal files remain compatible with older journalctl
implementations.
* journalctl will now include a clickable link in the default output for
each log message for which an URL with further documentation is
known. This is only supported on terminal emulators that support
clickable hyperlinks, and is turned off if a pager is used (since
"less" still doesn't support hyperlinks,
unfortunately). Documentation URLs may be included in log messages
either by including a DOCUMENTATION= journal field in it, or by
associating a journal message catalog entry with the log message's
MESSAGE_ID, which then carries a "Documentation:" tag.
* journald.conf gained a new boolean setting Audit= that may be used to
control whether systemd-journald will enable audit during
initialization.
* when systemd-journald's log stream is broken up into multiple lines
because the PID of the sender changed this is indicated in the
generated log records via the _LINE_BREAK=pid-change field.
* journalctl's "-o cat" output mode will now show one or more journal
fields specified with --output-fields= instead of unconditionally
MESSAGE=. This is useful to retrieve a very specific set of fields
without any decoration.
* The sd-journal.h API gained two new functions:
sd_journal_enumerate_available_unique() and
sd_journal_enumerate_available_data() that operate like their
counterparts that lack the _available_ in the name, but skip items
that cannot be read and processed by the local implementation
(i.e. are compressed in an unsupported format or such),
* coredumpctl gained a new --file= switch, matching the same one in
journalctl: a specific journal file may be specified to read the
coredump data from.
* coredumps collected by systemd-coredump may now be compressed using
the zstd algorithm.
* systemd-binfmt gained a new switch --unregister for unregistering all
registered entries at once. This is now invoked automatically at
shutdown, so that binary formats registered with the "F" flag will
not block clean file system unmounting.
* systemd-notify's --pid= switch gained new values: "parent", "self",
"auto" for controlling which PID to send to the service manager: the
systemd-notify process' PID, or the one of the process invoking it.
* systemd-logind's Session bus object learnt a new method call
SetType() for temporarily updating the session type of an already
allocated session. This is useful for upgrading tty sessions to
graphical ones once a compositor is invoked.
* systemd-socket-proxy gained a new switch --exit-idle-time= for
configuring an exit-on-idle time.
* systemd-repart's --empty= setting gained a new value "create". If
specified a new empty regular disk image file is created under the
specified name. Its size may be specified with the new --size=
option. The latter is also supported without the "create" mode, in
order to grow existing disk image files to the specified size. These
two new options are useful when creating or manipulating disk images
instead of operating on actual block devices.
* systemd-repart drop-ins now support a new UUID= setting to control
the UUID to assign to a newly created partition.
* systemd-repart's SizeMin= per-partition parameter now defaults to 10M
instead of 0.
* systemd-repart's Label= setting now support the usual, simple
specifier expansion.
* systemd-homed's LUKS backend gained the ability to discard empty file
system blocks automatically when the user logs out. This is enabled
by default to ensure that home directories take minimal space when
logged out but get full size guarantees when logged in. This may be
controlled with the new --luks-offline-discard= switch to homectl.
* If systemd-homed detects that /home/ is encrypted as a whole it will
now default to the directory or subvolume backends instead of the
LUKS backend, in order to avoid double encryption. The default
storage and file system may now be configured explicitly, too, via
the new /etc/systemd/homed.conf configuration file.
* systemd-homed now supports unlocking home directories with FIDO2
security tokens that support the 'hmac-secret' extension, in addition
to the existing support for PKCS#11 security token unlocking
support. Note that many recent hardware security tokens support both
interfaces. The FIDO2 support is accessible via homectl's
--fido2-device= option.
* homectl's --pkcs11-uri= setting now accepts two special parameters:
if "auto" is specified and only one suitable PKCS#11 security token
is plugged in, its URL is automatically determined and enrolled for
unlocking the home directory. If "list" is specified a brief table of
suitable PKCS#11 security tokens is shown. Similar, the new
--fido2-device= option also supports these two special values, for
automatically selecting and listing suitable FIDO2 devices.
* The /etc/crypttab tmp option now optionally takes an argument
selecting the file system to use. Moreover, the default is now
changed from ext2 to ext4.
* There's a new /etc/crypttab option "keyfile-erase". If specified the
key file listed in the same line is removed after use, regardless if
volume activation was successful or not. This is useful if the key
file is only acquired transiently at runtime and shall be erased
before the system continues to boot.
* There's also a new /etc/crypttab option "try-empty-password". If
specified, before asking the user for a password it is attempted to
unlock the volume with an empty password. This is useful for
installing encrypted images whose password shall be set on first boot
instead of at installation time.
* systemd-cryptsetup will now attempt to load the keys to unlock
volumes with automatically from files in
/etc/cryptsetup-keys.d/<volume>.key and
/run/cryptsetup-keys.d/<volume>.key, if any of these files exist.
* systemd-cryptsetup may now activate Microsoft BitLocker volumes via
/etc/crypttab, during boot.
* logind.conf gained a new RuntimeDirectoryInodesMax= setting to
control the inode limit for the per-user $XDG_RUNTIME_DIR tmpfs
instance.
* A new generator systemd-xdg-autostart-generator has been added. It
generates systemd unit files from XDG autostart .desktop files, and
may be used to let the systemd user instance manage services that are
started automatically as part of the desktop session.
* "bootctl" gained a new verb "reboot-to-firmware" that may be used
to query and change the firmware's 'reboot into firmware' setup flag.
* systemd-firstboot gained a new switch --kernel-command-line= that may
be used to initialize the /etc/kernel/cmdline file of the image. It
also gained a new switch --root-password-hashed= which is like
--root-password= but accepts a pre-hashed UNIX password as
argument. The new option --delete-root-password may be used to unset
any password for the root user (dangerous!). The --root-shell= switch
may be used to control the shell to use for the root account. A new
--force option may be used to override any already set settings with
the parameters specified on the command line (by default, the tool
will not override what has already been set before, i.e. is purely
incremental).
* systemd-firstboot gained support for a new --image= switch, which is
similar to --root= but accepts the path to a disk image file, on
which it then operates.
* A new sd-path.h API has been added to libsystemd. It provides a
simple API for retrieving various search paths and primary
directories for various resources.
* A new call sd_notify_barrier() has been added to the sd-daemon.h
API. The call will block until all previously sent sd_notify()
messages have been processed by the service manager. This is useful
to remove races caused by a process already having disappeared at the
time a notification message is processed by the service manager,
making correct attribution impossible. The systemd-notify tool will
now make use of this call implicitly, but this can be turned off again
via the new --no-block switch.
* When sending a file descriptor (fd) to the service manager to keep
track of, using the sd_notify() mechanism, a new parameter FDPOLL=0
may be specified. If passed the service manager will refrain from
poll()ing on the file descriptor. Traditionally (and when the
parameter is not specified), the service manager will poll it for
POLLHUP or POLLERR events, and immediately close the fds in that
case.
* The service manager (PID1) gained a new D-Bus method call
SetShowStatus() which may be used to control whether it shall show
boot-time status output on the console. This method has a similar
effect to sending SIGRTMIN+20/SIGRTMIN+21 to PID 1.
* The sd-bus API gained a number of convenience functions that take
va_list arguments rather than "...". For example, there's now
sd_bus_call_methodv() to match sd_bus_call_method(). Those calls make
it easier to build wrappers that accept variadic arguments and want
to pass a ready va_list structure to sd-bus.
* sd-bus vtable entries can have a new SD_BUS_VTABLE_ABSOLUTE_OFFSET
flag which alters how the userdata pointer to pass to the callbacks
is determined. When the flag is set, the offset field is converted
as-is into a pointer, without adding it to the object pointer the
vtable is associated with.
* sd-bus now exposes four new functions:
sd_bus_interface_name_is_valid() + sd_bus_service_name_is_valid() +
sd_bus_member_name_is_valid() + sd_bus_object_path_is_valid() will
validate strings to check if they qualify as various D-Bus concepts.
* The sd-bus API gained the SD_BUS_METHOD_WITH_ARGS(),
SD_BUS_METHOD_WITH_ARGS_OFFSET() and SD_BUS_SIGNAL_WITH_ARGS() macros
that simplify adding argument names to D-Bus methods and signals.
* The man pages for the sd-bus and sd-hwdb APIs have been completed.
* Various D-Bus APIs of systemd daemons now have man pages that
document the methods, signals and properties.
* The expectations on user/group name syntax are now documented in
detail; documentation on how classic home directories may be
converted into home directories managed by homed has been added;
documentation regarding integration of homed/userdb functionality in
desktops has been added:
https://systemd.io/USER_NAMES
https://systemd.io/CONVERTING_TO_HOMED
https://systemd.io/USERDB_AND_DESKTOPS
* Documentation for the on-disk Journal file format has been updated
and has now moved to:
https://systemd.io/JOURNAL_FILE_FORMAT
* The interface for containers (https://systemd.io/CONTAINER_INTERFACE)
has been extended by a set of environment variables that expose
select fields from the host's os-release file to the container
payload. Similarly, host's os-release files can be mounted into the
container underneath /run/host. Together, those mechanisms provide a
standardized way to expose information about the host to the
container payload. Both interfaces are implemented in systemd-nspawn.
* All D-Bus services shipped in systemd now implement the generic
LogControl1 D-Bus API which allows clients to change log level +
target of the service during runtime.
* Only relevant for developers: the mkosi.default symlink has been
dropped from version control. Please create a symlink to one of the
distribution-specific defaults in .mkosi/ based on your preference.
Contributions from: 24bisquitz, Adam Nielsen, Alan Perry, Alexander
Malafeev, Amitanand.Chikorde, Alin Popa, Alvin Šipraga, Amos Bird,
Andreas Rammhold, AndreRH, Andrew Doran, Anita Zhang, Ankit Jain,
antznin, Arnaud Ferraris, Arthur Moraes do Lago, Arusekk, Balaji
Punnuru, Balint Reczey, Bastien Nocera, bemarek, Benjamin Berg,
Benjamin Dahlhoff, Benjamin Robin, Chris Down, Chris Kerr, Christian
Göttsche, Christian Hesse, Christian Oder, Ciprian Hacman, Clinton Roy,
codicodi, Corey Hinshaw, Daan De Meyer, Dana Olson, Dan Callaghan,
Daniel Fullmer, Daniel Rusek, Dan Streetman, Dave Reisner, David
Edmundson, David Wood, Denis Pronin, Diego Escalante Urrelo, Dimitri
John Ledkov, dolphrundgren, duguxy, Einsler Lee, Elisei Roca, Emmanuel
Garette, Eric Anderson, Eric DeVolder, Evgeny Vereshchagin,
ExtinctFire, fangxiuning, Ferran Pallarès Roca, Filipe Brandenburger,
Filippo Falezza, Finn, Florian Klink, Florian Mayer, Franck Bui,
Frantisek Sumsal, gaurav, Georg Müller, Gergely Polonkai, Giedrius
Statkevičius, Gigadoc2, gogogogi, Gaurav Singh, gzjsgdsb, Hans de
Goede, Haochen Tong, ianhi, ignapk, Jakov Smolic, James T. Lee, Jan
Janssen, Jan Klötzke, Jan Palus, Jay Burger, Jeremy Cline, Jérémy
Rosen, Jian-Hong Pan, Jiri Slaby, Joel Shapiro, Joerg Behrmann, Jörg
Thalheim, Jouke Witteveen, Kai-Heng Feng, Kenny Levinsen, Kevin
Kuehler, Kumar Kartikeya Dwivedi, layderv, laydervus, Lénaïc Huard,
Lennart Poettering, Lidong Zhong, Luca Boccassi, Luca BRUNO, Lucas
Werkmeister, Lukas Klingsbo, Lukáš Nykrýn, Łukasz Stelmach, Maciej
S. Szmigiero, MadMcCrow, Marc-André Lureau, Marcel Holtmann, Marc
Kleine-Budde, Martin Hundebøll, Matthew Leeds, Matt Ranostay, Maxim
Fomin, MaxVerevkin, Michael Biebl, Michael Chapman, Michael Gubbels,
Michael Marley, Michał Bartoszkiewicz, Michal Koutný, Michal Sekletár,
Mike Gilbert, Mike Kazantsev, Mikhail Novosyolov, ml, Motiejus Jakštys,
nabijaczleweli, nerdopolis, Niccolò Maggioni, Niklas Hambüchen, Norbert
Lange, Paul Cercueil, pelzvieh, Peter Hutterer, Piero La Terza, Pieter
Lexis, Piotr Drąg, Rafael Fontenelle, Richard Petri, Ronan Pigott, Ross
Lagerwall, Rubens Figueiredo, satmandu, Sean-StarLabs, Sebastian
Jennen, sterlinghughes, Surhud More, Susant Sahani, szb512, Thomas
Haller, Tobias Hunger, Tom, Tomáš Pospíšek, Tomer Shechner, Tom Hughes,
Topi Miettinen, Tudor Roman, Uwe Kleine-König, Valery0xff, Vito Caputo,
Vladimir Panteleev, Vladyslav Tronko, Wen Yang, Yegor Vialov, Yigal
Korman, Yi Gao, YmrDtnJu, Yuri Chornoivan, Yu Watanabe, Zbigniew
Jędrzejewski-Szmek, Zhu Li, Дамјан Георгиевски, наб
– Warsaw, 2020-07-30
CHANGES WITH 245:
* A new tool "systemd-repart" has been added, that operates as an
@ -171,8 +775,6 @@ CHANGES WITH 245:
* systemd-sysusers gained support for creating users with the primary
group named differently than the user.
* systemd-resolved's DNS-over-TLS support gained SNI validation.
* systemd-growfs (i.e. the x-systemd.growfs mount option in /etc/fstab)
gained support for growing XFS partitions. Previously it supported
only ext4 and btrfs partitions.
@ -270,7 +872,7 @@ CHANGES WITH 245:
such files in version 243.
* systemd-logind will now validate access to the operation of changing
the virtual terminal via a PolicyKit action. By default, only users
the virtual terminal via a polkit action. By default, only users
with at least one session on a local VT are granted permission.
* When systemd sets up PAM sessions that invoked service processes
@ -373,7 +975,7 @@ CHANGES WITH 244:
of the PAM session, for example for time-limited logins.
* A new @pkey system call group is now defined to make it easier to
whitelist memory protection syscalls for containers and services
allow-list memory protection syscalls for containers and services
which need to use them.
* systemd-udevd: removed the 30s timeout for killing stale workers on
@ -390,10 +992,10 @@ CHANGES WITH 244:
* udev now provides a program (fido_id) that identifies FIDO CTAP1
("U2F")/CTAP2 security tokens based on the usage declared in their
report and descriptor and outputs suitable environment variables.
This replaces the externally maintained whitelists of all known
This replaces the externally maintained allow lists of all known
security tokens that were used previously.
* Automatically generated autosuspend udev rules for whitelisted
* Automatically generated autosuspend udev rules for allow-listed
devices have been imported from the Chromium OS project. This should
improve power saving with many more devices.
@ -501,8 +1103,8 @@ CHANGES WITH 244:
configuration time using the -Dservice-watchdog= setting. If set to
empty, the watchdogs will be disabled.
* systemd-resolved validates IP addresses in certificates now when GnuTLS
is being used.
* systemd-resolved validates IP addresses in certificates now when GnuTLS
is being used.
* libcryptsetup >= 2.0.1 is now required.
@ -684,10 +1286,10 @@ CHANGES WITH 243:
the IO accounting data is included in the resource log message
generated whenever a unit stops.
* Units may now configure an explicit time-out to wait for when killed
* Units may now configure an explicit timeout to wait for when killed
with SIGABRT, for example when a service watchdog is hit. Previously,
the regular TimeoutStopSec= time-out was applied in this case too —
now a separate time-out may be set using TimeoutAbortSec=.
the regular TimeoutStopSec= timeout was applied in this case too —
now a separate timeout may be set using TimeoutAbortSec=.
* Services may now send a special WATCHDOG=trigger message with
sd_notify() to trigger an immediate "watchdog missed" event, and thus
@ -717,7 +1319,7 @@ CHANGES WITH 243:
* If processes terminated during the last phase of shutdown do not exit
quickly systemd will now show their names after a short time, to make
debugging easier. After a longer time-out they are forcibly killed,
debugging easier. After a longer timeout they are forcibly killed,
as before.
* journalctl (and the other tools that display logs) will now highlight
@ -760,7 +1362,7 @@ CHANGES WITH 243:
* systemd-networkd's DHCPv4 support now understands a new MaxAttempts=
option for configuring the maximum number of DHCP lease requests. It
also learnt a new BlackList= option for blacklisting DHCP servers (a
also learnt a new BlackList= option for deny-listing DHCP servers (a
similar setting has also been added to the IPv6 RA client), as well
as a SendRelease= option for configuring whether to send a DHCP
RELEASE message when terminating.
@ -988,7 +1590,7 @@ CHANGES WITH 243:
space if there are multiple devices with the highest priority.
* /etc/crypttab support has learnt a new keyfile-timeout= per-device
option that permits selecting the timout how long to wait for a
option that permits selecting the timeout how long to wait for a
device with an encryption key before asking for the password.
* IOWeight= has learnt to properly set the IO weight when using the
@ -1992,12 +2594,12 @@ CHANGES WITH 239:
any relevant symlinks both in /run and /etc.
* Note that all long-running system services shipped with systemd will
now default to a system call whitelist (rather than a blacklist, as
now default to a system call allow list (rather than a deny list, as
before). In particular, systemd-udevd will now enforce one too. For
most cases this should be safe, however downstream distributions
which disabled sandboxing of systemd-udevd (specifically the
MountFlags= setting), might want to disable this security feature
too, as the default whitelisting will prohibit all mount, swap,
too, as the default allow-listing will prohibit all mount, swap,
reboot and clock changing operations from udev rules.
* sd-boot acquired new loader configuration settings to optionally turn
@ -2025,7 +2627,7 @@ CHANGES WITH 239:
lookup is likely to trigger nss-ldap which in turn might use NSS to
ask systemd-resolved for hostname lookups. This will hence result in
a deadlock: a user name lookup in order to start
systemd-resolved.service will result in a host name lookup for which
systemd-resolved.service will result in a hostname lookup for which
systemd-resolved.service needs to be started already. There are
multiple ways to work around this problem: pre-allocate the
"systemd-resolve" user on such systems, so that nss-ldap won't be
@ -2994,7 +3596,7 @@ CHANGES WITH 235:
A/AAAA resource record for the "_gateway" hostname, pointing to the
current default IP gateway. Previously it did that for the "gateway"
name, hampering adoption, as some distributions wanted to leave that
host name open for local use. The old behaviour may still be
hostname open for local use. The old behaviour may still be
requested at build time.
* systemd-networkd's [Address] section in .network files gained a new
@ -3025,7 +3627,7 @@ CHANGES WITH 235:
* systemd-nspawn gained support for a new --system-call-filter= command
line option for adding and removing entries in the default system
call filter it applies. Moreover systemd-nspawn has been changed to
implement a system call whitelist instead of a blacklist.
implement a system call allow list instead of a deny list.
* systemd-run gained support for a new --pipe command line option. If
used the STDIN/STDOUT/STDERR file descriptors passed to systemd-run
@ -3513,7 +4115,7 @@ CHANGES WITH 233:
that is removed when the container dies. Specifically, if the source
directory is specified as empty string this mechanism is selected. An
example usage is --overlay=+/var::/var, which creates an overlay
mount based on the original /var contained in the image, overlayed
mount based on the original /var contained in the image, overlaid
with a temporary directory in the host's /var/tmp. This way changes
to /var are automatically flushed when the container shuts down.
@ -4335,7 +4937,7 @@ CHANGES WITH 230:
again don't consider turning this on in your stable, LTS or
production release just yet. (Note that you have to enable
nss-resolve in /etc/nsswitch.conf, to actually use systemd-resolved
and its DNSSEC mode for host name resolution from local
and its DNSSEC mode for hostname resolution from local
applications.)
* systemd-resolve conveniently resolves DANE records with the --tlsa
@ -5738,11 +6340,10 @@ CHANGES WITH 220:
fsck's progress report to an AF_UNIX socket in the file
system.
* udev will no longer create device symlinks for all block
devices by default. A blacklist for excluding special block
devices from this logic has been turned into a whitelist
that requires picking block devices explicitly that require
device symlinks.
* udev will no longer create device symlinks for all block devices by
default. A deny list for excluding special block devices from this
logic has been turned into a allow list that requires picking block
devices explicitly that require device symlinks.
* A new (currently still internal) API sd-device.h has been
added to libsystemd. This modernized API is supposed to
@ -6153,14 +6754,14 @@ CHANGES WITH 218:
for a unit, as declared in the (usually vendor-supplied)
system preset files.
* nss-myhostname will now resolve the single-label host name
* nss-myhostname will now resolve the single-label hostname
"gateway" to the locally configured default IP routing
gateways, ordered by their metrics. This assigns a stable
name to the used gateways, regardless which ones are
currently configured. Note that the name will only be
resolved after all other name sources (if nss-myhostname is
configured properly) and should hence not negatively impact
systems that use the single-label host name "gateway" in
systems that use the single-label hostname "gateway" in
other contexts.
* systemd-inhibit now allows filtering by mode when listing
@ -6500,7 +7101,7 @@ CHANGES WITH 217:
* Calendar time specifications in .timer units now also
understand the strings "semi-annually", "quarterly" and
"minutely" as shortcuts (in addition to the preexisting
"anually", "hourly", ...).
"annually", "hourly", ...).
* systemd-tmpfiles will now correctly create files in /dev
at boot which are marked for creation only at boot. It is
@ -7588,7 +8189,7 @@ CHANGES WITH 210:
reported by uname()'s "machine" field.
* systemd-networkd now supports matching on the system
virtualization, architecture, kernel command line, host name
virtualization, architecture, kernel command line, hostname
and machine ID.
* logind is now a lot more aggressive when suspending the
@ -7631,11 +8232,11 @@ CHANGES WITH 210:
Wikipedia. We explicitly document which base applies for
each configuration option.
* The DeviceAllow= setting in unit files now supports a syntax
to whitelist an entire group of devices node majors at once,
based on the /proc/devices listing. For example, with the
string "char-pts", it is now possible to whitelist all
current and future pseudo-TTYs at once.
* The DeviceAllow= setting in unit files now supports a syntax to
allow-list an entire group of devices node majors at once, based on
the /proc/devices listing. For example, with the string "char-pts",
it is now possible to allow-list all current and future pseudo-TTYs
at once.
* sd-event learned a new "post" event source. Event sources of
this type are triggered by the dispatching of any event
@ -7906,12 +8507,12 @@ CHANGES WITH 209:
example, a line that creates /run/nologin).
* A new API "sd-resolve.h" has been added which provides a simple
asynchronous wrapper around glibc NSS host name resolution
asynchronous wrapper around glibc NSS hostname resolution
calls, such as getaddrinfo(). In contrast to glibc's
getaddrinfo_a(), it does not use signals. In contrast to most
other asynchronous name resolution libraries, this one does
not reimplement DNS, but reuses NSS, so that alternate
host name resolution systems continue to work, such as mDNS,
hostname resolution systems continue to work, such as mDNS,
LDAP, etc. This API is based on libasyncns, but it has been
cleaned up for inclusion in systemd.
@ -9695,7 +10296,7 @@ CHANGES WITH 190:
when he over-mounts a non-empty directory.
* There are new specifiers that are resolved in unit files,
for the host name (%H), the machine ID (%m) and the boot ID
for the hostname (%H), the machine ID (%m) and the boot ID
(%b).
Contributions from: Allin Cottrell, Auke Kok, Brandon Philips,
@ -9878,9 +10479,9 @@ CHANGES WITH 187:
* journalctl gained the new "--header" switch to introspect
header data of journal files.
* A new setting SystemCallFilters= has been added to services
which may be used to apply blacklists or whitelists to
system calls. This is based on SECCOMP Mode 2 of Linux 3.5.
* A new setting SystemCallFilters= has been added to services which may
be used to apply deny lists or allow lists to system calls. This is
based on SECCOMP Mode 2 of Linux 3.5.
* nspawn gained a new --link-journal= switch (and quicker: -j)
to link the container journal with the host. This makes it

29
README
View File

@ -35,6 +35,7 @@ LICENSE:
REQUIREMENTS:
Linux kernel >= 3.13
Linux kernel >= 4.2 for unified cgroup hierarchy support
Linux kernel >= 5.4 for signed Verity images support
Kernel Config Options:
CONFIG_DEVTMPFS
@ -102,6 +103,9 @@ REQUIREMENTS:
CONFIG_EFIVAR_FS
CONFIG_EFI_PARTITION
Required for signed Verity images support:
CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG
We recommend to turn off Real-Time group scheduling in the
kernel when using systemd. RT group scheduling effectively
makes RT scheduling unavailable for most userspace, since it
@ -144,12 +148,13 @@ REQUIREMENTS:
libblkid >= 2.24 (from util-linux) (optional)
libkmod >= 15 (optional)
PAM >= 1.1.2 (optional)
libcryptsetup (optional)
libcryptsetup (optional), >= 2.3.0 required for signed Verity images support
libaudit (optional)
libacl (optional)
libselinux (optional)
liblzma (optional)
liblz4 >= 1.3.0 / 130 (optional)
libzstd >= 1.4.0 (optional)
libgcrypt (optional)
libqrencode (optional)
libmicrohttpd (optional)
@ -257,19 +262,19 @@ USERS AND GROUPS:
NSS:
systemd ships with four glibc NSS modules:
nss-myhostname resolves the local hostname to locally
configured IP addresses, as well as "localhost" to
127.0.0.1/::1.
nss-myhostname resolves the local hostname to locally configured IP
addresses, as well as "localhost" to 127.0.0.1/::1.
nss-resolve enables DNS resolution via the systemd-resolved
DNS/LLMNR caching stub resolver "systemd-resolved".
nss-resolve enables DNS resolution via the systemd-resolved DNS/LLMNR
caching stub resolver "systemd-resolved".
nss-mymachines enables resolution of all local containers registered
with machined to their respective IP addresses. It also maps UID/GIDs
ranges used by containers to useful names.
with machined to their respective IP addresses.
nss-systemd enables resolution of all dynamically allocated service
users. (See the DynamicUser= setting in unit files.)
nss-systemd enables resolution of users/group registered via the
User/Group Record Lookup API (https://systemd.io/USER_GROUP_API/),
including all dynamically allocated service users. (See the
DynamicUser= setting in unit files.)
To make use of these NSS modules, please add them to the "hosts:",
"passwd:" and "group:" lines in /etc/nsswitch.conf. The "resolve"
@ -278,8 +283,8 @@ NSS:
The four modules should be used in the following order:
passwd: compat mymachines systemd
group: compat mymachines systemd
passwd: compat systemd
group: compat systemd
hosts: files mymachines resolve [!UNAVAIL=return] dns myhostname
SYSV INIT.D SCRIPTS:

12
README.md
View File

@ -6,17 +6,21 @@ System and Service Manager
<a href="https://in.waw.pl/systemd-github-state/systemd-systemd-pull-requests.svg"><img align="right" src="https://in.waw.pl/systemd-github-state/systemd-systemd-pull-requests-small.svg" alt="Count of open pull requests over time"></a>
[![Semaphore CI Build Status](https://semaphoreci.com/api/v1/projects/28a5a3ca-3c56-4078-8b5e-7ed6ef912e14/443470/shields_badge.svg)](https://semaphoreci.com/systemd/systemd)<br/>
[![Coverity Scan Status](https://scan.coverity.com/projects/350/badge.svg)](https://scan.coverity.com/projects/350)<br/>
[![Fuzzit Status](https://app.fuzzit.dev/badge?org_id=systemd&branch=master)](https://app.fuzzit.dev/orgs/systemd/dashboard)<br/>
[![OSS-Fuzz Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/systemd.svg)](https://oss-fuzz-build-logs.storage.googleapis.com/index.html)<br/>
[![OSS-Fuzz Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/systemd.svg)](https://oss-fuzz-build-logs.storage.googleapis.com/index.html#systemd)<br/>
[![CIFuzz](https://github.com/systemd/systemd/workflows/CIFuzz/badge.svg)](https://github.com/systemd/systemd/actions)<br/>
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1369/badge)](https://bestpractices.coreinfrastructure.org/projects/1369)<br/>
[![Travis CI Build Status](https://travis-ci.org/systemd/systemd.svg?branch=master)](https://travis-ci.org/systemd/systemd)<br/>
[![Language Grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/systemd/systemd.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/systemd/systemd/context:cpp)<br/>
[![CentOS CI Build Status](https://ci.centos.org/buildStatus/icon?job=systemd-pr-build)](https://ci.centos.org/job/systemd-pr-build/)<br/>
[![Build Status](https://dev.azure.com/evvers/systemd-systemd/_apis/build/status/systemd.systemd?branchName=master)](https://dev.azure.com/evvers/systemd-systemd/_build/latest?definitionId=1&branchName=master)
[![Build Status](https://dev.azure.com/evvers/systemd-systemd/_apis/build/status/systemd.systemd?branchName=master)](https://dev.azure.com/evvers/systemd-systemd/_build/latest?definitionId=1&branchName=master)<br/>
[![Fossies codespell report](https://fossies.org/linux/test/systemd-master.tar.gz/codespell.svg)](https://fossies.org/linux/test/systemd-master.tar.gz/codespell.html)</br>
[![Packaging status](https://repology.org/badge/tiny-repos/systemd.svg)](https://repology.org/project/systemd/versions)
## Details
General information about systemd can be found in the [systemd Wiki](https://www.freedesktop.org/wiki/Software/systemd).
Most documentation is available on [systemd's web site](https://systemd.io/).
Assorted, older, general information about systemd can be found in the [systemd Wiki](https://www.freedesktop.org/wiki/Software/systemd).
Information about build requirements is provided in the [README file](README).

251
TODO
View File

@ -8,8 +8,6 @@ External:
* Fedora: add an rpmlint check that verifies that all unit files in the RPM are listed in %systemd_post macros.
* wiki: update journal format documentation for lz4 additions
Janitorial Clean-ups:
* Rearrange tests so that the various test-xyz.c match a specific src/basic/xyz.c again
@ -19,13 +17,164 @@ Janitorial Clean-ups:
Features:
* cryptsetup/homed: also support FIDO2 HMAC password logic for unlocking
devices. (see: https://github.com/mjec/fido2-hmac-secret)
* nspawn: move "incoming mount" directory to /run/host, move "inaccessible"
nodes to /run/host, move notify socket (for sd_notify() between payload and
container manager)
* cryptsetup: if keyfile specified in crypttab is AF_UNIX socket, connect to it
and read from it (like we do elsewhere with READ_FULL_FILE_CONNECT_SOCKET)
* repart: support setting up dm-integrity with HMAC
* add /etc/integritytab, to support dm-integrity setups. In particular those
with HMAC as hash function, so that we can have a protected /home without
encryption (leaving encryption to the individual dirs/homed).
* complement root=, rootflags=, rootfstype= with rootsubdir= which allows
mounting a subdir of the root fs as actual root. This can be used as
fstype-agnostic version of btrfs' rootflags=subvol=foobar.
* add --copy-from and --copy-to command to systemd-dissect which copies stuff
in and out of a disk image
* Support ProtectProc= or so, using: https://patchwork.kernel.org/cover/11310197/
* if /usr/bin/swapoff fails due to OOM, log a friendly explanatory message about it
* build short web pages out of each catalog entry, build them along with man
pages, and include hyperlinks to them in the journal output
* machined: add API to acquire UID range. add API to mount/dissect loopback
file. Both protected by PK. Then make nspawn use these APIs to run
unprivileged containers. i.e. push the truly privileged bits into machined,
so that the client side can remain entirely unprivileged, with SUID or
anything like that.
* journald: do journal file writing out-of-process, with one writer process per
client UID, so that synthetic hash table collisions can slow down a specific
user's journal stream down but not the others.
* add "throttling" to sd-event event sources: optionally, when we wake up too
often for one, let's turn it off entirely for a while. Use that for the
/proc/self/mountinfo logic.
* move our systemd-user PAM snippet to /usr/, which PAM appears to support
these days
* nspawn: support time namespaces
* systemd-firstboot: make sure to always use chase_symlinks() before
reading/writing files
* add ConditionSecurity=tpm2
* Remove any support for booting without /usr pre-mounted in the initrd entirely.
Update INITRD_INTERFACE.md accordingly.
* pid1: Move to tracking of main pid/control pid of units per pidfd
* pid1: support new clone3() fork-into-cgroup feature
* pid1: also remove PID files of a service when the service starts, not just
when it exits
* make us use dynamically fewer deps for containers in general purpose distros:
o turn into dlopen() deps:
- pcre2 (always) — irrelevant on Fedora, since dep by
libselinux, but should benefit Debian
- libpwquality (always) - only relevant for homed, and maybe soon
firstboot
- elfutils (always)
- p11-kit-trust (always)
- kmod-libs (only when called from PID 1)
- cryptsetup-libs (only in RootImage= handling in PID 1, but not in systemd-cryptsetup)
- similar: libblkid
- libpam (only when called from PID 1)
- bzip2, xz, lz4 (always — gzip and zstd should probably stay static deps the way they are,
since they are so basic and our defaults)
o move into separate libsystemd-shared-iptables.so .so
- iptables-libs (only used by nspawn + networkd)
* seccomp: when SystemCallArchitectures=native is set then don't install any
other seccomp filters for any of the other archs, in order to reduce the
number of seccomp filters we install needlessly.
* seccomp: maybe use seccomp_merge() to merge our filters per-arch if we can.
Apparently kernel performance is much better with fewer larger seccomp
filters than with more smaller seccomp filters.
* systemd-path: add ESP and XBOOTLDR path. Add "private" runtime/state/cache dir enum,
mapping to $RUNTIME_DIRECTORY, $STATE_DIRECTORY and such
* make "systemd-dissect" an official supported tool, i.e. move to /usr/bin/ and
provide man page. Given that we now have a tool that can generate images like
this, it's useful to have one that can dump contents of them, too.
* All tools that support --root= should also learn --image= so that they can
operate on disk images directly. Specifically: bootctl, tmpfiles, sysusers,
systemctl, repart, journalctl, coredumpctl. (Already done: systemd-nspawn,
systemd-firstboot)
* seccomp: by default mask x32 ABI system wide on x86-64. it's on its way out
* seccomp: don't install filters for ABIs that are masked anyway for the
specific service
* seccomp: maybe merge all filters we install into one with that libseccomp API that allows merging.
* per-service credential system. Specifically: add LoadCredential= (for loading
cred from file), AcquireCredential= (for asking user for cred, via
ask-password), PassCredential= (for passing on credential systemd itself
got). Then, place credentials in a per-service, immutable ramfs instance (so
that it cannot be swapped out), destroy after use. Also pass via keyring
(with graceful fallback to cover for containers). Define CredentialPath= for
defining subdir of /run/credentials/ where to place it. Set $CREDENTIAL_PATH
env var for services to the result. Also pass via fd passing (optionally).
* homed: add native recovery key support. use 48 lowercase modhex characters
(192bit), show qr code of it, include pattern expression in user record.
* homed: introduce "degraded" state for home directories that weren't cleanly
unmounted (use xattr we add and remove on the loop back file)
* homed: during login resize fs automatically towards size goal. Specifically,
resize to diskSize if possible, but leave a certain amount (configured by a
new value diskLeaveFreeSize) of space free on the backing fs.
* homed: permit multiple user record signing keys to be used locally, and pick
the right one for signing records automatically depending on a pre-existing
signature
* homed: add a way to "adopt" a home directory, i.e. strip foreign signatures
and insert a local signature instead.
* homed: as an extension to the directory+subvolume backend: if located on
especially marked fs, then sync down password into LUKS header of that fs,
and always verify passwords against it too. Bootstrapping is a problem
though: if no one is logged in (or no other user even exists yet), how do you
unlock the volume in order to create the first user and add the first pw.
* homed: support new FS_IOC_ADD_ENCRYPTION_KEY ioctl for setting up fscrypt
* homed: maybe pre-create ~/.cache as subvol so that it can have separate quota
easily?
* busctl: maybe expose a verb "ping" for pinging a dbus service to see if it
exists and responds.
* when systemd-nspawn and suchlike dissect an OS image, and there are multiple
root partitions, do an strverscmp() on the partition label and boot
first. That is inspired how sd-boot figures out which kernel to boot, and
thus allows defining OS images which can be A/B updated and we default to the
newest version automatically, both in nspawn and in sd-boot
* cryptsetup: support FIDO2 tokens for deriving keys (i.e. do what homed can do
also in plain cryptsetup)
* systemd-gpt-auto should probably set x-systemd.growfs on the mounts it
creates
* homed/userdb: distuingish passwords and recovery keys in the records, since
* homed/userdb: distinguish passwords and recovery keys in the records, since
we probably want to use different PBKDF algorithms/settings for them:
passwords have low entropy but recovery keys should have good entropy key
hence we can make them quicker to work.
@ -35,12 +184,13 @@ Features:
- teach it to copy in unified kernel images and maybe type #1 boot loader spec entries from host
- make it operate on loopback files, dissecting enough to find ESP to operate on
* Maybe add a separate GPT partition type to the discoverable partition spec
for "hibernate" partitions, that are exactly like swap partitions but only
activated right before hibernation and thus never used for regular swapping.
* by default, in systemd --user service bump the OOMAdjust to 100, as privs
allow so that systemd survives
* honour specifiers in unit files that resolve to some very basic
/etc/os-release data, such as ID, VERSION_ID, BUILD_ID, VARIANT_ID.
* cryptsetup: allow encoding key directly in /etc/crypttab, maybe with a
"base64:" prefix. Useful in particular for pkcs11 mode.
@ -48,9 +198,10 @@ Features:
systemd-makefs.service instead.
* socket units: allow creating a udev monitor socket with ListenDevices= or so,
with matches, then actviate app thorugh that passing socket oveer
with matches, then activate app through that passing socket over
* unify on openssl:
* unify on openssl (as soon as OpenSSL 3.0 is out, and the Debian license
confusion is gone)
- port sd_id128_get_machine_app_specific() over from khash
- port resolved over from libgcrypt (DNSSEC code)
- port journald + fsprg over from libgcrypt
@ -72,17 +223,10 @@ Features:
that the device paths stay the same, regardless if crypto is used or not.
* systemd-repart: by default generate minimized partition tables (i.e. tables
that only covere the space actually used, excluding any free space at the
that only cover the space actually used, excluding any free space at the
end), in order to maximize dd'ability. Requires libfdisk work, see
https://github.com/karelzak/util-linux/issues/907
* systemd-repart: optionally, allow specifiying a path to initialize new
partitions from, i.e. an fs image file or a source device node. This would
then turn systemd-repart into a simple installer: with a few .repart files
you could replicate the host system on another device. a full installer would
then be: "systemd-repart /dev/sda && bootctl install /dev/sda &&
systemd-firstboot --image= …"
* systemd-repart: MBR partition table support. Care needs to be taken regarding
Type=, so that partition definitions can sanely apply to both the GPT and the
MBR case. Idea: accept syntax "Type=gpt:home mbr:0x83" for setting the types
@ -98,26 +242,37 @@ Features:
* systemd-repart: allow managing the gpt read-only partition flag + auto-mount flag
* systemd-repart: allow boolean option that ensures that if existing partition
doesn't exist within the configured size bounds the whole command fails. This
is useful to implement ESP vs. XBOOTLDR schemes in installers: have one set
of repart files for the case where ESP is large enough and one where it isn't
and XBOOTLDR is added in instead. Then apply the former first, and if it
fails to apply use the latter.
* systemd-repart: add per-partition option to never reuse existing partition
and always create anew even if matching partition already exists.
* systemd-repart: add per-partition option to fail if partition already exist,
i.e. is not added new. Similar, add option to fail if partition does not exist yet.
* systemd-repart: add --size=auto for generating/resizing images of minimal
size, i.e. where the image file is sized exactly as large as necessary taking
SizeMin= into account, but not a single byte larger.
* systemd-repart: allow disabling growing of specific partitions, or making
them (think ESP: we don't ever want to grow it, since we cannot resize vfat)
* systemd-repart: add specifier expansion, add especifier that refers to root
device node of current system, /usr device node, and matching verity, so that
an installer can be made a "copy" installer of the booted OS
* systemd-repart: make it a static checker during early boot for existence and
absence of other partitions for trusted boot environments
* systemd-repart: when no configuration is found, exit early do not check
partition table, so that it is safe to run in the initrd on any system
* userdb: allow username prefix searches in varlink API, allow realname and
realname substr searches in varlink API
* systemd-repart: allow config of partition uuid
* userdb: allow username prefix searches in varlink API
* userdb: allow uid/gid range checks
* userdb: allow existence checks
* pid: activation by journal search expression
* pid1: activation by journal search expression
* when switching root from initrd to host, set the machine_id env var so that
if the host has no machine ID set yet we continue to use the random one the
@ -176,14 +331,11 @@ Features:
* systemd-firstboot: teach it dissector magic, so that you can point it to some
disk image and it will just set everything in it all behind the scenes.
* systemd-firstboot: add --force mode that replaces existing configuration.
* We should probably replace /var/log/README, /etc/rc.d/README with symlinks
that are linked to these places instead of copied. After all they are
constant vendor data.
* maybe add kernel cmdline params: 1) to force first-boot mode + 2) to force
random seed crediting
* maybe add kernel cmdline params: to force random seed crediting
* nspawn: on cgroupsv1 issue cgroup empty handler process based on host events,
so that we make cgroup agent logic safe
@ -197,11 +349,9 @@ Features:
* homed:
- when user tries to log into record signed by unrecognized key, automatically add key to our chain after polkit auth
- hook up machined/nspawn users with a varlink user query interface
- rollback when resize fails mid-operation
- GNOME's side for forget key on suspend (requires rework so that lock screen runs outside of uid)
- resize on login?
- fstrim on logout?
- shrink fs on logout?
- update LUKS password on login if we find there's a password that unlocks the JSON record but not the LUKS device.
- create on activate?
@ -210,8 +360,9 @@ Features:
beefing up logind to make pam session close hook synchronous and wait until
systemd --user is shut down.
- logind: maybe keep a "busy fd" as long as there's a non-released session around or the user@.service
- maybe make automatic, read-only, time-based reflink-copies of LUKS disk images (think: time machine)
- distuingish destroy / remove (i.e. currently we can unregister a user, unregister+remove their home directory, but not just remove their home directory)
- maybe make automatic, read-only, time-based reflink-copies of LUKS disk
images (and btrfs snapshots of subvolumes) (think: time machine)
- distinguish destroy / remove (i.e. currently we can unregister a user, unregister+remove their home directory, but not just remove their home directory)
- in systemd's PAMName= logic: query passwords with ssh-askpassword, so that we can make "loginctl set-linger" mode work
- fingerprint authentication, pattern authentication, …
- make sure "classic" user records can also be managed by homed
@ -226,6 +377,9 @@ Features:
- make slice for users configurable (requires logind rework)
- logind: populate auto-login list bus property from PKCS#11 token
- when determining state of a LUKS home directory, check DM suspended sysfs file
- introduce API for "making room", that grows/shrinks home directory
according to elastic parameters, discards blocks, and removes additional snapshots. Call it
either from UI when disk space gets low
* introduce a new per-process uuid, similar to the boot id, the machine id, the
invocation id, that is derived from process creds, specifically a hashed
@ -802,6 +956,10 @@ Features:
* teach ConditionKernelCommandLine= globs or regexes (in order to match foobar={no,0,off})
* Add ConditionDirectoryNotEmpty= handle non-absoute paths as a search path or add
ConditionConfigSearchPathNotEmpty= or different syntax? See the discussion starting at
https://github.com/systemd/systemd/pull/15109#issuecomment-607740136.
* BootLoaderSpec: Clarify that the kernel has to be in $BOOT. Clarify
that the boot loader should be installed to the ESP. Define a way
how an installer can figure out whether a BLS compliant boot loader
@ -857,6 +1015,7 @@ Features:
make assumptions about their slice anymore.
- follow PropertiesChanged state more closely, to deal with quick logouts and
relogins
- (optionally?) spawn seat-manager@$SEAT.service whenever a seat shows up that as CanGraphical set
* journal:
- consider introducing implicit _TTY= + _PPID= + _EUID= + _EGID= + _FSUID= + _FSGID= fields
@ -874,7 +1033,7 @@ Features:
- journal: add a setgid "systemd-journal" utility to invoke from libsystemd-journal, which passes fds via STDOUT and does PK access
- journactl: support negative filtering, i.e. FOOBAR!="waldo",
and !FOOBAR for events without FOOBAR.
- journal: store timestamp of journal_file_set_offline() int he header,
- journal: store timestamp of journal_file_set_offline() in the header,
so it is possible to display when the file was last synced.
- journal-send.c, log.c: when the log socket is clogged, and we drop, count this and write a message about this when it gets unclogged again.
- journal: find a way to allow dropping history early, based on priority, other rules
@ -916,6 +1075,7 @@ Features:
them via machined, and also watch containers coming and going.
Benefit: nspawn --ephemeral would start working nicely with the journal.
- assign MESSAGE_ID to log messages about failed services
- check if loop in decompress_blob_xz() is necessary
* add a test if all entries in the catalog are properly formatted.
(Adding dashes in a catalog entry currently results in the catalog entry
@ -1131,18 +1291,15 @@ Features:
* networkd:
- add more keys to [Route] and [Address] sections
- add support for more DHCPv4 options (and, longer term, other kinds of dynamic config)
- add proper initrd support (in particular generate .network/.link files based on /proc/cmdline)
- add reduced [Link] support to .network files
- add Scope= parsing option for [Network]
- properly handle routerless dhcp leases
- work with non-Ethernet devices
- add support for more bond options
- dhcp: do we allow configuring dhcp routes on interfaces that are not the one we got the dhcp info from?
- the DHCP lease data (such as NTP/DNS) is still made available when
a carrier is lost on a link. It should be removed instantly.
- expose in the API the following bits:
- option 15, domain name and/or option 119, search list
- option 12, host name and/or option 81, fqdn
- option 15, domain name
- option 12, hostname and/or option 81, fqdn
- option 123, 144, geolocation
- option 252, configure http proxy (PAC/wpad)
- provide a way to define a per-network interface default metric value
@ -1150,11 +1307,9 @@ Features:
- allow Name= to be specified repeatedly in the [Match] section. Maybe also
support Name=foo*|bar*|baz ?
- duplicate address check for static IPs (like ARPCHECK in network-scripts)
- allow DUID/IAID to be customized, see issue #394.
- whenever uplink info changes, make DHCP server send out FORCERENEW
* networkd-wait-online:
- make operstates to wait for configurable?
* Figure out how to do unittests of networkd's state serialization
* dhcp:
- figure out how much we can increase Maximum Message Size
@ -1179,20 +1334,14 @@ External:
- natively watch for dbus-*.service symlinks (PENDING)
- teach dbus to activate all services it finds in /etc/systemd/services/org-*.service
* fix alsa mixer restore to not print error when no config is stored
* make cryptsetup lower --iter-time
* patch kernel for xattr support in /dev, /proc/, /sys?
* kernel: add device_type = "fb", "fbcon" to class "graphics"
* /usr/bin/service should actually show the new command line
* fedora: suggest auto-restart on failure, but not on success and not on coredump. also, ask people to think about changing the start limit logic. Also point people to RestartPreventExitStatus=, SuccessExitStatus=
* fedora: F20: go timer units all the way, leave cron.daily for cron
* neither pkexec nor sudo initialize environ[] from the PAM environment?
* fedora: update policy to declare access mode and ownership of unit files to root:root 0644, and add an rpmlint check for it

88
catalog/systemd.catalog.in
View File

@ -302,7 +302,8 @@ shut down.
Subject: DNSSEC mode has been turned off, as server doesn't support it
Defined-By: systemd
Support: %SUPPORT_URL%
Documentation: man:systemd-resolved.service(8) resolved.conf(5)
Documentation: man:systemd-resolved.service(8)
Documentation: man:resolved.conf(5)
The resolver service (systemd-resolved.service) has detected that the
configured DNS server does not support DNSSEC, and DNSSEC validation has been
@ -417,6 +418,7 @@ Note that the memory pressure might or might not have been caused by @UNIT@.
Subject: Accepting user/group name @USER_GROUP_NAME@, which does not match strict user/group name rules.
Defined-By: systemd
Support: %SUPPORT_URL%
Documentation: https://systemd.io/USER_NAMES
The user/group name @USER_GROUP_NAME@ has been specified, which is accepted
according the relaxed user/group name rules, but does not qualify under the
@ -432,6 +434,86 @@ characters; names not valid UTF-8; names with leading or trailing whitespace;
the strings "." or ".."; fully numeric strings, or strings beginning in a
hyphen and otherwise fully numeric.
For further details on strict and relaxed user/group name rules, see:
-- 1b3bb94037f04bbf81028e135a12d293
Subject: Failed to generate valid unit name from path '@MOUNT_POINT@'.
Defined-By: systemd
Support: %SUPPORT_URL%
https://systemd.io/USER_NAMES
The following mount point path could not be converted into a valid .mount
unit name:
@MOUNT_POINT@
Typically this means that the path to the mount point is longer than allowed
for valid unit names.
systemd dynamically synthesizes .mount units for all mount points appearing on
the system. For that a simple escaping algorithm is applied: the absolute path
name is used, with all "/" characters replaced by "-" (the leading one is
removed). Moreover, any non-alphanumeric characters (as well as any of ":",
"-", "_", ".", "\") are replaced by "\xNN" where "NN" is the hexadecimal code
of the character. Finally, ".mount" is suffixed. The resulting string must be
under 256 characters in length to be a valid unit name. This restriction is
made in order for all unit names to also be suitable as file names. If a mount
point appears that — after escaping — is longer than this limit it cannot be
mapped to a unit. In this case systemd will refrain from synthesizing a unit
and cannot be used to manage the mount point. It will not appear in the service
manager's unit table and thus also not be torn down safely and automatically at
system shutdown.
It is generally recommended to avoid such overly long mount point paths, or —
if used anyway – manage them independently of systemd, i.e. establish them as
well as tear them down automatically at system shutdown by other software.
-- b480325f9c394a7b802c231e51a2752c
Subject: Special user @OFFENDING_USER@ configured, this is not safe!
Defined-By: systemd
Support: %SUPPORT_URL%
Documentation: https://systemd.io/UIDS-GIDS
The unit @UNIT@ is configured to use User=@OFFENDING_USER@.
This is not safe. The @OFFENDING_USER@ user's main purpose on Linux-based
operating systems is to be the owner of files that otherwise cannot be mapped
to any local user. It's used by the NFS client and Linux user namespacing,
among others. By running a unit's processes under the identity of this user
they might possibly get read and even write access to such files that cannot
otherwise be mapped.
It is strongly recommended to avoid running services under this user identity,
in particular on systems using NFS or running containers. Allocate a user ID
specific to this service, either statically via systemd-sysusers or dynamically
via the DynamicUser= service setting.
-- 1c0454c1bd2241e0ac6fefb4bc631433
Subject: systemd-udev-settle.service is deprecated.
Defined-By: systemd
Support: %SUPPORT_URL%
Usage of the systemd service unit systemd-udev-settle.service is deprecated. It
inserts artificial delays into the boot process without providing the
guarantees other subsystems traditionally assumed it provides. Relying on this
service is racy, and it is generally a bug to make use of it and depend on it.
Traditionally, this service's job was to wait until all devices a system
possesses have been fully probed and initialized, delaying boot until this
phase is completed. However, today's systems and hardware generally don't work
this way anymore, hardware today may show up any time and take any time to be
probed and initialized. Thus, in the general case, it's no longer possible to
correctly delay boot until "all devices" have been processed, as it is not
clear what "all devices" means and when they have been found. This is in
particular the case if USB hardware or network-attached hardware is used.
Modern software that requires some specific hardware (such as a network device
or block device) to operate should only wait for the specific devices it needs
to show up, and otherwise operate asynchronously initializing devices as they
appear during boot and during runtime without delaying the boot process.
It is a defect of the software in question if it doesn't work this way, and
still pulls systemd-udev-settle.service into the boot process.
Please file a bug report against the following units, with a request for it to
be updated to operate in a hotplug fashion without depending on
systemd-udev-settle.service:
@OFFENDING_UNITS@

115
catalog/systemd.pl.catalog.in
View File

@ -298,7 +298,8 @@ Maszyna wirtualna @NAME@ (PID prowadzący @LEADER@) została wyłączona.
Subject: Wyłączono tryb DNSSEC, ponieważ serwer go nie obsługuje
Defined-By: systemd
Support: %SUPPORT_URL%
Documentation: man:systemd-resolved.service(8) resolved.conf(5)
Documentation: man:systemd-resolved.service(8)
Documentation: man:resolved.conf(5)
Usługa resolver (systemd-resolved.service) wykryła, że skonfigurowany serwer
DNS nie obsługuje DNSSEC, w wyniku czego walidacja DNSSEC została wyłączona.
@ -411,3 +412,115 @@ i jądro wymusiło zakończenie jego działania.
Proszę zauważyć, że brak pamięci mógł nie zostać spowodowany
przez jednostkę @UNIT@.
-- b61fdac612e94b9182285b998843061f
Subject: Przyjmowanie nazwy użytkownika/grupy @USER_GROUP_NAME@, która nie zgadza się ze ścisłymi regułami nazw użytkowników/grup.
Defined-By: systemd
Support: %SUPPORT_URL%
Documentation: https://systemd.io/USER_NAMES
Podano nazwę użytkownika/grupy @USER_GROUP_NAME@, co zostało przyjęte
zgodnie z rozluźnionymi regułami nazw użytkowników/grup, ale nie spełnia
ścisłych reguł.
Ścisłe reguły nazw użytkowników/grup zapisane jako wyrażenie regularne to:
^[a-zA-Z_][a-zA-Z0-9_-]{0,30}$
Rozluźnione reguły nazw użytkowników/grup przyjmują wszystkie nazwy,
oprócz pustego ciągu, nazw zawierających bajty NUL, znaki kontrolne,
dwukropki lub ukośniki, nazw niebędących prawidłowym tekstem UTF-8,
nazw z początkową lub końcową spacją, ciągów „.” lub „..”, ciągów
zawierających tylko cyfry lub ciągów zaczynających się myślnikiem
i zawierających oprócz niego tylko cyfry.
-- 1b3bb94037f04bbf81028e135a12d293
Subject: Utworzenie prawidłowej nazwy jednostki ze ścieżki „@MOUNT_POINT@” się nie powiodło.
Defined-By: systemd
Support: %SUPPORT_URL%
Następująca ścieżka do punktu montowania nie może zostać przekonwertowana
na prawidłową nazwę jednostki .mount:
@MOUNT_POINT@
Zwykle oznacza to, że ścieżka do punktu montowania jest dłuższa niż dozwolona
dla prawidłowych nazw jednostek.
systemd dynamicznie syntetyzuje jednostki .mount dla wszystkich punktów
montowania pojawiających się na komputerze. Stosowany do tego jest prosty
algorytm: używana jest bezwzględna nazwa ścieżki ze wszystkimi znakami „/”
zastąpionymi znakami „-” (początkowy jest usuwany). Co więcej, wszystkie
niealfanumeryczne znaki (a także „:”, „-”, „_”, „.”, „\”) są zastępowane
„\xNN”, gdzie „NN” jest szesnastkowym kodem znaki. Na końcu dołączany jest
przyrostek „.mount”. Wynikowy ciąg musi mieć poniżej 256 znaków długości,
aby był prawidłową nazwą jednostki. To ograniczenie obowiązuje, aby wszystkie
nazwy jednostek mogły być używane także jako nazwy plików. Jeśli punkt
montowania — po zastosowaniu algorytmu — jest dłuższy niż to ograniczenie,
to nie może zostać zmapowany do jednostki. W takim przypadku systemd nie
zsyntetyzuje jednostki i nie może być używany do zarządzania punktem
montowania. Nie pojawi się w tabeli jednostek menedżera usług, przez co
nie zostanie także bezpiecznie i automatycznie zdjęty podczas wyłączania
komputera.
Zasadniczo zalecane jest unikanie takich za długich ścieżek do punktów
montowania, a jeśli są używane mimo to, zarządzanie nimi niezależnie
od systemd, tzn. stawianie ich i automatyczne zdejmowanie podczas
wyłączania komputera przez inne oprogramowanie.
-- b480325f9c394a7b802c231e51a2752c
Subject: Skonfigurowany jest szczególny użytkownik @OFFENDING_USER@, jest to niebezpieczne!
Defined-By: systemd
Support: %SUPPORT_URL%
Documentation: https://systemd.io/UIDS-GIDS
Jednostka @UNIT@ jest skonfigurowana do używania User=@OFFENDING_USER@.
Nie jest to bezpieczne. Głównym zastosowaniem użytkownika @OFFENDING_USER@
w linuksowych systemach operacyjnych jest bycie właścicielem plików, których
nie można w inny sposób zmapować do żadnego lokalnego użytkownika. Jest
używany między innymi przez klienta NFS i przestrzenie nazw użytkowników
Linuksa. Wykonywanie procesów jednostki pod tożsamością tego użytkownika
może spowodować, że będą one miały dostęp do odczytu, a może nawet do zapisu,
plików, których nie można zmapować w inny sposób.
Mocno zalecane jest unikanie wykonywania usług pod tą tożsamością użytkownika,
zwłaszcza na komputerach używających NFS lub mających kontenery. Należy
przydzielić identyfikator użytkownika dla tej konkretnej usługi, statycznie
przez systemd-sysusers lub dynamicznie przez ustawienie usługi DynamicUser=.
-- 1c0454c1bd2241e0ac6fefb4bc631433
Subject: Usługa systemd-udev-settle.service jest przestarzała.
Defined-By: systemd
Support: %SUPPORT_URL%
Użycie jednostki usługi systemd „systemd-udev-settle.service” jest
przestarzałe. Wstawia ona sztuczne opóźnienie do procesu uruchamiania
bez dostarczania gwarancji, które były oczekiwane przez pozostałe
podsystemy. Korzystanie z tej usługi może prowadzić do hazardów,
i zasadniczo jest błędem.
W przeszłości zadaniem tej usługi było oczekiwanie, aż wszystkie urządzenia
komputera zostaną w pełni wykryte i zainicjowane, opóźniając uruchamianie
do ukończenia tego etapu. Jednakże, współczesne komputery i urządzenia
na ogół nie działają już w ten sposób, tylko mogą pojawić się w dowolnej
chwili i zająć dowolny czas na wykrycie i inicjację. Z tego powodu,
w ogólnym przypadku, nie jest już możliwe poprawne opóźnienie uruchamiania
do przetworzenia „wszystkich urządzeń”, ponieważ nie jest jasne, co znaczy
„wszystkie urządzenia” i kiedy zostały odnalezione. Dotyczy to zwłaszcza
urządzeń podłączonych przez USB lub sieć.
Nowoczesne oprogramowanie wymagające określonego sprzętu (takiego jak
urządzenie sieciowe lub urządzenie blokowe) do działania powinno oczekiwać
tylko na pojawienie się danego urządzenia, a w przeciwnym razie działać
asynchronicznie, inicjując urządzenia, kiedy te pojawiają się w trakcie
uruchamiania i w trakcie działania systemu bez opóźniania procesu uruchamiania.
Jest to wada danego oprogramowania, jeśli nie działa ono w ten sposób
i nadal wciąga usługę systemd-udev-settle.service do procesu uruchamiania.
Prosimy zgłosić błąd w następujących jednostkach z prośbą
o ich aktualizację tak, aby działały w sposób dynamiczny
bez zależności od usługi systemd-udev-settle.service:
@OFFENDING_UNITS@

18
coccinelle/set_ensure_put.cocci Normal file
View File

@ -0,0 +1,18 @@
@@
local idexpression r;
expression p, k, x;
@@
- r = set_ensure_allocated(&p, k);
- if (r < 0)
- return ...;
- r = set_put(p, x);
+ r = set_ensure_put(&p, k, x);
@@
local idexpression r;
expression p, k, x;
@@
- r = set_ensure_allocated(p, k);
- if (r < 0)
- return ...;
- r = set_put(*p, x);
+ r = set_ensure_put(p, k, x);

16
coccinelle/strempty.cocci
View File

@ -1,6 +1,18 @@
@@
/* Avoid running this transformation on the strempty function itself */
position p : script:python() { p[0].current_element != "strempty" };
/* Avoid running this transformation on the strempty function itself and
* on the "make_expression" macro in src/libsystemd/sd-bus/bus-convenience.c.
* As Coccinelle's Location object doesn't support macro "detection", use
* a pretty horrifying combo of specifying a file and a special "something_else"
* position element, which is, apparently, the default value of
* "current_element" before it's set (according to the source code), thus
* matching any "top level" position, including macros. Let's hope we never
* introduce a function called "something_else"...
*/
position p : script:python() {
not (p[0].current_element == "strempty" or
(p[0].file == "src/libsystemd/sd-bus/bus-convenience.c" and
p[0].current_element == "something_else"))
};
expression s;
@@
(

6
docs/AUTOMATIC_BOOT_ASSESSMENT.md
View File

@ -101,9 +101,9 @@ Here's an example walkthrough of how this all fits together.
6. If this boot also fails, on the next boot the boot loader will see the
tag `+0-3`, i.e. the counter reached zero. At this point the entry will be
considered "bad", and ordered to the end of the list of entries. The next
newest boot entry is now tried, i.e. the system automatically reverted back
to an earlier version.
considered "bad", and ordered to the beginning of the list of entries. The
next newest boot entry is now tried, i.e. the system automatically reverted
back to an earlier version.
The above describes the walkthrough when the selected boot entry continuously
fails. Let's have a look at an alternative ending to this walkthrough. In this

4
docs/BOOT_LOADER_SPECIFICATION.md
View File

@ -47,7 +47,7 @@ functionality. Here's why we think that it is not enough for our uses:
* The various EFI implementations implement the boot order/boot item logic to different levels. Some firmware implementations do not offer a boot menu at all and instead unconditionally follow the EFI boot order, booting the first item that is working.
* If the firmware setup is used to reset all data usually all EFI boot entries are lost, making the system entirely unbootable, as the firmware setups generally do not offer a UI to define additional boot items. By placing the menu item information on disk, it is always available, regardless if the BIOS setup data is lost.
* Harddisk images should be moveable between machines and be bootable without requiring explicit EFI variables to be set. This also requires that the list of boot options is defined on disk, and not in EFI variables alone.
* Harddisk images should be movable between machines and be bootable without requiring explicit EFI variables to be set. This also requires that the list of boot options is defined on disk, and not in EFI variables alone.
* EFI is not universal yet (especially on non-x86 platforms), this specification is useful both for EFI and non-EFI boot loaders.
* Many EFI systems disable USB support during early boot to optimize boot times, thus making keyboard input unavailable in the EFI menu. It is thus useful if the OS UI has a standardized way to discover available boot options which can be booted to.
@ -95,7 +95,7 @@ Note that the `$BOOT` partition is not supposed to be exclusive territory of
this specification. This specification only defines semantics of the `/loader/`
directory inside the file system (see below), but it doesn't intend to define
ownership of the whole file system exclusively. Boot loaders, firmware, and
other software implementating this specification may choose to place other
other software implementing this specification may choose to place other
files and directories in the same file system. For example, boot loaders that
implement this specification might install their own boot code into the `$BOOT`
partition. On systems where `$BOOT` is the ESP this is a particularly common

2
docs/CGROUP_DELEGATION.md
View File

@ -131,6 +131,8 @@ If you wonder how to detect which of these three modes is currently used, use
you are either in legacy or hybrid mode. To distinguish these two cases, run
`statfs()` again on `/sys/fs/cgroup/unified/`. If that succeeds and reports
`CGROUP2_SUPER_MAGIC` you are in hybrid mode, otherwise not.
From a shell, you can use check the `Type` in `stat -f /sys/fs/cgroup` and
`stat -f /sys/fs/cgroup/unified`.
## systemd's Unit Types

3
docs/CODE_QUALITY.md
View File

@ -71,5 +71,8 @@ available functionality:
See [Testing systemd using sanitizers](https://systemd.io/TESTING_WITH_SANITIZERS)
for more information.
16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell).
The systemd report can be found [here](https://fossies.org/linux/test/systemd-master.tar.gz/codespell.html).
Access to Coverity and oss-fuzz reports is limited. Please reach out to the
maintainers if you need access.

4
docs/CODING_STYLE.md
View File

@ -424,7 +424,7 @@ layout: default
## Deadlocks
- Do not issue NSS requests (that includes user name and host name lookups)
- Do not issue NSS requests (that includes user name and hostname lookups)
from PID 1 as this might trigger deadlocks when those lookups involve
synchronously talking to services that we would need to start up.
@ -521,7 +521,7 @@ layout: default
hence we might want to call it "big endian" right-away.
- Please never use `dup()`. Use `fcntl(fd, F_DUPFD_CLOEXEC, 3)` instead. For
two reason: first, you want `O_CLOEXEC` set on the new `fd` (see
two reasons: first, you want `O_CLOEXEC` set on the new `fd` (see
above). Second, `dup()` will happily duplicate your `fd` as 0, 1, 2,
i.e. stdin, stdout, stderr, should those `fd`s be closed. Given the special
semantics of those `fd`s, it's probably a good idea to avoid

10
docs/CONTAINER_INTERFACE.md
View File

@ -121,6 +121,16 @@ manager, please consider supporting the following interfaces.
`container_ttys=pts/7 pts/8 pts/14` it will spawn three additional login
gettys on ptys 7, 8, and 14.
4. To allow applications to detect the OS version and other metadata of the host
running the container manager, if this is considered desirable, please parse
the host's `/etc/os-release` and set a `$container_host_<key>=<VALUE>`
environment variable for the ID fields described by the [os-release
interface](https://www.freedesktop.org/software/systemd/man/os-release.html), eg:
`$container_host_id=debian`
`$container_host_build_id=2020-06-15`
`$container_host_variant_id=server`
`$container_host_version_id=10`
## Advanced Integration
1. Consider syncing `/etc/localtime` from the host file system into the

4
docs/CONTRIBUTING.md
View File

@ -11,7 +11,7 @@ We welcome contributions from everyone. However, please follow the following gui
## Filing Issues
* We use [GitHub Issues](https://github.com/systemd/systemd/issues) **exclusively** for tracking **bugs** and **feature** **requests** of systemd. If you are looking for help, please contact [systemd-devel mailing list](https://lists.freedesktop.org/mailman/listinfo/systemd-devel) instead.
* We only track bugs in the **two** **most** **recently** **released** **versions** of systemd in the GitHub Issue tracker. If you are using an older version of systemd, please contact your distribution's bug tracker instead.
* We only track bugs in the **two** **most** **recently** **released** (non-rc) **versions** of systemd in the GitHub Issue tracker. If you are using an older version of systemd, please contact your distribution's bug tracker instead (see below). See [GitHub Release Page](https://github.com/systemd/systemd/releases) for the list of most recent releases.
* When filing an issue, specify the **systemd** **version** you are experiencing the issue with. Also, indicate which **distribution** you are using.
* Please include an explanation how to reproduce the issue you are pointing out.
@ -20,7 +20,7 @@ Following these guidelines makes it easier for us to process your issue, and ens
### Older downstream versions
For older versions that are still supported by your distribution please use respective downstream tracker:
* **Fedora** - [bugzilla](https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=systemd)
* **RHEL-7/CentOS-7** - [bugzilla](https://bugzilla.redhat.com/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%207&component=systemd) or [systemd-rhel github](https://github.com/lnykryn/systemd-rhel/issues)
* **RHEL/CentOS** - [bugzilla](https://bugzilla.redhat.com/) or [systemd-rhel github](https://github.com/systemd-rhel/)
* **Debian** - [bugs.debian.org](https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=systemd)
## Security vulnerability reports

135
docs/CONVERTING_TO_HOMED.md Normal file
View File

@ -0,0 +1,135 @@
---
title: Converting Existing Users to systemd-homed
category: Users, Groups and Home Directories
layout: default
---
# Converting Existing Users to systemd-homed managed Users
Traditionally on most Linux distributions, regular (human) users are managed
via entries in `/etc/passwd`, `/etc/shadow`, `/etc/group` and
`/etc/gshadow`. With the advent of
[`systemd-homed`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html)
it might be desirable to convert an existing, traditional user account to a
`systemd-homed` managed one. Below is a brief guide how to do that.
Before continuing, please read up on these basic concepts:
* [Home Directories](https://systemd.io/HOME_DIRECTORY)
* [JSON User Records](https://systemd.io/USER_RECORD)
* [JSON Group Records](https://systemd.io/GROUP_RECORD)
* [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API)
## Caveat
This is a manual process, and possibly a bit fragile. Hence, do this at your
own risk, read up beforehand, and make a backup first. You know what's at
stake: your own home directory, i.e. all your personal data.
## Step-By-Step
Here's the step-by-step guide:
0. Preparations: make sure you run a distribution that has `systemd-homed`
enabled and properly set up, including the necessary PAM and NSS
configuration updates. Make sure you have enough disk space in `/home/` for
a (temporary) second copy of your home directory. Make sure to backup your
home directory. Make sure to log out of your user account fully. Then log in
as root on the console.
1. Rename your existing home directory to something safe. Let's say your user
ID is `foobar`. Then do:
```
mv /home/foobar /home/foobar.saved
```
2. Have a look at your existing user record, as stored in `/etc/passwd` and
related files. We want to use the same data for the new record, hence it's good
looking at the old data. Use commands such as:
```
getent passwd foobar
getent shadow foobar
```
This will tell you the `/etc/passwd` and `/etc/shadow` entries for your
user. For details about the fields, see the respective man pages
[passwd(5)](http://man7.org/linux/man-pages/man5/passwd.5.html) and
[shadow(5)](http://man7.org/linux/man-pages/man5/shadow.5.html).
The fourth field in the `getent passwd foobar` output tells you the GID of
your user's main group. Depending on your distribution it's a group private
to the user, or a group shared by most local, regular users. Let's say the
GID reported is 1000, let's then query its details:
```
getent group 1000
```
This will tell you the name of that group. If the name is the same as your
user name your distribution apparently provided you with a private group for
your user. If it doesn't match (and is something like `users`) it apparently
didn't. Note that `systemd-homed` will always manage a private group for
each user under the same name, hence if your distribution is one of the
latter kind, then there's a (minor) mismatch in structure when converting.
Save the information reported by these three commands somewhere, for later
reference.
3. Now edit your `/etc/passwd` file and remove your existing record
(i.e. delete a single line, the one of your user's account, leaving all
other lines unmodified). Similar for `/etc/shadow`, `/etc/group` (in case
you have a private group for your user) and `/etc/gshadow`. Most
distributions provide you with a tool for that, that adds safe
synchronization for these changes: `vipw`, `vipw -s`, `vigr` and `vigr -s`.
4. At this point the old user account vanished, while the home directory still
exists safely under the `/home/foobar.saved` name. Let's now create a new
account with `systemd-homed`, using the same username and UID as before:
```
homectl create foobar --uid=$UID --real-name=$GECOS
```
In this command line, replace `$UID` by the UID you previously used,
i.e. the third field of the `getent passwd foobar` output above. Similar,
replace `$GECOS` by the GECOS field of your old account, i.e the fifth field
of the old output. If your distribution traditionally does not assign a
private group to regular user groups, then consider adding `--member-of=`
with the group name to get a modicum of compatibility with the status quo
ante: this way your new user account will still not have the old primary
group as new primary group, but will have it as auxiliary group.
Consider reading through the
[homectl(1)](https://www.freedesktop.org/software/systemd/man/homectl.html)
manual page at this point, maybe there are a couple of other settings you
want to set for your new account. In particular, look at `--storage=` and
`--disk-size=`, in order to change how your home directory shall be stored
(the default `luks` storage is recommended).
5. Your new user account exists now, but it has an empty home directory. Let's
now migrate your old home directory into it. For that let's mount the new
home directory temporarily and copy the data in.
```
homectl with foobar -- rsync -aHAXv --remove-source-files /home/foobar.saved/ .
```
This mounts the home directory of the user, and then runs the specified
`rsync` command which copies the contents of the old home directory into the
new. The new home directory is the working directory of the invoked `rsync`
process. We are invoking this command as root, hence the `rsync` runs as
root too. When the `rsync` command completes the home directory is
automatically unmounted again. Since we used `--remove-source-files` all files
copied are removed from the old home directory as the copy progresses. After
the command completes the old home directory should be empty. Let's remove
it hence:
```
rmdir /home/foobar.saved
```
And that's it, we are done already. You can log out now and should be able to
log in under your user account as usual, but now with `systemd-homed` managing
your home directory.

117
docs/DESKTOP_ENVIRONMENTS.md Normal file
View File

@ -0,0 +1,117 @@
---
title: Desktop Environment Integration
category: Concepts
layout: default
---
# Desktop Environments
NOTE: This document is a work-in-progress.
## Single Graphical Session
systemd only supports running one graphical session per user at a time.
While this might not have always been the case historically, having multiple
sessions for one user running at the same time is problematic.
The DBus session bus is shared between all the logins, and services that are
started must be implicitly assigned to the user's current graphical session.
In principle it is possible to run a single graphical session across multiple
logind seats, and this could be a way to use more than one display per user.
When a user logs in to a second seat, the seat resources could be assigned
to the existing session, allowing the graphical environment to present it
is a single seat.
Currently nothing like this is supported or even planned.
## Pre-defined systemd units
[`systemd.special(7)`](https://www.freedesktop.org/software/systemd/man/systemd.special.html)
defines the `graphical-session.target` and `graphical-session-pre.target` to
allow cross-desktop integration. Furthermore, systemd defines the three base
slices `background`, `app` and `session`.
All units should be placed into one of these slices depending on their purposes:
* `session.slice`: Contains only processes essential to run the user's graphical session
* `app.slice`: Contains all normal applications that the user is running
* `background.slice`: Useful for low-priority background tasks
The purpose of this grouping is to assign different priorities to the
applications.
This could e.g. mean reserving memory to session processes,
preferentially killing background tasks in out-of-memory situations
or assigning different memory/CPU/IO priorities to ensure that the session
runs smoothly under load.
TODO: Will there be a default to place units into e.g. `app.slice` by default
rather than the root slice?
## XDG standardization for applications
To ensure cross-desktop compatibility and encourage sharing of good practices,
desktop environments should adhere to the following conventions:
* Application units should follow the scheme `app[-<launcher>]-<ApplicationID>[@<RANDOM>].service`
or `app[-<launcher>]-<ApplicationID>-<RANDOM>.scope`
e.g:
- `app-gnome-org.gnome.Evince@12345.service`
- `app-flatpak-org.telegram.desktop@12345.service`
- `app-KDE-org.kde.okular@12345.service`
- `app-org.kde.amarok.service`
- `app-org.gnome.Evince-12345.scope`
* Using `.service` units instead of `.scope` units, i.e. allowing systemd to
start the process on behalf of the caller,
instead of the caller starting the process and letting systemd know about it,
is encouraged.
* The RANDOM should be a string of random characters to ensure that multiple instances
of the application can be launched.
It can be omitted in the case of a non-transient application services which can ensure
multiple instances are not spawned, such as a DBus activated application.
* If no application ID is available, the launcher should generate a reasonable
name when possible (e.g. using `basename(argv[0])`). This name must not
contain a `-` character.
This has the following advantages:
* Using the `app-<launcher>-` prefix means that the unit defaults can be
adjusted using desktop environment specific drop-in files.
* The application ID can be retrieved by stripping the prefix and postfix.
This in turn should map to the corresponding `.desktop` file when available
TODO: Define the name of slices that should be used.
This could be `app-<launcher>-<ApplicationID>-<RANDOM>.slice`.
TODO: Does it really make sense to insert the `<launcher>`? In GNOME I am
currently using a drop-in to configure `BindTo=graphical-session.target`,
`CollectMode=inactive-or-failed` and `TimeoutSec=5s`. I feel that such a
policy makes sense, but it may make much more sense to just define a
global default for all (graphical) applications.
* Should application lifetime be bound to the session?
* May the user have applications that do not belong to the graphical session (e.g. launched from SSH)?
* Could we maybe add a default `app-.service.d` drop-in configuration?
## XDG autostart integration
To allow XDG autostart integration, systemd ships a cross-desktop generator
to create appropriate units for the autostart directory
(`systemd-xdg-autostart-generator`).
Desktop Environments can opt-in to using this by starting
`xdg-desktop-autostart.target`. The systemd generator correctly handles
`OnlyShowIn=` and `NotShowin=`. It also handles the KDE and GNOME specific
`X-KDE-autostart-condition=` and `AutostartCondition=` by using desktop
environment provided binaries in an `ExecCondition=` line.
However, this generator is somewhat limited in what it supports. For example,
all generated units will have `After=graphical-session.target` set on them,
it may therefore not be useful to start session services.
Desktop files can be marked to be explicitly excluded from the generator using the line
`X-systemd-skip=true`. This should be set if an application provides its own
systemd service file for startup.
## Startup and shutdown best practices
Question here are:
* Are there strong opinions on how the session-leader process should watch the user's session units?
* Should systemd/logind/… provide an integrated way to define a session in terms of a running *user* unit?
* Is having `gnome-session-shutdown.target` that is run with `replace-irreversibly` considered a good practice?

2
docs/ENVIRONMENT.md
View File

@ -145,7 +145,7 @@ systemd-udevd:
boot loader menu through EFI a file `/run/systemd/reboot-to-boot-loader-menu`
is created whenever this is requested. The file contains the requested boot
loader menu timeout in µs, formatted in ASCII decimals, or zero in case no
time-out is requested. This file may be checked for by services run during
timeout is requested. This file may be checked for by services run during
system shutdown in order to request the appropriate operation from the boot
loader in an alternative fashion.

2
docs/GROUP_RECORD.md
View File

@ -1,6 +1,6 @@
---
title: JSON Group Records
category: Interfaces
category: Users, Groups and Home Directories
layout: default
---

42
docs/HACKING.md
View File

@ -36,9 +36,12 @@ building clean OS images from an upstream distribution in combination with a
fresh build of the project in the local working directory. To make use of this,
please acquire `mkosi` from https://github.com/systemd/mkosi first, unless your
distribution has packaged it already and you can get it from there. After the
tool is installed it is sufficient to type `mkosi` in the systemd project
directory to generate a disk image `image.raw` you can boot either in
`systemd-nspawn` or in an UEFI-capable VM:
tool is installed, symlink the settings file for your distribution of choice from
.mkosi/ to mkosi.default in the project root directory (note that the package
manager for this distro needs to be installed on your host system). After doing
that, it is sufficient to type `mkosi` in the systemd project directory to
generate a disk image `image.raw` you can boot either in `systemd-nspawn` or in
an UEFI-capable VM:
```
# systemd-nspawn -bi image.raw
@ -72,22 +75,23 @@ Putting this all together, here's a series of commands for preparing a patch
for systemd (this example is for Fedora):
```sh
$ sudo dnf builddep systemd # install build dependencies
$ sudo dnf install mkosi # install tool to quickly build images
$ sudo dnf builddep systemd # install build dependencies
$ sudo dnf install mkosi # install tool to quickly build images
$ git clone https://github.com/systemd/systemd.git
$ cd systemd
$ vim src/core/main.c # or wherever you'd like to make your changes
$ meson build # configure the build
$ ninja -C build # build it locally, see if everything compiles fine
$ ninja -C build test # run some simple regression tests
$ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi
$ sudo mkosi # build a test image
$ sudo systemd-nspawn -bi image.raw # boot up the test image
$ git add -p # interactively put together your patch
$ git commit # commit it
$ vim src/core/main.c # or wherever you'd like to make your changes
$ meson build # configure the build
$ ninja -C build # build it locally, see if everything compiles fine
$ ninja -C build test # run some simple regression tests
$ ln -s .mkosi/mkosi.fedora mkosi.default # Configure mkosi to build a fedora image
$ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi
$ sudo mkosi # build a test image
$ sudo systemd-nspawn -bi image.raw # boot up the test image
$ git add -p # interactively put together your patch
$ git commit # commit it
$ git push REMOTE HEAD:refs/heads/BRANCH
# where REMOTE is your "fork" on GitHub
# and BRANCH is a branch name.
# where REMOTE is your "fork" on GitHub
# and BRANCH is a branch name.
```
And after that, head over to your repo on GitHub and click "Compare & pull request"
@ -98,7 +102,7 @@ Happy hacking!
## Fuzzers
systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically
run by [OSS-Fuzz](https://github.com/google/oss-fuzz) and [Fuzzit](https://fuzzit.dev) with sanitizers.
run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers.
To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput`
function and add it to the list in `src/fuzz/meson.build`.
@ -118,10 +122,6 @@ python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd
python infra/helper.py run_fuzzer systemd fuzz-foo
```
When you add a new target you should also add the target on [Fuzzit](https://app.fuzzit.dev/admin/RxqRpGNXquIvqrmp4iJS/dashboard)
(Please ask someone with permissions). One the target is configured on Fuzzit you need to add it to
`travis-ci/managers/fuzzit.sh` so the new target will run sanity tests on every pull-request and periodic fuzzing jobs.
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.

12
docs/HOME_DIRECTORY.md
View File

@ -1,6 +1,6 @@
---
title: Home Directories
category: Concepts
category: Users, Groups and Home Directories
layout: default
---
@ -125,7 +125,7 @@ medium. (Moreover it allows to embed additional partitions later on, for
example for allowing a multi-purpose USB stick that contains both a home
directory and a generic storage volume.)
Rationale for including the encrypted user record in the the LUKS2 header:
Rationale for including the encrypted user record in the LUKS2 header:
Linux kernel file system implementations are generally not robust towards
maliciously formatted file systems; there's a good chance that file system
images can be used as attack vectors, exploiting the kernel. Thus it is
@ -147,7 +147,7 @@ directory-based storage mechanisms (`directory`, `subvolume` and `fscrypt`)
this is a bind mount, in case of `cifs` this is a CIFS network mount, and in
case of the LUKS2 backend a regular block device mount of the file system
contained in the LUKS2 image. By requiring a mount for all cases (even for
those that already are a directory) a clear logic is defined to distuingish
those that already are a directory) a clear logic is defined to distinguish
active and inactive home directories, so that the directories become
inaccessible under their regular path the instant they are
deactivated. Moreover, the `nosuid`, `nodev` and `noexec` flags configured in
@ -168,6 +168,10 @@ If the UID assigned to a user does not match the owner of the home directory in
the file system, the home directory is automatically and recursively `chown()`ed
to the correct UID.
Depending on the `discard` setting of the user record either the backing
Depending on the `luksDiscard` setting of the user record either the backing
loopback file is `fallocate()`ed during activation, or the mounted file system
is `FITRIM`ed after mounting, to ensure the setting is correctly enforced.
When deactivating a home directory, the file system or block device is trimmed
or extended as configured in the `luksOfflineDiscard` setting of the user
record.

2
docs/INITRD_INTERFACE.md
View File

@ -36,7 +36,7 @@ interfaces are currently used by dracut and the ArchLinux initrds.
optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command
line options, for example `--log-level=` and similar.
* Storage daemons run from the initrd should follow the the guide on [systemd
* Storage daemons run from the initrd should follow the guide on [systemd
and Storage Daemons for the Root File
System](https://systemd.io/ROOT_STORAGE_DAEMONS) to survive properly from the
boot initrd all the way to the point where systemd jumps back into the initrd

694
docs/JOURNAL_FILE_FORMAT.md Normal file
View File

@ -0,0 +1,694 @@
---
title: Journal File Format
category: Interfaces
layout: default
---
# Journal File Format
_Note that this document describes the binary on-disk format of journals
only. For interfacing with web technologies there's the [Journal JSON
Format](http://www.freedesktop.org/wiki/Software/systemd/json). For transfer
of journal data across the network there's the [Journal Export
Format](http://www.freedesktop.org/wiki/Software/systemd/export)._
The systemd journal stores log data in a binary format with several features:
* Fully indexed by all fields
* Can store binary data, up to 2^64-1 in size
* Seekable
* Primarily append-based, hence robust to corruption
* Support for in-line compression
* Support for in-line Forward Secure Sealing
This document explains the basic structure of the file format on disk. We are
making this available primarily to allow review and provide documentation. Note
that the actual implementation in the [systemd
codebase](https://github.com/systemd/systemd/blob/master/src/journal/) is the
only ultimately authoritative description of the format, so if this document
and the code disagree, the code is right. That said we'll of course try hard to
keep this document up-to-date and accurate.
Instead of implementing your own reader or writer for journal files we ask you
to use the [Journal's native C
API](http://www.freedesktop.org/software/systemd/man/sd-journal.html) to access
these files. It provides you with full access to the files, and will not
withhold any data. If you find a limitation, please ping us and we might add
some additional interfaces for you.
If you need access to the raw journal data in serialized stream form without C
API our recommendation is to make use of the [Journal Export
Format](http://www.freedesktop.org/wiki/Software/systemd/export), which you can
get via "journalctl -o export" or via systemd-journal-gatewayd. The export
format is much simpler to parse, but complete and accurate. Due to its
stream-based nature it is not indexed.
_Or, to put this in other words: this low-level document is probably not what
you want to use as base of your project. You want our [C
API](http://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](http://www.freedesktop.org/wiki/Software/systemd/export) instead! This
document is primarily for your entertainment and education. Thank you!_
This document assumes you have a basic understanding of the journal concepts,
the properties of a journal entry and so on. If not, please go and read up,
then come back! This is a good opportunity to read about the [basic properties
of journal
entries](http://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.
This document describes the current format of systemd 246. The documented
format is compatible with the format used in the first versions of the journal,
but received various compatible and incompatible additions since.
If you are wondering why the journal file format has been created in the first
place instead of adopting an existing database implementation, please have a
look [at this
thread](https://lists.freedesktop.org/archives/systemd-devel/2012-October/007054.html).
## Basics
* All offsets, sizes, time values, hashes (and most other numeric values) are 64bit unsigned integers in LE format.
* Offsets are always relative to the beginning of the file.
* The 64bit hash function siphash24 is used for newer journal files. For older files [Jenkins lookup3](https://en.wikipedia.org/wiki/Jenkins_hash_function) is used, more specifically `jenkins_hashlittle2()` with the first 32bit integer it returns as higher 32bit part of the 64bit value, and the second one uses as lower 32bit part.
* All structures are aligned to 64bit boundaries and padded to multiples of 64bit
* The format is designed to be read and written via memory mapping using multiple mapped windows.
* All time values are stored in usec since the respective epoch.
* Wall clock time values are relative to the Unix time epoch, i.e. January 1st, 1970. (`CLOCK_REALTIME`)
* Monotonic time values are always stored jointly with the kernel boot ID value (i.e. `/proc/sys/kernel/random/boot_id`) they belong to. They tend to be relative to the start of the boot, but aren't for containers. (`CLOCK_MONOTONIC`)
* Randomized, unique 128bit IDs are used in various locations. These are generally UUID v4 compatible, but this is not a requirement.
## General Rules
If any kind of corruption is noticed by a writer it should immediately rotate
the file and start a new one. No further writes should be attempted to the
original file, but it should be left around so that as little data as possible
is lost.
If any kind of corruption is noticed by a reader it should try hard to handle
this gracefully, such as skipping over the corrupted data, but allowing access
to as much data around it as possible.
A reader should verify all offsets and other data as it reads it. This includes
checking for alignment and range of offsets in the file, especially before
trying to read it via a memory map.
A reader must interleave rotated and corrupted files as good as possible and
present them as single stream to the user.
All fields marked as "reserved" must be initialized with 0 when writing and be
ignored on reading. They are currently not used but might be used later on.
## Structure
The file format's data structures are declared in
[journal-def.h](https://github.com/systemd/systemd/blob/master/src/journal/journal-def.h).
The file format begins with a header structure. After the header structure
object structures follow. Objects are appended to the end as time
progresses. Most data stored in these objects is not altered anymore after
having been written once, with the exception of records necessary for
indexing. When new data is appended to a file the writer first writes all new
objects to the end of the file, and then links them up at front after that's
done. Currently, seven different object types are known:
```c
enum {
OBJECT_UNUSED,
OBJECT_DATA,
OBJECT_FIELD,
OBJECT_ENTRY,
OBJECT_DATA_HASH_TABLE,
OBJECT_FIELD_HASH_TABLE,
OBJECT_ENTRY_ARRAY,
OBJECT_TAG,
_OBJECT_TYPE_MAX
};
```
* A **DATA** object, which encapsulates the contents of one field of an entry, i.e. a string such as `_SYSTEMD_UNIT=avahi-daemon.service`, or `MESSAGE=Foobar made a booboo.` but possibly including large or binary data, and always prefixed by the field name and "=".
* A **FIELD** object, which encapsulates a field name, i.e. a string such as `_SYSTEMD_UNIT` or `MESSAGE`, without any `=` or even value.
* An **ENTRY** object, which binds several **DATA** objects together into a log entry.
* A **DATA_HASH_TABLE** object, which encapsulates a hash table for finding existing **DATA** objects.
* A **FIELD_HASH_TABLE** object, which encapsulates a hash table for finding existing **FIELD** objects.
* An **ENTRY_ARRAY** object, which encapsulates a sorted array of offsets to entries, used for seeking by binary search.
* A **TAG** object, consisting of an FSS sealing tag for all data from the beginning of the file or the last tag written (whichever is later).
## Header
The Header struct defines, well, you guessed it, the file header:
```c
_packed_ struct Header {
uint8_t signature[8]; /* "LPKSHHRH" */
le32_t compatible_flags;
le32_t incompatible_flags;
uint8_t state;
uint8_t reserved[7];
sd_id128_t file_id;
sd_id128_t machine_id;
sd_id128_t boot_id; /* last writer */
sd_id128_t seqnum_id;
le64_t header_size;
le64_t arena_size;
le64_t data_hash_table_offset;
le64_t data_hash_table_size;
le64_t field_hash_table_offset;
le64_t field_hash_table_size;
le64_t tail_object_offset;
le64_t n_objects;
le64_t n_entries;
le64_t tail_entry_seqnum;
le64_t head_entry_seqnum;
le64_t entry_array_offset;
le64_t head_entry_realtime;
le64_t tail_entry_realtime;
le64_t tail_entry_monotonic;
/* Added in 187 */
le64_t n_data;
le64_t n_fields;
/* Added in 189 */
le64_t n_tags;
le64_t n_entry_arrays;
/* Added in 246 */
le64_t data_hash_chain_depth;
le64_t field_hash_chain_depth;
};
```
The first 8 bytes of Journal files must contain the ASCII characters `LPKSHHRH`.
If a writer finds that the **machine_id** of a file to write to does not match
the machine it is running on it should immediately rotate the file and start a
new one.
When journal file is first created the **file_id** is randomly and uniquely
initialized.
When a writer opens a file it shall initialize the **boot_id** to the current
boot id of the system.
The currently used part of the file is the **header_size** plus the
**arena_size** field of the header. If a writer needs to write to a file where
the actual file size on disk is smaller than the reported value it shall
immediately rotate the file and start a new one. If a writer is asked to write
to a file with a header that is shorter than his own definition of the struct
Header, he shall immediately rotate the file and start a new one.
The **n_objects** field contains a counter for objects currently available in
this file. As objects are appended to the end of the file this counter is
increased.
The first object in the file starts immediately after the header. The last
object in the file is at the offset **tail_object_offset**, which may be 0 if
no object is in the file yet.
The **n_entries**, **n_data**, **n_fields**, **n_tags**, **n_entry_arrays** are
counters of the objects of the specific types.
**tail_entry_seqnum** and **head_entry_seqnum** contain the sequential number
(see below) of the last or first entry in the file, respectively, or 0 if no
entry has been written yet.
**tail_entry_realtime** and **head_entry_realtime** contain the wallclock
timestamp of the last or first entry in the file, respectively, or 0 if no
entry has been written yet.
**tail_entry_monotonic** is the monotonic timestamp of the last entry in the
file, referring to monotonic time of the boot identified by **boot_id**.
**data_hash_chain_depth** is a counter of the deepest chain in the data hash
table, minus one. This is updated whenever a chain is found that is longer than
the previous deepest chain found. Note that the counter is updated during hash
table lookups, as the chains are traversed. This counter is used to determine
when it is a good time to rotate the journal file, because hash collisions
became too frequent.
Similar, **field_hash_chain_depth** is a counter of the deepest chain in the
field hash table, minus one.
## Extensibility
The format is supposed to be extensible in order to enable future additions of
features. Readers should simply skip objects of unknown types as they read
them. If a compatible feature extension is made a new bit is registered in the
header's **compatible_flags** field. If a feature extension is used that makes
the format incompatible a new bit is registered in the header's
**incompatible_flags** field. Readers should check these two bit fields, if
they find a flag they don't understand in compatible_flags they should continue
to read the file, but if they find one in **incompatible_flags** they should
fail, asking for an update of the software. Writers should refuse writing if
there's an unknown bit flag in either of these fields.
The file header may be extended as new features are added. The size of the file
header is stored in the header. All header fields up to **n_data** are known to
unconditionally exist in all revisions of the file format, all fields starting
with **n_data** needs to be explicitly checked for via a size check, since they
were additions after the initial release.
Currently only five extensions flagged in the flags fields are known:
```c
enum {
HEADER_INCOMPATIBLE_COMPRESSED_XZ = 1 << 0,
HEADER_INCOMPATIBLE_COMPRESSED_LZ4 = 1 << 1,
HEADER_INCOMPATIBLE_KEYED_HASH = 1 << 2,
HEADER_INCOMPATIBLE_COMPRESSED_ZSTD = 1 << 3,
};
enum {
HEADER_COMPATIBLE_SEALED = 1 << 0,
};
```
HEADER_INCOMPATIBLE_COMPRESSED_XZ indicates that the file includes DATA objects
that are compressed using XZ. Similarly, HEADER_INCOMPATIBLE_COMPRESSED_LZ4
indicates that the file includes DATA objects that are compressed with the LZ4
algorithm. And HEADER_INCOMPATIBLE_COMPRESSED_ZSTD indicates that there are
objects compressed with ZSTD.
HEADER_INCOMPATIBLE_KEYED_HASH indicates that instead of the unkeyed Jenkins
hash function the keyed siphash24 hash function is used for the two hash
tables, see below.
HEADER_COMPATIBLE_SEALED indicates that the file includes TAG objects required
for Forward Secure Sealing.
## Dirty Detection
```c
enum {
STATE_OFFLINE = 0,
STATE_ONLINE = 1,
STATE_ARCHIVED = 2,
_STATE_MAX
};
```
If a file is opened for writing the **state** field should be set to
STATE_ONLINE. If a file is closed after writing the **state** field should be
set to STATE_OFFLINE. After a file has been rotated it should be set to
STATE_ARCHIVED. If a writer is asked to write to a file that is not in
STATE_OFFLINE it should immediately rotate the file and start a new one,
without changing the file.
After and before the state field is changed `fdatasync()` should be executed on
the file to ensure the dirty state hits disk.
## Sequence Numbers
All entries carry sequence numbers that are monotonically counted up for each
entry (starting at 1) and are unique among all files which carry the same
**seqnum_id** field. This field is randomly generated when the journal daemon
creates its first file. All files generated by the same journal daemon instance
should hence carry the same seqnum_id. This should guarantee a monotonic stream
of sequential numbers for easy interleaving even if entries are distributed
among several files, such as the system journal and many per-user journals.
## Concurrency
The file format is designed to be usable in a simultaneous
single-writer/multiple-reader scenario. The synchronization model is very weak
in order to facilitate storage on the most basic of file systems (well, the
most basic ones that provide us with `mmap()` that is), and allow good
performance. No file locking is used. The only time where disk synchronization
via `fdatasync()` should be enforced is after and before changing the **state**
field in the file header (see below). It is recommended to execute a memory
barrier after appending and initializing new objects at the end of the file,
and before linking them up in the earlier objects.
This weak synchronization model means that it is crucial that readers verify
the structural integrity of the file as they read it and handle invalid
structure gracefully. (Checking what you read is a pretty good idea out of
security considerations anyway.) This specifically includes checking offset
values, and that they point to valid objects, with valid sizes and of the type
and hash value expected. All code must be written with the fact in mind that a
file with inconsistent structure might just be inconsistent temporarily, and
might become consistent later on. Payload OTOH requires less scrutiny, as it
should only be linked up (and hence visible to readers) after it was
successfully written to memory (though not necessarily to disk). On non-local
file systems it is a good idea to verify the payload hashes when reading, in
order to avoid annoyances with `mmap()` inconsistencies.
Clients intending to show a live view of the journal should use `inotify()` for
this to watch for files changes. Since file writes done via `mmap()` do not
result in `inotify()` writers shall truncate the file to its current size after
writing one or more entries, which results in inotify events being
generated. Note that this is not used as a transaction scheme (it doesn't
protect anything), but merely for triggering wakeups.
Note that inotify will not work on network file systems if reader and writer
reside on different hosts. Readers which detect they are run on journal files
on a non-local file system should hence not rely on inotify for live views but
fall back to simple time based polling of the files (maybe recheck every 2s).
## Objects
All objects carry a common header:
```c
enum {
OBJECT_COMPRESSED_XZ = 1 << 0,
OBJECT_COMPRESSED_LZ4 = 1 << 1,
OBJECT_COMPRESSED_ZSTD = 1 << 2,
};
_packed_ struct ObjectHeader {
uint8_t type;
uint8_t flags;
uint8_t reserved[6];
le64_t size;
uint8_t payload[];
};
```
The **type** field is one of the object types listed above. The **flags** field
currently knows three flags: OBJECT_COMPRESSED_XZ, OBJECT_COMPRESSED_LZ4 and
OBJECT_COMPRESSED_ZSTD. It is only valid for DATA objects and indicates that
the data payload is compressed with XZ/LZ4/ZSTD. If one of the
OBJECT_COMPRESSED_* flags is set for an object then the matching
HEADER_INCOMPATIBLE_COMPRESSED_XZ/HEADER_INCOMPATIBLE_COMPRESSED_LZ4/HEADER_INCOMPATIBLE_COMPRESSED_ZSTD
flag must be set for the file as well. At most one of these three bits may be
set. The **size** field encodes the size of the object including all its
headers and payload.
## Data Objects
```c
_packed_ struct DataObject {
ObjectHeader object;
le64_t hash;
le64_t next_hash_offset;
le64_t next_field_offset;
le64_t entry_offset; /* the first array entry we store inline */
le64_t entry_array_offset;
le64_t n_entries;
uint8_t payload[];
};
```
Data objects carry actual field data in the **payload[]** array, including a
field name, a `=` and the field data. Example:
`_SYSTEMD_UNIT=foobar.service`. The **hash** field is a hash value of the
payload. If the `HEADER_INCOMPATIBLE_KEYED_HASH` flag is set in the file header
this is the siphash24 hash value of the payload, keyed by the file ID as stored
in the **file_id** field of the file header. If the flag is not set it is the
non-keyed Jenkins hash of the payload instead. The keyed hash is preferred as
it makes the format more robust against attackers that want to trigger hash
collisions in the hash table.
**next_hash_offset** is used to link up DATA objects in the DATA_HASH_TABLE if
a hash collision happens (in a singly linked list, with an offset of 0
indicating the end). **next_field_offset** is used to link up data objects with
the same field name from the FIELD object of the field used.
**entry_offset** is an offset to the first ENTRY object referring to this DATA
object. **entry_array_offset** is an offset to an ENTRY_ARRAY object with
offsets to other entries referencing this DATA object. Storing the offset to
the first ENTRY object in-line is an optimization given that many DATA objects
will be referenced from a single entry only (for example, `MESSAGE=` frequently
includes a practically unique string). **n_entries** is a counter of the total
number of ENTRY objects that reference this object, i.e. the sum of all
ENTRY_ARRAYS chained up from this object, plus 1.
The **payload[]** field contains the field name and date unencoded, unless
OBJECT_COMPRESSED_XZ/OBJECT_COMPRESSED_LZ4/OBJECT_COMPRESSED_ZSTD is set in the
`ObjectHeader`, in which case the payload is compressed with the indicated
compression algorithm.
## Field Objects
```c
_packed_ struct FieldObject {
ObjectHeader object;
le64_t hash;
le64_t next_hash_offset;
le64_t head_data_offset;
uint8_t payload[];
};
```
Field objects are used to enumerate all possible values a certain field name
can take in the entire journal file.
The **payload[]** array contains the actual field name, without '=' or any
field value. Example: `_SYSTEMD_UNIT`. The **hash** field is a hash value of
the payload. As for the DATA objects, this too is either the `.file_id` keyed
siphash24 hash of the payload, or the non-keyed Jenkins hash.
**next_hash_offset** is used to link up FIELD objects in the FIELD_HASH_TABLE
if a hash collision happens (in singly linked list, offset 0 indicating the
end). **head_data_offset** points to the first DATA object that shares this
field name. It is the head of a singly linked list using DATA's
**next_field_offset** offset.
## Entry Objects
```
_packed_ struct EntryItem {
le64_t object_offset;
le64_t hash;
};
_packed_ struct EntryObject {
ObjectHeader object;
le64_t seqnum;
le64_t realtime;
le64_t monotonic;
sd_id128_t boot_id;
le64_t xor_hash;
EntryItem items[];
};
```
An ENTRY object binds several DATA objects together into one log entry, and
includes other metadata such as various timestamps.
The **seqnum** field contains the sequence number of the entry, **realtime**
the realtime timestamp, and **monotonic** the monotonic timestamp for the boot
identified by **boot_id**.
The **xor_hash** field contains a binary XOR of the hashes of the payload of
all DATA objects referenced by this ENTRY. This value is usable to check the
contents of the entry, being independent of the order of the DATA objects in
the array. Note that even for files that have the
`HEADER_INCOMPATIBLE_KEYED_HASH` flag set (and thus siphash24 the otherwise
used hash function) the hash function used for this field, as singular
exception, is the Jenkins lookup3 hash function. The XOR hash value is used to
quickly compare the contents of two entries, and to define a well-defined order
between two entries that otherwise have the same sequence numbers and
timestamps.
The **items[]** array contains references to all DATA objects of this entry,
plus their respective hashes (which are calculated the same way as in the DATA
objects, i.e. keyed by the file ID).
In the file ENTRY objects are written ordered monotonically by sequence
number. For continuous parts of the file written during the same boot
(i.e. with the same boot_id) the monotonic timestamp is monotonic too. Modulo
wallclock time jumps (due to incorrect clocks being corrected) the realtime
timestamps are monotonic too.
## Hash Table Objects
```c
_packed_ struct HashItem {
le64_t head_hash_offset;
le64_t tail_hash_offset;
};
_packed_ struct HashTableObject {
ObjectHeader object;
HashItem items[];
};
```
The structure of both DATA_HASH_TABLE and FIELD_HASH_TABLE objects are
identical. They implement a simple hash table, which each cell containing
offsets to the head and tail of the singly linked list of the DATA and FIELD
objects, respectively. DATA's and FIELD's next_hash_offset field are used to
chain up the objects. Empty cells have both offsets set to 0.
Each file contains exactly one DATA_HASH_TABLE and one FIELD_HASH_TABLE
objects. Their payload is directly referred to by the file header in the
**data_hash_table_offset**, **data_hash_table_size**,
**field_hash_table_offset**, **field_hash_table_size** fields. These offsets do
_not_ point to the object headers but directly to the payloads. When a new
journal file is created the two hash table objects need to be created right
away as first two objects in the stream.
If the hash table fill level is increasing over a certain fill level (Learning
from Java's Hashtable for example: > 75%), the writer should rotate the file
and create a new one.
The DATA_HASH_TABLE should be sized taking into account to the maximum size the
file is expected to grow, as configured by the administrator or disk space
considerations. The FIELD_HASH_TABLE should be sized to a fixed size; the
number of fields should be pretty static as it depends only on developers'
creativity rather than runtime parameters.
## Entry Array Objects
```c
_packed_ struct EntryArrayObject {
ObjectHeader object;
le64_t next_entry_array_offset;
le64_t items[];
};
```
Entry Arrays are used to store a sorted array of offsets to entries. Entry
arrays are strictly sorted by offsets on disk, and hence by their timestamps
and sequence numbers (with some restrictions, see above).
Entry Arrays are chained up. If one entry array is full another one is
allocated and the **next_entry_array_offset** field of the old one pointed to
it. An Entry Array with **next_entry_array_offset** set to 0 is the last in the
list. To optimize allocation and seeking, as entry arrays are appended to a
chain of entry arrays they should increase in size (double).
Due to being monotonically ordered entry arrays may be searched with a binary
search (bisection).
One chain of entry arrays links up all entries written to the journal. The
first entry array is referenced in the **entry_array_offset** field of the
header.
Each DATA object also references an entry array chain listing all entries
referencing a specific DATA object. Since many DATA objects are only referenced
by a single ENTRY the first offset of the list is stored inside the DATA object
itself, an ENTRY_ARRAY object is only needed if it is referenced by more than
one ENTRY.
## Tag Object
```c
#define TAG_LENGTH (256/8)
_packed_ struct TagObject {
ObjectHeader object;
le64_t seqnum;
le64_t epoch;
uint8_t tag[TAG_LENGTH]; /* SHA-256 HMAC */
};
```
Tag objects are used to seal off the journal for alteration. In regular
intervals a tag object is appended to the file. The tag object consists of a
SHA-256 HMAC tag that is calculated from the objects stored in the file since
the last tag was written, or from the beginning if no tag was written yet. The
key for the HMAC is calculated via the externally maintained FSPRG logic for
the epoch that is written into **epoch**. The sequence number **seqnum** is
increased with each tag. When calculating the HMAC of objects header fields
that are volatile are excluded (skipped). More specifically all fields that
might validly be altered to maintain a consistent file structure (such as
offsets to objects added later for the purpose of linked lists and suchlike)
after an object has been written are not protected by the tag. This means a
verifier has to independently check these fields for consistency of
structure. For the fields excluded from the HMAC please consult the source code
directly. A verifier should read the file from the beginning to the end, always
calculating the HMAC for the objects it reads. Each time a tag object is
encountered the HMAC should be verified and restarted. The tag object sequence
numbers need to increase strictly monotonically. Tag objects themselves are
partially protected by the HMAC (i.e. seqnum and epoch is included, the tag
itself not).
## Algorithms
### Reading
Given an offset to an entry all data fields are easily found by following the
offsets in the data item array of the entry.
Listing entries without filter is done by traversing the list of entry arrays
starting with the headers' **entry_array_offset** field.
Seeking to an entry by timestamp or sequence number (without any matches) is
done via binary search in the entry arrays starting with the header's
**entry_array_offset** field. Since these arrays double in size as more are
added the time cost of seeking is O(log(n)*log(n)) if n is the number of
entries in the file.
When seeking or listing with one field match applied the DATA object of the
match is first identified, and then its data entry array chain traversed. The
time cost is the same as for seeks/listings with no match.
If multiple matches are applied, multiple chains of entry arrays should be
traversed in parallel. Since they all are strictly monotonically ordered by
offset of the entries, advancing in one can be directly applied to the others,
until an entry matching all matches is found. In the worst case seeking like
this is O(n) where n is the number of matching entries of the "loosest" match,
but in the common case should be much more efficient at least for the
well-known fields, where the set of possible field values tend to be closely
related. Checking whether an entry matches a number of matches is efficient
since the item array of the entry contains hashes of all data fields
referenced, and the number of data fields of an entry is generally small (<
30).
When interleaving multiple journal files seeking tends to be a frequently used
operation, but in this case can be effectively suppressed by caching results
from previous entries.
When listing all possible values a certain field can take it is sufficient to
look up the FIELD object and follow the chain of links to all DATA it includes.
### Writing
When an entry is appended to the journal for each of its data fields the data
hash table should be checked. If the data field does not yet exist in the file
it should be appended and added to the data hash table. When a field data
object is added the field hash table should be checked for the field name of
the data field, and a field object be added if necessary. After all data fields
(and recursively all field names) of the new entry are appended and linked up
in the hashtables the entry object should be appended and linked up too.
In regular intervals a tag object should be written if sealing is enabled (see
above). Before the file is closed a tag should be written too, to seal it off.
Before writing an object, time and disk space limits should be checked and
rotation triggered if necessary.
## Optimizing Disk IO
_A few general ideas to keep in mind:_
The hash tables for looking up fields and data should be quickly in the memory
cache and not hurt performance. All entries and entry arrays are ordered
strictly by time on disk, and hence should expose an OK access pattern on
rotating media, when read sequentially (which should be the most common case,
given the nature of log data).
The disk access patterns of the binary search for entries needed for seeking
are problematic on rotating disks. This should not be a major issue though,
since seeking should not be a frequent operation.
When reading, collecting data fields for presenting entries to the user is
problematic on rotating disks. In order to optimize these patterns the item
array of entry objects should be sorted by disk offset before
writing. Effectively, frequently used data objects should be in the memory
cache quickly. Non-frequently used data objects are likely to be located
between the previous and current entry when reading and hence should expose an
OK access pattern. Problematic are data objects that are neither frequently nor
infrequently referenced, which will cost seek time.
And that's all there is to it.
Thanks for your interest!

40
docs/PASSWORD_AGENTS.md Normal file
View File

@ -0,0 +1,40 @@
---
title: Password Agents
category: Interfaces
layout: default
---
# Password Agents
systemd 12 and newer support lightweight password agents which can be used to query the user for system-level passwords or passphrases. These are passphrases that are not related to a specific user, but to some kind of hardware or service. Right now this is used exclusively for encrypted hard-disk passphrases but later on this is likely to be used to query passphrases of SSL certificates at Apache startup time as well. The basic idea is that a system component requesting a password entry can simply drop a simple .ini-style file into `/run/systemd/ask-password` which multiple different agents may watch via `inotify()`, and query the user as necessary. The answer is then sent back to the querier via an `AF_UNIX`/`SOCK_DGRAM` socket. Multiple agents might be running at the same time in which case they all should query the user and the agent which answers first wins. Right now systemd ships with the following passphrase agents:
* A Plymouth agent used for querying passwords during boot-up
* A console agent used in similar situations if Plymouth is not available
* A GNOME agent which can be run as part of the normal user session which pops up a notification message and icon which when clicked receives the passphrase from the user. This is useful and necessary in case an encrypted system hard-disk is plugged in when the machine is already up.
* A [`wall(1)`](http://man7.org/linux/man-pages/man1/wall.1.html) agent which sends wall messages as soon as a password shall be entered.
* A simple tty agent which is built into "`systemctl start`" (and similar commands) and asks passwords to the user during manual startup of a service
* A simple tty agent which can be run manually to respond to all queued passwords
It is easy to write additional agents. The basic algorithm to follow looks like this:
* Create an inotify watch on /run/systemd/ask-password, watch for `IN_CLOSE_WRITE|IN_MOVED_TO`
* Ignore all events on files in that directory that do not start with "`ask.`"
* As soon as a file named "`ask.xxxx`" shows up, read it. It's a simple `.ini` file that may be parsed with the usual parsers. The `xxxx` suffix is randomized.
* Make sure to ignore unknown `.ini` file keys in those files, so that we can easily extend the format later on.
* You'll find the question to ask the user in the `Message=` field in the `[Ask]` section. It is a single-line string in UTF-8, which might be internationalized (by the party that originally asks the question, not by the agent).
* You'll find an icon name (following the XDG icon naming spec) to show next to the message in the `Icon=` field in the `[Ask]` section
* You'll find the PID of the client asking the question in the `PID=` field in the `[Ask]` section (Before asking your question use `kill(PID, 0)` and ignore the file if this returns `ESRCH`; there's no need to show the data of this field but if you want to you may)
* `Echo=` specifies whether the input should be obscured. If this field is missing or is `Echo=0`, the input should not be shown.
* The socket to send the response to is configured via `Socket=` in the `[Ask]` section. It is a `AF_UNIX`/`SOCK_DGRAM` socket in the file system.
* Ignore files where the time specified in the `NotAfter=` field in the `[Ask]` section is in the past. The time is specified in usecs, and refers to the `CLOCK_MONOTONIC` clock. If `NotAfter=` is `0`, no such check should take place.
* Make sure to hide a password query dialog as soon as a) the `ask.xxxx` file is deleted, watch this with inotify. b) the `NotAfter=` time elapses, if it is set `!= 0`.
* Access to the socket is restricted to privileged users. To acquire the necessary privileges to send the answer back, consider using PolicyKit. In fact, the GNOME agent we ship does that, and you may simply piggyback on that, by executing "`/usr/bin/pkexec /lib/systemd/systemd-reply-password 1 /path/to/socket`" or "`/usr/bin/pkexec /lib/systemd/systemd-reply-password 0 /path/to/socket`" and writing the password to its standard input. Use '`1`' as argument if a password was entered by the user, or '`0`' if the user canceled the request.
* If you do not want to use PK ensure to acquire the necessary privileges in some other way and send a single datagram to the socket consisting of the password string either prefixed with "`+`" or with "`-`" depending on whether the password entry was successful or not. You may but don't have to include a final `NUL` byte in your message.
Again, it is essential that you stop showing the password box/notification/status icon if the `ask.xxx` file is removed or when `NotAfter=` elapses (if it is set `!= 0`)!
It may happen that multiple password entries are pending at the same time. Your agent needs to be able to deal with that. Depending on your environment you may either choose to show all outstanding passwords at the same time or instead only one and as soon as the user replied to that one go on to the next one.
You may test this all with manually invoking the "`systemd-ask-password`" tool on the command line. Pass `--no-tty` to ensure the password is asked via the agent system. Note that only privileged users may use this tool (after all this is intended purely for system-level passwords).
If you write a system level agent a smart way to activate it is using systemd `.path` units. This will ensure that systemd will watch the `/run/systemd/ask-password` directory and spawn the agent as soon as that directory becomes non-empty. In fact, the console, wall and Plymouth agents are started like this. If systemd is used to maintain user sessions as well you can use a similar scheme to automatically spawn your user password agent as well. (As of this moment we have not switched any DE over to use systemd for session management, however.)

4
docs/PORTABILITY_AND_STABILITY.md
View File

@ -87,7 +87,7 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy
| [Boot Loader interface](https://systemd.io/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no |
| [Service bus API](https://www.freedesktop.org/wiki/Software/systemd/dbus) | D-Bus | yes | yes | system-config-services | no | - | no |
| [logind](https://www.freedesktop.org/wiki/Software/systemd/logind) | D-Bus | yes | yes | GNOME | no | - | no |
| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, PolicyKit, ... | no | - | no |
| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, polkit, ... | no | - | no |
| [sd-daemon.h API](https://www.freedesktop.org/software/systemd/man/sd-daemon.html) | C Library or Drop-in | yes | yes | numerous | yes | - | yes |
| [sd-id128.h API](https://www.freedesktop.org/software/systemd/man/sd-id128.html) | C Library | yes | yes | - | yes | - | no |
| [sd-journal.h API](https://www.freedesktop.org/software/systemd/man/sd-journal.html) | C Library | yes | yes | - | maybe | - | no |
@ -98,7 +98,7 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy
| [Unit file format](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) | File format | yes | yes | numerous | no | - | no |
| [Network](https://www.freedesktop.org/software/systemd/man/systemd.network.html) & [Netdev file format](https://www.freedesktop.org/software/systemd/man/systemd.netdev.html) | File format | yes | yes | no | no | - | no |
| [Link file format](https://www.freedesktop.org/software/systemd/man/systemd.link.html) | File format | yes | yes | no | no | - | no |
| [Journal File Format](https://www.freedesktop.org/wiki/Software/systemd/journal-files) | File format | yes | yes | - | maybe | - | no |
| [Journal File Format](https://systemd.io/JOURNAL_FILE_FORMAT) | File format | yes | yes | - | maybe | - | no |
| [Journal Export Format](https://www.freedesktop.org/wiki/Software/systemd/export) | File format | yes | yes | - | yes | - | no |
| [Cooperation in cgroup tree](https://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups) | Treaty | yes | yes | libvirt | yes | libvirt | no |
| [Password Agents](https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents) | Socket+Files | yes | yes | - | yes | - | no |

33
docs/RANDOM_SEEDS.md
View File

@ -118,7 +118,7 @@ requires random numbers as well, including for the following uses:
* systemd maintains various hash tables internally. In order to harden them
against [collision
attacks](https://rt.perl.org/Public/Bug/Display.html?CSRF_Token=165691af9ddaa95f653402f1b68de728)
attacks](https://www.cs.auckland.ac.nz/~mcw/Teaching/refs/misc/denial-of-service.pdf)
they are seeded with random numbers.
* At various places systemd needs random bytes for temporary file name
@ -212,10 +212,10 @@ boot, in order to ensure the entropy pool is filled up quickly.
random-seed`](https://www.freedesktop.org/software/systemd/man/bootctl.html#random-seed))
a seed file with an initial seed is placed in a file `/loader/random-seed`
in the ESP. In addition, an identically sized randomized EFI variable called
the the 'system token' is set, which is written to the machine's firmware
NVRAM. During boot, when `systemd-boot` finds both the random seed file and
the system token they are combined and hashed with SHA256 (in counter mode,
to generate sufficient data), to generate a new random seed file to store in
the 'system token' is set, which is written to the machine's firmware NVRAM.
During boot, when `systemd-boot` finds both the random seed file and the
system token they are combined and hashed with SHA256 (in counter mode, to
generate sufficient data), to generate a new random seed file to store in
the ESP as well as a random seed to pass to the OS kernel. The new random
seed file for the ESP is then written to the ESP, ensuring this is completed
before the OS is invoked. Very early during initialization PID 1 will read
@ -257,7 +257,16 @@ boot, in order to ensure the entropy pool is filled up quickly.
file. If done, `systemd-boot` will use the random seed file even if no
system token is found in EFI variables.
With the three mechanisms described above it should be possible to provide
4. A kernel command line option `systemd.random_seed=` may be used to pass in a
base64 encoded seed to initialize the kernel's entropy pool from during
early service manager initialization. This option is only safe in testing
environments, as the random seed passed this way is accessible to
unprivileged programs via `/proc/cmdline`. Using this option outside of
testing environments is a security problem since cryptographic key material
derived from the entropy pool initialized with a seed accessible to
unprivileged programs should not be considered secret.
With the four mechanisms described above it should be possible to provide
early-boot entropy in most cases. Specifically:
1. On EFI systems, `systemd-boot`'s random seed logic should make sure good
@ -267,7 +276,8 @@ early-boot entropy in most cases. Specifically:
2. On virtualized systems, the early `virtio-rng` hookup should ensure entropy
is available early on — as long as the VM environment provides virtualized
RNG devices, which they really should all do in 2019. Complain to your
hosting provider if they don't.
hosting provider if they don't. For VMs used in testing environments,
`systemd.random_seed=` may be used as an alternative to a virtualized RNG.
3. On Intel/AMD systems systemd's own reliance on the kernel entropy pool is
minimal (as RDRAND is used on those for UUID generation). This only works if
@ -286,8 +296,9 @@ This primarily leaves two kind of systems in the cold:
boot. Alternatively, consider implementing a solution similar to
systemd-boot's random seed concept in your platform's boot loader.
2. Virtualized environments that lack both virtio-rng and RDRAND. Tough
luck. Talk to your hosting provider, and ask them to fix this.
2. Virtualized environments that lack both virtio-rng and RDRAND, outside of
test environments. Tough luck. Talk to your hosting provider, and ask them
to fix this.
3. Also note: if you deploy an image without any random seed and/or without
installing any 'system token' in an EFI variable, as described above, this
@ -410,6 +421,10 @@ This primarily leaves two kind of systems in the cold:
information to possibly gain too much information about the current state
of the kernel's entropy pool.
That said, we actually do implement this with the `systemd.random_seed=`
kernel command line option. Don't use this outside of testing environments,
however, for the aforementioned reasons.
12. *Why doesn't `systemd-boot` rewrite the 'system token' too each time
when updating the random seed file stored in the ESP?*

6
docs/SECURITY.md
View File

@ -6,4 +6,8 @@ layout: default
# Reporting of Security Vulnerabilities
If you discover a security vulnerability, we'd appreciate a non-public disclosure. The [issue tracker](https://github.com/systemd/systemd/issues) and [systemd-devel mailing list](https://lists.freedesktop.org/mailman/listinfo/systemd-devel) are fully public. If you need to reach systemd developers in a non-public way, report the issue to the [systemd-security@redhat.com](mailto:systemd-security@redhat.com) mailing list. The disclosure will be coordinated with distributions.
If you discover a security vulnerability, we'd appreciate a non-public disclosure. systemd developers can be contacted privately on the **[systemd-security@redhat.com](mailto:systemd-security@redhat.com) mailing list**. The disclosure will be coordinated with distributions.
(The [issue tracker](https://github.com/systemd/systemd/issues) and [systemd-devel mailing list](https://lists.freedesktop.org/mailman/listinfo/systemd-devel) are fully public.)
Subscription to the systemd-security mailing list is open to **regular systemd contributors and people working in the security teams of various distributions**. Those conditions should be backed by publicly accessible information (ideally, a track of posts and commits from the mail address in question). If you fall into one of those categories and wish to be subscribed, submit a **[subscription request](https://www.redhat.com/mailman/listinfo/systemd-security)**.

48
docs/TRANSIENT-SETTINGS.md
View File

@ -114,6 +114,7 @@ All execution-related settings are available for transient units.
✓ SupplementaryGroups=
✓ Nice=
✓ OOMScoreAdjust=
✓ CoredumpFilter=
✓ IOSchedulingClass=
✓ IOSchedulingPriority=
✓ CPUSchedulingPolicy=
@ -158,6 +159,9 @@ All execution-related settings are available for transient units.
✓ RestrictRealtime=
✓ RestrictSUIDSGID=
✓ RestrictAddressFamilies=
✓ RootHash=
✓ RootHashSignature=
✓ RootVerity=
✓ LockPersonality=
✓ LimitCPU=
✓ LimitFSIZE=
@ -284,37 +288,39 @@ All process killing settings are available for transient units:
Most service unit settings are available for transient units.
```
✓ PIDFile=
✓ BusName=
✓ ExecCondition=
✓ ExecStartPre=
✓ ExecReload=
✓ ExecStart=
✓ ExecStartPost=
✓ ExecReload=
✓ ExecStartPre=
✓ ExecStop=
✓ ExecStopPost=
✓ FileDescriptorStoreMax=
✓ GuessMainPID=
✓ NonBlocking=
✓ NotifyAccess=
✓ OOMPolicy=
✓ PIDFile=
✓ RemainAfterExit=
✓ Restart=
✓ RestartForceExitStatus=
✓ RestartPreventExitStatus=
✓ RestartSec=
✓ TimeoutStartSec=
✓ TimeoutStopSec=
✓ RootDirectoryStartOnly=
✓ RuntimeMaxSec=
Sockets=
✓ SuccessExitStatus=
✓ TimeoutAbortSec=
✓ TimeoutSec=
✓ RuntimeMaxSec=
✓ WatchdogSec=
✓ TimeoutStartFailureMode=
✓ TimeoutStartSec=
✓ TimeoutStopFailureMode=
✓ TimeoutStopSec=
✓ Type=
✓ Restart=
✓ RootDirectoryStartOnly=
✓ RemainAfterExit=
✓ GuessMainPID=
✓ RestartPreventExitStatus=
✓ RestartForceExitStatus=
✓ SuccessExitStatus=
✓ NonBlocking=
✓ BusName=
✓ FileDescriptorStoreMax=
✓ NotifyAccess=
Sockets=
✓ USBFunctionDescriptors=
✓ USBFunctionStrings=
✓ OOMPolicy=
✓ WatchdogSec=
```
## Mount Unit Settings
@ -331,6 +337,7 @@ All mount unit settings are available to transient units:
✓ SloppyOptions=
✓ LazyUnmount=
✓ ForceUnmount=
✓ ReadWriteOnly=
```
## Automount Unit Settings
@ -427,6 +434,7 @@ Most socket unit settings are available to transient units.
✓ Broadcast=
✓ PassCredentials=
✓ PassSecurity=
✓ PassPacketInfo=
✓ TCPCongestion=
✓ ReusePort=
✓ MessageQueueMaxMessages=

8
docs/UIDS-GIDS.md
View File

@ -1,6 +1,6 @@
---
title: Users, Groups, UIDs and GIDs on systemd Systems
category: Concepts
category: Users, Groups and Home Directories
layout: default
---
@ -132,7 +132,7 @@ but downstreams are strongly advised against doing that.)
range is above the 16bit boundary. Moreover it's below the 31bit boundary,
as some broken code (specifically: the kernel's `devpts` file system)
erroneously considers UIDs signed integers, and hence can't deal with values
above 2^31. The `nss-mymachines` glibc NSS module will synthesize user
above 2^31. The `systemd-machined.service` service will synthesize user
database records for all UIDs assigned to a running container from this
range.
@ -240,14 +240,14 @@ the artifacts the container manager persistently leaves in the system.
| 5 | `tty` group | `systemd` | `/etc/passwd` |
| 6…999 | System users | Distributions | `/etc/passwd` |
| 1000…60000 | Regular users | Distributions | `/etc/passwd` + LDAP/NIS/… |
| 60001…60513 | Human Users (homed) | `systemd` | `nss-systemd`
| 60001…60513 | Human Users (homed) | `systemd` | `nss-systemd` |
| 60514…61183 | Unused | | |
| 61184…65519 | Dynamic service users | `systemd` | `nss-systemd` |
| 65520…65533 | Unused | | |
| 65534 | `nobody` user | Linux | `/etc/passwd` + `nss-systemd` |
| 65535 | 16bit `(uid_t) -1` | Linux | |
| 65536…524287 | Unused | | |
| 524288…1879048191 | Container UID ranges | `systemd` | `nss-mymachines` |
| 524288…1879048191 | Container UID ranges | `systemd` | `nss-systemd` |
| 1879048192…2147483647 | Unused | | |
| 2147483648…4294967294 | HIC SVNT LEONES | | |
| 4294967295 | 32bit `(uid_t) -1` | Linux | |

169
docs/USERDB_AND_DESKTOPS.md Normal file
View File

@ -0,0 +1,169 @@
---
title: systemd-homed and JSON User/Group Record Support in Desktop Environments
category: Users, Groups and Home Directories
layout: default
---
# `systemd-homed` and JSON User/Group Record Support in Desktop Environments
Starting with version 245, systemd supports a new subsystem
[`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html)
for managing regular ("human") users and their home directories. Along with it
a new concept `userdb` got merged that brings rich, extensible JSON user/group
records, extending the classic UNIX/glibc NSS `struct passwd`/`struct group`
structures. Both additions are added in a fully backwards compatible way,
accessible through `getpwnam()`/`getgrnam()`/… (i.e. libc NSS) and PAM as
usual, meaning that for basic support no changes in the upper layers of the
stack (in particular desktop environments, such as GNOME or KDE) have to be
made. However, for better support a number of changes to desktop environments
are recommended. A few areas where that applies are discussed below.
Before reading on, please read up on the basic concepts, specifically:
* [Home Directories](https://systemd.io/HOME_DIRECTORY)
* [JSON User Records](https://systemd.io/USER_RECORD)
* [JSON Group Records](https://systemd.io/GROUP_RECORD)
* [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API)
## Support for Suspending Home Directory Access during System Suspend
One key feature of `systemd-homed` managed encrypted home directories is the
ability that access to them can be suspended automatically during system sleep,
removing any cryptographic key material from memory while doing so. This is
important in a world where most laptop users seldom shut down their computers
but most of the time just suspend them instead. Previously, the encryption keys
for the home directories remained in memory during system suspend, so that
sufficiently equipped attackers could read them from there and gain full access
to the device. By removing the key material from memory before suspend, and
re-requesting it on resume this attack vector can be closed down effectively.
Supporting this mechanism requires support in the desktop environment, since
the encryption keys (i.e. the user's login password) need to be reacquired on
system resume, from a lock screen or similar. This lock screen must run in
system context, and cannot run in the user's own context, since otherwise it
might end up accessing the home directory of the user even though access to it
is temporarily suspended and thus will hang if attempted.
It is suggested that desktop environments that implement lock screens run them
from system context, for example by switching back to the display manager, and
only revert back to the session after re-authentication via this system lock
screen (re-authentication in this case refers to passing the user's login
credentials to the usual PAM authentication hooks). Or in other words, when
going into system suspend it is recommended that GNOME Shell switches back to
the GNOME Display Manager login screen which now should double as screen lock,
and only switches back to the shell's UI after the user re-authenticated there.
Note that this change in behavior is a good idea in any case, and does not
create any dependencies on `systemd-homed` or systemd-specific APIs. It's
simply a change of behavior regarding use of existing APIs, not a suggested
hook-up to a any new API.
A display manager which supports this kind of out-of-context screen lock
operation needs to inform systemd-homed about this so that systemd-homed knows
that it is safe to suspend the user's home directory on suspend. This is done
via the `suspend=` argument to the
[`pam_systemd_home`](https://www.freedesktop.org/software/systemd/man/pam_systemd_home.html)
PAM module. A display manager should hence change its PAM stack configuration
to set this parameter to on. `systemd-homed` will not suspend home directories
if there's at least one active session of the user that does not support
suspending, as communicated via this parameter.
## User Management UIs
The rich user/group records `userdb` and `systemd-homed` support carry various
fields of relevance to UIs that manage the local user database or parts
thereof. In particular, most of the metadata `accounts-daemon` (also see below)
supports is directly available in these JSON records. Hence it makes sense for
any user management UI to expose them directly.
`systemd-homed` exposes APIs to add, remove and make changes to local users via
D-Bus, with full [polkit](https://www.freedesktop.org/software/polkit/docs/latest/)
hook-up. On the command line this is exposed via the
`homectl` command. A graphical UI that exposes similar functionality would be
very useful, exposing the various new account settings, and in particular
providing a stream-lined UI for enrolling new-style authentication tokens such
as PKCS#11/YubiKey-style devices. (Ideally, if the user plugs in an
uninitialized YubiKey during operation it might be nice if the Desktop would
automatically ask if a key pair shall be written to it and the local account be
bound to it, `systemd-homed` provides enough YubiKey/PKCS#11 support to make
this a reality today; except that it will not take care of token
initialization).
A strong point of `systemd-homed` is per-user resource management. In
particular disk space assignments are something that most likely should be
exposed in a user management UI. Various metadata fields are supplied allowing
exposure of disk space assignment "slider" UI. Note however that the file system
back-ends of `systemd-homed.service` have different feature sets. Specifically,
only btrfs has online file system shrinking support, ext4 only offline file
system shrinking support, and xfs no shrinking support at all (all three file
systems support online file system growing however). This means if the LUKS
back-end is used, disk space assignment cannot be instant for logged in users,
unless btrfs is used.
Note that only `systemd-homed` provides an API for modifying/creating/deleting
users. The generic `userdb` subsystem (which might have other back-ends, besides
`systemd-homed`, for example LDAP or Windows) exclusively provides a read-only
interface. (This is unlikely to change, as the other back-ends might have very
different concepts of adding or modifying users, i.e. might not even have any
local concept for that at all). This means any user management UI that intends
to change (and not just view) user accounts should talk directly to
`systemd-homed` to make use of its features; there's no abstraction available
to support other back-ends under the same API.
Unfortunately there's currently no documentation for the `systemd-homed` D-Bus
API. Consider using the `homectl` sources as guidelines for implementing a user
management UI. The JSON user/records are well documented however, see above,
and the D-Bus API provides limited introspection.
## Relationship to `accounts-daemon`
For a long time `accounts-daemon` has been included in Linux distributions
providing richer user accounts. The functionality of this daemon overlaps in
many areas with the functionality of `systemd-homed` or `userdb`, but there are
systematic differences, which means that `systemd-homed` cannot replace
`accounts-daemon` fully. Most importantly: `accounts-daemon` provides
"side-car" metadata for *any* type of user account, while `systemd-homed` only
provides additional metadata for the users it defines itself. In other words:
`accounts-daemon` will augment foreign accounts; `systemd-homed` cannot be used
to augment users defined elsewhere, for example in LDAP or as classic
`/etc/passwd` records.
This probably means that for the time being, a user management UI (or other UI)
that wants to support rich user records with compatibility with the status quo
ante should probably talk to both `systemd-homed` and `accounts-daemon` at the
same time, and ignore `accounts-daemon`'s records if `systemd-homed` defines
them. While I (Lennart) personally believe in the long run `systemd-homed` is
the way to go for rich user records, any UI that wants to manage and support
rich records for classic records has to support `accounts-daemon` in parallel
for the time being.
In the short term, it might make sense to also expose the `userdb` provided
records via `accounts-daemon`, so that clients of the latter can consume them
without changes. However, I think in the long run `accounts-daemon` should
probably be removed from the general stack, hence this sounds like a temporary
solution only.
In case you wonder, there's no automatic mechanism for converting existing
users registered in `/etc/passwd` or LDAP to users managed by
`systemd-homed`. There's documentation for doing this manually though, see
[Converting Existing Users to systemd-homed managed
Users](https://systemd.io/CONVERTING_TO_HOMED).
## Future Additions
JSON user/group records are extensible, hence we can easily add any additional
fields desktop environments require. For example pattern-based authentication
is likely very useful on touch-based devices, and the user records should hence
learn them natively. Fields for other authentication mechanisms, such as
fingerprint authentication should be provided as well, eventually.
It is planned to extend the `userdb` Varlink API to support look-ups by partial
user name and real name (GECOS) data, so that log-in screens can optionally
implement simple complete-as-you-type login screens.
It is planned to extend the `systemd-homed` D-Bus API to instantly inform clients
about hardware associated with a specific user being plugged in, to which login
screens can listen in order to initiate authentication. Specifically, any
YubiKey-like security token plugged in that is associated with a local user
record should initiate authentication for that user, making typing in of the
username unnecessary.

22
docs/USER_GROUP_API.md
View File

@ -1,6 +1,6 @@
---
title: User/Group Record Lookup API via Varlink
category: Interfaces
category: Users, Groups and Home Directories
layout: default
---
@ -95,7 +95,7 @@ services are listening there, that have special relevance:
2. `io.systemd.Multiplexer` → This service multiplexes client queries to all
other running services. It's supposed to simplify client development: in
order to look up or enumerate user/group records it's sufficient to talk to
one service instead of all of them in parallel. Note that it is not availabe
one service instead of all of them in parallel. Note that it is not available
during earliest boot and final shutdown phases, hence for programs running
in that context it is preferable to implement the parallel lookup
themselves.
@ -108,7 +108,7 @@ example, introspection is not available, and the resolver logic is not used.
## Other Services
The `systemd` project provides two other services implementing this
The `systemd` project provides three other services implementing this
interface. Specifically:
1. `io.systemd.DynamicUser` → This service is implemented by the service
@ -119,6 +119,10 @@ interface. Specifically:
and provides records for the users and groups defined by the home
directories it manages.
3. `io.systemd.Machine` → This service is implemented by
`systemd-machined.service` and provides records for the users and groups used
by local containers that use user namespacing.
Other projects are invited to implement these services too. For example it
would make sense for LDAP/ActiveDirectory projects to implement these
interfaces, which would provide them a way to do per-user resource management
@ -160,7 +164,7 @@ method GetUserRecord(
service : string
) -> (
record : object,
incomplete : boolean
incomplete : bool
)
method GetGroupRecord(
@ -169,7 +173,7 @@ method GetGroupRecord(
service : string
) -> (
record : object,
incomplete : boolean
incomplete : bool
)
method GetMemberships(
@ -185,6 +189,7 @@ error NoRecordFound()
error BadService()
error ServiceNotAvailable()
error ConflictingRecordFound()
error EnumerationNotSupported()
```
The `GetUserRecord` method looks up or enumerates a user record. If the `uid`
@ -264,4 +269,11 @@ services. Result of this is that it can be one service that defines a user A,
and another service that defines a group B, and a third service that declares
that A is a member of B.
Looking up explicit users/groups by their name or UID/GID, or querying
user/group memberships must be supported by all services implementing these
interfaces. However, supporting enumeration (i.e. user/group lookups that may
result in more than one reply, because neither UID/GID nor name is specified)
is optional. Services which are asked for enumeration may return the
`EnumerationNotSupported` error in this case.
And that's really all there is to it.

169
docs/USER_NAMES.md Normal file
View File

@ -0,0 +1,169 @@
---
title: User/Group Name Syntax
category: Users, Groups and Home Directories
layout: default
---
# User/Group Name Syntax
The precise set of allowed user and group names on Linux systems is weakly
defined. Depending on the distribution a different set of requirements and
restrictions on the syntax of user/group names are enforced — on some
distributions the accepted syntax is even configurable by the administrator. In
the interest of interoperability systemd enforces different rules when
processing users/group defined by other subsystems and when defining users/groups
itself, following the principle of "Be conservative in what you send, be
liberal in what you accept". Also in the interest of interoperability systemd
will enforce the same rules everywhere and not make them configurable or
distribution dependent. The precise rules are described below.
Generally, the same rules apply for user as for group names.
## Other Systems
* On POSIX the set of [valid user
names](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_437)
is defined as [lower and upper case ASCII letters, digits, period,
underscore, and
hyphen](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282),
with the restriction that hyphen is not allowed as first character of the
user name. Interestingly no size limit is declared, i.e. in neither
direction, meaning that strictly speaking according to POSIX both the empty
string is a valid user name as well as a string of gigabytes in length.
* Debian/Ubuntu based systems enforce the regular expression
`^[a-z][-a-z0-9]*$`, i.e. only lower case ASCII letters, digits and
hyphens. As first character only lowercase ASCII letters are allowed. This
regular expression is configurable by the administrator at runtime
though. This rule enforces a minimum length of one character but no maximum
length.
* Upstream shadow-utils enforces the regular expression
`^[a-z_][a-z0-9_-]*[$]$`, i.e. is similar to the Debian/Ubuntu rule, but
allows underscores and hyphens, but the latter not as first character. Also,
an optional trailing dollar character is permitted.
* Fedora/Red Hat based systems enforce the regular expression of
`^[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,30}[a-zA-Z0-9_.$-]?$`, i.e. a size limit of
32 characters, with upper and lower case letters, digits, underscores,
hyphens and periods. No hyphen as first character though, and the last
character may be a dollar character. On top of that, `.` and `..` are not
allowed as user/group names.
* sssd is known to generate user names with embedded `@` and white-space
characters, as well as non-ASCII (i.e. UTF-8) user/group names.
* winbindd is known to generate user/group names with embedded `\` and
white-space characters, as well as non-ASCII (i.e. UTF-8) user/group names.
Other operating systems enforce different rules; in this documentation we'll
focus on Linux systems only however, hence those are out of scope. That said,
software like Samba is frequently deployed on Linux for providing compatibility
with Windows systems; on such systems it might be wise to stick to user/group
names also valid according to Windows rules.
## Rules systemd enforces
Distilled from the above, below are the rules systemd enforces on user/group
names. An additional, common rule between both modes listed below is that empty
strings are not valid user/group names.
Philosophically, the strict mode described below enforces an allow list of
what's allowed and prohibits everything else, while the relaxed mode described
below implements a deny list of what's not allowed and permits everything else.
### Strict mode
Strict user/group name syntax is enforced whenever a systemd component is used
to register a user or group in the system, for example a system user/group
using
[`systemd-sysusers.service`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html)
or a regular user with
[`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.html).
In strict mode, only uppercase and lowercase characters are allowed, as well as
digits, underscores and hyphens. The first character may not be a digit or
hyphen. A size limit is enforced: the minimum of `sysconf(_SC_LOGIN_NAME_MAX)`
(typically 256 on Linux; rationale: this is how POSIX suggests to detect the
limit), `UT_NAMESIZE-1` (typically 31 on Linux; rationale: names longer than
this cannot correctly appear in `utmp`/`wtmp` and create ambiguity with login
accounting) and `FILENAME_MAX` (4096 on Linux; rationale: user names typically
appear in directory names, i.e. the home directory), thus MIN(256, 31, 4096) =
31.
Note that these rules are both more strict and more relaxed than all of the
rules enforced by other systems listed above. A user/group name conforming to
systemd's strict rules will not necessarily pass a test by the rules enforced
by these other subsystems.
Written as regular expression the above is: `^[a-zA-Z_][a-zA-Z0-9_-]{0,30}$`
### Relaxed mode
Relaxed user/group name syntax is enforced whenever a systemd component accepts
and makes use of user/group names registered by other (non-systemd)
components of the system, for example in
[`systemd-logind.service`](https://www.freedesktop.org/software/systemd/man/systemd-logind.html).
Relaxed syntax is also enforced by the `User=` setting in service unit files,
i.e. for system services used for running services. Since these users may be
registered by a variety of tools relaxed mode is used, but since the primary
purpose of these users is to run a system service and thus a job for systemd a
warning is shown if the specified user name does not qualify by the strict
rules above.
* No embedded NUL bytes (rationale: handling in C must be possible and
straight-forward)
* No names consisting fully of digits (rationale: avoid confusion with numeric
UID/GID specifications)
* Similar, no names consisting of an initial hyphen and otherwise entirely made
up of digits (rationale: avoid confusion with negative, numeric UID/GID
specifications, e.g. `-1`)
* No strings that do not qualify as valid UTF-8 (rationale: we want to be able
to embed these strings in JSON, with permits only valid UTF-8 in its strings;
user names using other character sets, such as JIS/Shift-JIS will cause
validation errors)
* No control characters (i.e. characters in ASCII range 1…31; rationale: they
tend to have special meaning when output on a terminal in other contexts,
moreover the newline character — as a specific control character — is used as
record separator in `/etc/passwd`, and hence it's crucial to avoid
ambiguities here)
* No colon characters (rationale: it is used as field separator in `/etc/passwd`)
* The two strings `.` and `..` are not permitted, as these have special meaning
in file system paths, and user names are frequently included in file system
paths, in particular for the purpose of home directories.
* Similar, no slashes, as these have special meaning in file system paths
* No leading or trailing white-space is permitted; and hence no user/group names
consisting of white-space only either (rationale: this typically indicates
parsing errors, and creates confusion since not visible on screen)
Note that these relaxed rules are implied by the strict rules above, i.e. all
user/group names accepted by the strict rules are also accepted by the relaxed
rules, but not vice versa.
Note that this relaxed mode does not refuse a couple of very questionable
syntaxes. For example it permits a leading or embedded period. A leading period
is problematic because the matching home directory would typically be hidden
from the user's/administrator's view. An embedded period is problematic since
it creates ambiguity in traditional `chown` syntax (which is still accepted
today) that uses it to separate user and group names in the command's
parameter: without consulting the user/group databases it is not possible to
determine if a `chown` invocation would change just the owning user or both the
owning user and group. It also allows embedding `@` (which is confusing to
MTAs).
## Common Core
Combining all rules listed above, user/group names that shall be considered
valid in all systemd contexts and on all Linux systems should match the
following regular expression (at least according to our understanding):
`^[a-z][a-z0-9-]{0,30}$`

67
docs/USER_RECORD.md
View File

@ -1,6 +1,6 @@
---
title: JSON User Records
category: Interfaces
category: Users, Groups and Home Directories
layout: default
---
@ -14,7 +14,7 @@ pairs, encoded as JSON. Specifically:
1. [`systemd-homed.service`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html)
manages `human` user home directories and embeds these JSON records
directly in the home directory images (see [Home
Directories](https://systemd.io/HOME_DIRECTORY)) for details.
Directories](https://systemd.io/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
@ -180,7 +180,7 @@ strictly local context and without signatures doesn't have to deal with the
`perMachine` or `binding` sections and can include its data exclusively in the
regular section. A service that uses a separate, private channel for
authenticating users (or that doesn't have a concept of authentication at all)
does not need to to be concerned with the `secret` section of user records, as
does not need to be concerned with the `secret` section of user records, as
the fields included therein are only useful when executing authentication
operations natively against JSON user records.
@ -455,6 +455,10 @@ storage. If false and `luks` storage is used turns this behavior off. In
addition, depending on this setting an `FITRIM` or `fallocate()` operation is
executed to make sure the image matches the selected option.
`luksOfflineDiscard` → A boolean. Similar to `luksDiscard`, it controls whether
to trim/allocate the file system/backing file when deactivating the home
directory.
`luksCipher` → A string, indicating the cipher to use for the LUKS storage mechanism.
`luksCipherMode` → A string, selecting the cipher mode to use for the LUKS storage mechanism.
@ -542,7 +546,12 @@ below). It's undefined how precise the URI is: during log-in it is tested
against all plugged in security tokens and if there's exactly one matching
private key found with it it is used.
`privileged` → An object, which contains the fields of he `privileged` section
`fido2HmacCredential` → An array of strings, each with a Base64-encoded FIDO2
credential ID that shell be used for authentication with FIDO2 devices that
implement the `hmac-secret` extension. The salt to pass to the FIDO2 device is
found in `fido2HmacSalt`.
`privileged` → An object, which contains the fields of the `privileged` section
of the user record, see below.
`perMachine` → An array of objects, which contain the `perMachine` section of
@ -578,7 +587,7 @@ restrictive access semantics. The following fields are currently defined:
be a string like "What's the name of your first pet?", but is entirely for the
user to choose.
`hashPassword` → An array of strings, each containing a hashed UNIX password
`hashedPassword` → An array of strings, each containing a hashed UNIX password
string, in the format
[`crypt(3)`](http://man7.org/linux/man-pages/man3/crypt.3.html) generates. This
corresponds with `sp_pwdp` field of `struct spwd` (and in a way the `pw_passwd`
@ -590,7 +599,7 @@ as the lines in the traditional `~/.ssh/authorized_key` file.
`pkcs11EncryptedKey` → An array of objects. Each element of the array should be
an object consisting of three string fields: `uri` shall contain a PKCS#11
security token URI, `data` shall contain a Base64 encoded encrypted key and
security token URI, `data` shall contain a Base64-encoded encrypted key and
`hashedPassword` shall contain a UNIX password hash to test the key
against. Authenticating with a security token against this account shall work
as follows: the encrypted secret key is converted from its Base64
@ -598,13 +607,29 @@ representation into binary, then decrypted with the PKCS#11 `C_Decrypt()`
function of the PKCS#11 module referenced by the specified URI, using the
private key found on the same token. The resulting decrypted key is then
Base64-encoded and tested against the specified UNIX hashed password. The
Base64-enceded decrypted key may also be used to unlock further resources
Base64-encoded decrypted key may also be used to unlock further resources
during log-in, for example the LUKS or `fscrypt` storage backend. It is
generally recommended that for each entry in `pkcs11EncryptedKey` there's also
a matching one in `pkcs11TokenUri` and vice versa, with the same URI, appearing
in the same order, but this should not be required by applications processing
user records.
`fido2HmacSalt` → An array of objects, implementing authentication support with
FIDO2 devices that implement the `hmac-secret` extension. Each element of the
array should be an object consisting of three string fields: `credential`,
`salt`, `hashedPassword`. The first two shall contain Base64-encoded binary
data: the FIDO2 credential ID and the salt value to pass to the FIDO2
device. During authentication this salt along with the credential ID is sent to
the FIDO2 token, which will HMAC hash the salt with its internal secret key and
return the result. This resulting binary key should then be Base64-encoded and
used as string password for the further layers of the stack. The
`hashedPassword` field of the `fido2HmacSalt` field shall be a UNIX password
hash to test this derived secret key against for authentication. It is
generally recommended that for each entry in `fido2HmacSalt` there's also a
matching one in `fido2HmacCredential`, and vice versa, with the same credential
ID, appearing in the same order, but this should not be required by
applications processing user records.
## Fields in the `perMachine` section
As mentioned, the `perMachine` section contains settings that shall apply to
@ -648,12 +673,13 @@ that may be used in this section are identical to the equally named ones in the
`mountNoDevices`, `mountNoSuid`, `mountNoExecute`, `cifsDomain`,
`cifsUserName`, `cifsService`, `imagePath`, `uid`, `gid`, `memberOf`,
`fileSystemType`, `partitionUuid`, `luksUuid`, `fileSystemUuid`, `luksDiscard`,
`luksCipher`, `luksCipherMode`, `luksVolumeKeySize`, `luksPbkdfHashAlgorithm`,
`luksPbkdfType`, `luksPbkdfTimeCostUSec`, `luksPbkdfMemoryCost`,
`luksPbkdfParallelThreads`, `rateLimitIntervalUSec`, `rateLimitBurst`,
`enforcePasswordPolicy`, `autoLogin`, `stopDelayUSec`, `killProcesses`,
`passwordChangeMinUSec`, `passwordChangeMaxUSec`, `passwordChangeWarnUSec`,
`passwordChangeInactiveUSec`, `passwordChangeNow`, `pkcs11TokenUri`.
`luksOfflineDiscard`, `luksCipher`, `luksCipherMode`, `luksVolumeKeySize`,
`luksPbkdfHashAlgorithm`, `luksPbkdfType`, `luksPbkdfTimeCostUSec`,
`luksPbkdfMemoryCost`, `luksPbkdfParallelThreads`, `rateLimitIntervalUSec`,
`rateLimitBurst`, `enforcePasswordPolicy`, `autoLogin`, `stopDelayUSec`,
`killProcesses`, `passwordChangeMinUSec`, `passwordChangeMaxUSec`,
`passwordChangeWarnUSec`, `passwordChangeInactiveUSec`, `passwordChangeNow`,
`pkcs11TokenUri`, `fido2HmacCredential`.
## Fields in the `binding` section
@ -805,7 +831,7 @@ public key.
The `signature` field in the top-level user record object is an array of
objects. Each object encapsulates one signature and has two fields: `data` and
`key` (both are strings). The `data` field contains the actual signature,
encoded in base64, the `key` field contains a copy of the public key whose
encoded in Base64, the `key` field contains a copy of the public key whose
private key was used to make the signature, in PEM format. Currently only
signatures with Ed25519 keys are defined.
@ -859,13 +885,20 @@ The `secret` field of the top-level user record contains the following fields:
`password` → an array of strings, each containing a plain text password.
`pkcs11Pin` → an array of strings, each containing a plain text PIN, suitable
for unlocking PKCS#11 security tokens that require that.
`tokenPin` → an array of strings, each containing a plain text PIN, suitable
for unlocking security tokens that require that. (The field `pkcs11Pin` should
be considered a compatibility alias for this field, and merged with `tokenPin`
in case both are set.)
`pkcs11ProtectedAuthenticationPathPermitted` → a boolean. If set to true allows
the receiver to use the PKCS#11 "protected authentication path" (i.e. a
physical button/touch element on the security token) for authenticating the
user. If false or unset authentication this way shall not be attempted.
user. If false or unset, authentication this way shall not be attempted.
`fido2UserPresencePermitted` → a boolean. If set to true allows the receiver to
use the FIDO2 "user presence" flag. This is similar to the concept of
`pkcs11ProtectedAuthenticationPathPermitted`, but exposes the FIDO2 concept
behind it. If false or unset authentication this way shall not be attempted.
## Mapping to `struct passwd` and `struct spwd`

4
factory/etc/nsswitch.conf
View File

@ -1,7 +1,7 @@
# This file is part of systemd.
passwd: compat mymachines systemd
group: compat [SUCCESS=merge] mymachines [SUCCESS=merge] systemd
passwd: compat systemd
group: compat [SUCCESS=merge] systemd
shadow: compat
hosts: files mymachines resolve [!UNAVAIL=return] dns myhostname

33
fuzzbuzz.yaml
View File

@ -1,33 +0,0 @@
base: ubuntu:16.04
language: c
setup:
- sudo bash -c "echo 'deb-src http://archive.ubuntu.com/ubuntu/ xenial main restricted universe multiverse' >>/etc/apt/sources.list"
- sudo apt-get update -y
- sudo apt-get build-dep -y systemd
- sudo apt-get install -y python3-pip
- sudo apt-get install -y libfdisk-dev libp11-kit-dev libssl-dev libpwquality-dev
- pip3 install meson ninja
- export PATH="$HOME/.local/bin/:$PATH"
- CC=$FUZZ_CC CXX=$FUZZ_CXX meson -Dfuzzbuzz=true -Dfuzzbuzz-engine-dir=$(dirname "$FUZZ_ENGINE") -Dfuzzbuzz-engine=$(cut -d. -f1 <(basename "$FUZZ_ENGINE")) -Db_lundef=false ./build
- ninja -v -C ./build fuzzers
environment:
targets:
- name: fuzz-compress
harness:
binary: ./build/fuzz-compress
- name: fuzz-unit-file
harness:
binary: ./build/fuzz-unit-file
corpus: ./test/fuzz/fuzz-unit-file
- name: fuzz-journald-syslog
harness:
binary: ./build/fuzz-journald-syslog
corpus: ./test/fuzz/fuzz-journald-syslog
- name: fuzz-netdev-parser
harness:
binary: ./build/fuzz-netdev-parser
corpus: ./test/fuzz/fuzz-netdev-parser
- name: fuzz-network-parser
harness:
binary: ./build/fuzz-network-parser
corpus: ./test/fuzz/fuzz-network-parser

54
hwdb.d/60-autosuspend.hwdb Normal file
View File

@ -0,0 +1,54 @@
# This file is part of systemd.
#
# The lookup keys are $MODALIAS strings, see udev's hwdb builtin.
#
# Match string formats:
# <subsystem>:<modalias>
#
# pci:v<vendor>d<device>
# usb:v<vendor>p<product>
#
# To add local entries, create a new file
# /etc/udev/hwdb.d/61-autosuspend-local.hwdb
# and add your rules there. To load the new rules execute (as root):
# systemd-hwdb update
# udevadm trigger /dev/…
#
# If your changes are generally applicable, preferably send them as a pull
# request to
# https://github.com/systemd/systemd
# or create a bug report on https://github.com/systemd/systemd/issues and
# include your new rules, a description of the device, and the output of
# udevadm info
# the device.
#
# Allowed properties are:
# ID_AUTOSUSPEND=1
#
# Sort by brand, model
#########################################
# Alcor
#########################################
# AU9540 Smartcard Reader
usb:v058Fp9540*
ID_AUTOSUSPEND=1
#########################################
# QEMU
#########################################
# Emulated USB HID devices
usb:v0627p0001:*QEMU USB Keyboard*
usb:v0627p0001:*QEMU USB Mouse*
usb:v0627p0001:*QEMU USB Tablet*
ID_AUTOSUSPEND=1
#########################################
# Wacom
#########################################
usb:v056Ap51A0*
ID_AUTOSUSPEND=1

8
hwdb.d/60-keyboard.hwdb
View File

@ -598,8 +598,9 @@ evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHDX9494NR:pvr*
# HP EliteBook 725 G2
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHPLicrice:pvr*
# HP EliteBook 840 G1
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHPEliteBook840G1:pvr*
# HP EliteBook
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHPEliteBook*:pvr*
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHP*:pnHPEliteBook*:pvr*
# HP ProBook 440 G2
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHP440G2:pvr*
# several HP ProBooks 4xx
@ -608,8 +609,6 @@ evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHP*:pnHP*ProBook*4*:pvr*
# HP ZBook
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHPZBook*:pvr*
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHP*:pnHPZBook*:pvr*
# Elitebook x360 1040 G6
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHP:pn*EliteBook*x3601040G6:pvr*
KEYBOARD_KEY_81=f20 # Fn+F8; Microphone mute button, should be micmute
# HP ZBook 15 G2
@ -628,7 +627,6 @@ evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHP:pnHPZBookStudioG4:pvr*
# HP Folio 1040g2
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnHewlett-Packard*:pnHPEliteBookFolio1040G2:pvr*
KEYBOARD_KEY_81=f20 # Fn+F8; Microphone mute button, should be micmute
KEYBOARD_KEY_d8=!f23 # touchpad off
KEYBOARD_KEY_d9=!f22 # touchpad on

4
hwdb.d/60-sensor.hwdb
View File

@ -680,6 +680,10 @@ sensor:modalias:acpi:KIOX000A*:dmi:*:svnTREKSTOR:pnPrimetabT13B:*
sensor:modalias:acpi:BOSC0200*:dmi:*:svnTrekStor*:pnSurfTabtwin11.6:*
ACCEL_MOUNT_MATRIX=1, 0, 0; 0, -1, 0; 0, 0, 1
# alternative version of Trekstor's SurfTab Twin 11.6
sensor:modalias:acpi:BOSC0200*:dmi:*:bvrTP15-VT5.2.1.3:*:svnTrekStor*:pnSurfTabtwin11.6:*
ACCEL_MOUNT_MATRIX=-1, 0, 0; 0, 1, 0; 0, 0, -1
sensor:modalias:acpi:KIOX010A*:dmi:*:svnTREKSTOR:pnPrimebookC11B:*
sensor:modalias:acpi:KIOX010A*:dmi:*:svnTREKSTOR:pnPRIMEBOOKC11B:*
ACCEL_MOUNT_MATRIX=-1, 0, 0; 0, -1, 0; 0, 0, -1

36
hwdb.d/meson.build
View File

@ -1,6 +1,9 @@
# SPDX-License-Identifier: LGPL-2.1+
hwdb_files = files('''
# Those files right now are not supported by the grammar. Also,
# they are very long but quite repetitive and the parser is not very fast.
# So we don't "test" them.
hwdb_files_notest = files('''
20-pci-vendor-model.hwdb
20-pci-classes.hwdb
20-usb-vendor-model.hwdb
@ -12,6 +15,10 @@ hwdb_files = files('''
20-OUI.hwdb
20-net-ifname.hwdb
20-vmbus-class.hwdb
'''.split())
hwdb_files_test = files('''
60-autosuspend.hwdb
60-evdev.hwdb
60-input-id.hwdb
60-keyboard.hwdb
@ -23,7 +30,16 @@ hwdb_files = files('''
'''.split())
if conf.get('ENABLE_HWDB') == 1
install_data(hwdb_files,
auto_suspend_rules = custom_target(
'60-autosuspend-chromiumos.hwdb',
output : '60-autosuspend-chromiumos.hwdb',
command : make_autosuspend_rules_py,
capture : true,
install : true,
install_dir: udevhwdbdir)
install_data(hwdb_files_notest,
hwdb_files_test,
install_dir : udevhwdbdir)
meson.add_install_script('sh', '-c',
@ -32,15 +48,15 @@ if conf.get('ENABLE_HWDB') == 1
meson.add_install_script('sh', '-c',
'test -n "$DESTDIR" || @0@/systemd-hwdb update'
.format(rootbindir))
endif
############################################################
parse_hwdb_py = find_program('parse_hwdb.py')
if want_tests != 'false'
test('parse-hwdb',
parse_hwdb_py,
timeout : 90)
if want_tests != 'false'
parse_hwdb_py = find_program('parse_hwdb.py')
test('parse-hwdb',
parse_hwdb_py,
args : [hwdb_files_test,
auto_suspend_rules],
timeout : 90)
endif
endif
############################################################

46
hwdb.d/parse_hwdb.py
View File

@ -59,6 +59,7 @@ REAL = Combine((INTEGER + Optional('.' + Optional(INTEGER))) ^ ('.' + INTEGER))
SIGNED_REAL = Combine(Optional(Word('-+')) + REAL)
UDEV_TAG = Word(string.ascii_uppercase, alphanums + '_')
# Those patterns are used in type-specific matches
TYPES = {'mouse': ('usb', 'bluetooth', 'ps2', '*'),
'evdev': ('name', 'atkbd', 'input'),
'id-input': ('modalias'),
@ -68,13 +69,30 @@ TYPES = {'mouse': ('usb', 'bluetooth', 'ps2', '*'),
'sensor': ('modalias', ),
}
# Patterns that are used to set general properties on a device
GENERAL_MATCHES = {'acpi',
'bluetooth',
'usb',
'pci',
'sdio',
'vmbus',
'OUI',
}
def upperhex_word(length):
return Word(nums + 'ABCDEF', exact=length)
@lru_cache()
def hwdb_grammar():
ParserElement.setDefaultWhitespaceChars('')
prefix = Or(category + ':' + Or(conn) + ':'
for category, conn in TYPES.items())
matchline = Combine(prefix + Word(printables + ' ' + '®')) + EOL
matchline_typed = Combine(prefix + Word(printables + ' ' + '®'))
matchline_general = Combine(Or(GENERAL_MATCHES) + ':' + Word(printables + ' ' + '®'))
matchline = (matchline_typed | matchline_general) + EOL
propertyline = (White(' ', exact=1).suppress() +
Combine(UDEV_TAG - '=' - Word(alphanums + '_=:@*.!-;, "') - Optional(pythonStyleComment)) +
EOL)
@ -102,6 +120,7 @@ def property_grammar():
('MOUSE_WHEEL_CLICK_ANGLE_HORIZONTAL', INTEGER),
('MOUSE_WHEEL_CLICK_COUNT', INTEGER),
('MOUSE_WHEEL_CLICK_COUNT_HORIZONTAL', INTEGER),
('ID_AUTOSUSPEND', Literal('1')),
('ID_INPUT', Literal('1')),
('ID_INPUT_ACCELEROMETER', Literal('1')),
('ID_INPUT_JOYSTICK', Literal('1')),
@ -115,8 +134,6 @@ def property_grammar():
('ID_INPUT_TOUCHPAD', Literal('1')),
('ID_INPUT_TOUCHSCREEN', Literal('1')),
('ID_INPUT_TRACKBALL', Literal('1')),
('MOUSE_WHEEL_TILT_HORIZONTAL', Literal('1')),
('MOUSE_WHEEL_TILT_VERTICAL', Literal('1')),
('POINTINGSTICK_SENSITIVITY', INTEGER),
('POINTINGSTICK_CONST_ACCEL', REAL),
('ID_INPUT_JOYSTICK_INTEGRATION', Or(('internal', 'external'))),
@ -166,8 +183,27 @@ def parse(fname):
return []
return [convert_properties(g) for g in parsed.GROUPS]
def check_match_uniqueness(groups):
def check_matches(groups):
matches = sum((group[0] for group in groups), [])
# This is a partial check. The other cases could be also done, but those
# two are most commonly wrong.
grammars = { 'usb' : 'v' + upperhex_word(4) + Optional('p' + upperhex_word(4)),
'pci' : 'v' + upperhex_word(8) + Optional('d' + upperhex_word(8)),
}
for match in matches:
prefix, rest = match.split(':', maxsplit=1)
gr = grammars.get(prefix)
if gr:
try:
gr.parseString(rest)
except ParseBaseException as e:
error('Pattern {!r} is invalid: {}', rest, e)
continue
if rest[-1] not in '*:':
error('pattern {} does not end with "*" or ":"', match)
matches.sort()
prev = None
for match in matches:
@ -242,7 +278,7 @@ if __name__ == '__main__':
for fname in args:
groups = parse(fname)
print_summary(fname, groups)
check_match_uniqueness(groups)
check_matches(groups)
check_properties(groups)
sys.exit(ERROR)

13
man/bootctl.xml
View File

@ -102,7 +102,7 @@
</varlistentry>
<varlistentry>
<term><option>systemd-efi-options</option> <optional><replaceable>VALUE</replaceable></optional></term>
<term><option>systemd-efi-options</option> <optional><replaceable>STRING</replaceable></optional></term>
<listitem><para>When called without the optional argument, prints the current value of the
<literal>SystemdOptions</literal> EFI variable. When called with an argument, sets the
@ -111,6 +111,17 @@
for the meaning of that variable.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term>
<listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a
boolean argument which controls whether to show the firmware setup on next system reboot. If the
argument is omitted shows the current status of the flag, or whether the flag is supported. This
controls the same flag as <command>systemctl reboot --firmware-setup</command>, but is more
low-level and allows setting the flag independently from actually requesting a
reboot.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list</option></term>

8
man/bootup.xml
View File

@ -32,7 +32,7 @@
of firmware, this firmware may also load the kernel directly.</para>
<para>The kernel (optionally) mounts an in-memory file system, often generated by
<citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
which looks for the root file system. Nowadays this is usually implemented as an initramfs — a compressed
archive which is extracted when the kernel boots up into a lightweight in-memory file system based on
tmpfs, but in the past normal file systems using an in-memory block device (ramdisk) were used, and the
@ -170,7 +170,7 @@ emergency.service | | |
user units. For non-graphical sessions, <filename>default.target</filename> is used. Whenever the user
logs into a graphical session, the login manager will start the
<filename>graphical-session.target</filename> target that is used to pull in units required for the
grahpical session. A number of targets (shown on the right side) are started when specific hardware is
graphical session. A number of targets (shown on the right side) are started when specific hardware is
available to the user.</para>
<programlisting>
@ -192,7 +192,7 @@ emergency.service | | |
v graphical-session-pre.target
(various user services) | (printers)
| v |
| (services for the graphical sesion) v
| (services for the graphical session) v
| | printer.target
v v
<emphasis>default.target</emphasis> graphical-session.target</programlisting>
@ -349,7 +349,7 @@ systemd-reboot.service systemd-poweroff.service systemd-halt.service syste
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry project='man-pages'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>

2
man/coredump.conf.xml
View File

@ -49,7 +49,7 @@
<title>Options</title>
<para>All options are configured in the
<literal>[Coredump]</literal> section:</para>
[Coredump] section:</para>
<variablelist class='config-directives'>

8
man/coredumpctl.xml
View File

@ -52,8 +52,8 @@
matching specified characteristics. If no command is
specified, this is the implied default.</para>
<para>The output is designed to be human readable and contains list contains
a table with the following columns:</para>
<para>The output is designed to be human readable and contains a table with the following
columns:</para>
<variablelist>
<varlistentry>
<term>TIME</term>
@ -134,7 +134,7 @@
<listitem><para>Invoke a debugger on the last core dump
matching specified characteristics. By default,
<citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
will be used. This may be changed using the <option>--debugger=</option>
option or the <varname>$SYSTEMD_DEBUGGER</varname> environment
variable.</para></listitem>
@ -213,7 +213,7 @@
<listitem><para>Use the given debugger for the <command>debug</command>
command. If not given and <varname>$SYSTEMD_DEBUGGER</varname> is unset, then
<citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
will be used. </para></listitem>
</varlistentry>

81
man/crypttab.xml
View File

@ -41,7 +41,7 @@
character are ignored. Each of the remaining lines describes one
encrypted block device. Fields are delimited by white space.</para>
<para>Each line is in the form<programlisting><replaceable>name</replaceable> <replaceable>encrypted-device</replaceable> <replaceable>password</replaceable> <replaceable>options</replaceable></programlisting>
<para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>encrypted-device</replaceable> <replaceable>key-file</replaceable> <replaceable>options</replaceable></programlisting>
The first two fields are mandatory, the remaining two are
optional.</para>
@ -53,24 +53,22 @@
it is opened as a LUKS device; otherwise, it is assumed to be in
raw dm-crypt (plain mode) format.</para>
<para>The first field contains the name of the resulting encrypted
block device; the device is set up within
<filename>/dev/mapper/</filename>.</para>
<para>The first field contains the name of the resulting encrypted volume; its block device is set up
below <filename>/dev/mapper/</filename>.</para>
<para>The second field contains a path to the underlying block
device or file, or a specification of a block device via
<literal>UUID=</literal> followed by the UUID.</para>
<para>The third field specifies the encryption password. If the
field is not present or the password is set to
<literal>none</literal> or <literal>-</literal>, the password has
to be manually entered during system boot. Otherwise, the field is
interpreted as an absolute path to a file containing the encryption
password. For swap encryption, <filename>/dev/urandom</filename>
or the hardware device <filename>/dev/hw_random</filename> can be
used as the password file; using <filename>/dev/random</filename>
may prevent boot completion if the system does not have enough
entropy to generate a truly random encryption key.</para>
<para>The third field specifies an absolute path to a file to read the encryption key from. Optionally,
the path may be followed by <literal>:</literal> and an fstab device specification (e.g. starting with
<literal>LABEL=</literal> or similar); in which case, the path is relative to the device file system
root. If the field is not present or set to <literal>none</literal> or <literal>-</literal>, a key file
named after the volume to unlock (i.e. the first column of the line), suffixed with
<filename>.key</filename> is automatically loaded from the <filename>/etc/cryptsetup-keys.d/</filename>
and <filename>/run/cryptsetup-keys.d/</filename> directories, if present. Otherwise, the password has to
be manually entered during system boot. For swap encryption, <filename>/dev/urandom</filename> may be
used as key file.</para>
<para>The fourth field, if present, is a comma-delimited list of
options. The following options are recognized:</para>
@ -138,6 +136,15 @@
size is then given by the key size.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>keyfile-erase</option></term>
<listitem><para>If enabled, the specified key file is erased after the volume is activated or when
activation fails. This is in particular useful when the key file is only acquired transiently before
activation (e.g. via a file in <filename>/run/</filename>, generated by a service running before
activation), and shall be removed after use. Defaults to off.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>key-slot=</option></term>
@ -172,6 +179,13 @@
<option>size=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>bitlk</option></term>
<listitem><para>Decrypt Bitlocker drive. Encryption parameters
are deduced by cryptsetup from Bitlocker header.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>_netdev</option></term>
@ -241,6 +255,7 @@
<listitem><para>Perform encryption using the same cpu that IO was submitted on. The default is to use
an unbound workqueue so that encryption work is automatically balanced between available CPUs.</para>
<para>This requires kernel 4.0 or newer.</para>
</listitem>
</varlistentry>
@ -249,9 +264,10 @@
<term><option>submit-from-crypt-cpus</option></term>
<listitem><para>Disable offloading writes to a separate thread after encryption. There are some
situations where offloading write bios from the encryption threads to a single thread degrades
performance significantly. The default is to offload write bios to the same thread because it benefits
CFQ to have writes submitted using the same context.</para>
situations where offloading write requests from the encryption threads to a dedicated thread degrades
performance significantly. The default is to offload write requests to a dedicated thread because it
benefits the CFQ scheduler to have writes submitted using the same context.</para>
<para>This requires kernel 4.0 or newer.</para>
</listitem>
</varlistentry>
@ -388,18 +404,17 @@
</varlistentry>
<varlistentry>
<term><option>tmp</option></term>
<term><option>tmp=</option></term>
<listitem><para>The encrypted block device will be prepared
for using it as <filename>/tmp</filename>; it will be
formatted using
<citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
This option implies <option>plain</option>.</para>
<listitem><para>The encrypted block device will be prepared for using it as
<filename>/tmp/</filename>; it will be formatted using <citerefentry
project='man-pages'><refentrytitle>mkfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
a file system type as argument, such as <literal>ext4</literal>, <literal>xfs</literal> or
<literal>btrfs</literal>. If no argument is specified defaults to <literal>ext4</literal>. This
option implies <option>plain</option>.</para>
<para>WARNING: Using the <option>tmp</option> option will
destroy the contents of the named partition during every boot,
so make sure the underlying block device is specified
correctly.</para></listitem>
<para>WARNING: Using the <option>tmp</option> option will destroy the contents of the named partition
during every boot, so make sure the underlying block device is specified correctly.</para></listitem>
</varlistentry>
<varlistentry>
@ -431,6 +446,15 @@
before it is used to unlock the LUKS volume.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>try-empty-password=</option></term>
<listitem><para>Takes a boolean argument. If enabled, right before asking the user for a password it
is first attempted to unlock the volume with an empty password. This is useful for systems that are
initialized with an encrypted volume with only an empty password set, which shall be replaced with a
suitable password during first boot, but after activation.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>x-systemd.device-timeout=</option></term>
@ -490,7 +514,8 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s</programlist
<para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA
decryption keys. Here's an example how to set up a Yubikey security token for this purpose, using
<command>ykman</command> from the yubikey-manager project:</para>
<citerefentry project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry>
from the yubikey-manager project:</para>
<programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting>

9
man/custom-entities.ent.in
View File

@ -1,11 +1,12 @@
<?xml version="1.0" encoding="utf-8" ?>
<!ENTITY MOUNT_PATH @MOUNT_PATH@>
<!ENTITY UMOUNT_PATH @UMOUNT_PATH@>
<!ENTITY systemgeneratordir @SYSTEM_GENERATOR_PATH@>
<!ENTITY usergeneratordir @USER_GENERATOR_PATH@>
<!ENTITY systemenvgeneratordir @SYSTEM_ENV_GENERATOR_PATH@>
<!ENTITY userenvgeneratordir @USER_ENV_GENERATOR_PATH@>
<!ENTITY systemgeneratordir @SYSTEM_GENERATOR_DIR@>
<!ENTITY usergeneratordir @USER_GENERATOR_DIR@>
<!ENTITY systemenvgeneratordir @SYSTEM_ENV_GENERATOR_DIR@>
<!ENTITY userenvgeneratordir @USER_ENV_GENERATOR_DIR@>
<!ENTITY CERTIFICATE_ROOT @CERTIFICATE_ROOT@>
<!ENTITY FALLBACK_HOSTNAME @FALLBACK_HOSTNAME@>
<!ENTITY MEMORY_ACCOUNTING_DEFAULT @MEMORY_ACCOUNTING_DEFAULT_YES_NO@>
<!ENTITY KILL_USER_PROCESSES @KILL_USER_PROCESSES_YES_NO@>
<!ENTITY DEBUGTTY @DEBUGTTY@>

4
man/daemon.xml
View File

@ -357,7 +357,7 @@
special target unit <filename>sockets.target</filename>. It is
recommended to place a
<varname>WantedBy=sockets.target</varname> directive in the
<literal>[Install]</literal> section to automatically add such a
[Install] section to automatically add such a
dependency on installation of a socket unit. Unless
<varname>DefaultDependencies=no</varname> is set, the necessary
ordering dependencies are implicitly created for all socket
@ -520,7 +520,7 @@
operating system-independent.</para></listitem>
<listitem><para>Make sure to include an
<literal>[Install]</literal> section including installation
[Install] section including installation
information for the unit file. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. To activate your service on boot, make sure to

199
man/directives-template.xml Normal file
View File

@ -0,0 +1,199 @@
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.directives">
<refentryinfo>
<title>systemd.directives</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd.directives</refentrytitle>
<manvolnum>7</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd.directives</refname>
<refpurpose>Index of configuration directives</refpurpose>
</refnamediv>
<refsect1>
<title>Unit directives</title>
<para>Directives for configuring units, used in unit files.</para>
<variablelist id='unit-directives' />
</refsect1>
<refsect1>
<title>Options on the kernel command line</title>
<para>Kernel boot options for configuring the behaviour of the systemd process.</para>
<variablelist id='kernel-commandline-options' />
</refsect1>
<refsect1>
<title>Environment variables</title>
<para>Environment variables understood by the systemd manager and other programs and environment
variable-compatible settings.</para>
<variablelist id='environment-variables' />
</refsect1>
<refsect1>
<title>EFI variables</title>
<para>EFI variables understood by
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
and other programs.</para>
<variablelist id='efi-variables' />
</refsect1>
<refsect1>
<title>Home Area/User Account directives</title>
<para>Directives for configuring home areas and user accounts via
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<variablelist id='home-directives' />
</refsect1>
<refsect1>
<title>UDEV directives</title>
<para>Directives for configuring systemd units through the udev database.</para>
<variablelist id='udev-directives' />
</refsect1>
<refsect1>
<title>Network directives</title>
<para>Directives for configuring network links through the net-setup-link udev builtin and networks
through systemd-networkd.</para>
<variablelist id='network-directives' />
</refsect1>
<refsect1>
<title>Journal fields</title>
<para>Fields in the journal events with a well known meaning.</para>
<variablelist id='journal-directives' />
</refsect1>
<refsect1>
<title>PAM configuration directives</title>
<para>Directives for configuring PAM behaviour.</para>
<variablelist id='pam-directives' />
</refsect1>
<refsect1>
<title><filename>/etc/crypttab</filename> and
<filename>/etc/fstab</filename> options</title>
<para>Options which influence mounted filesystems and encrypted volumes.</para>
<variablelist id='fstab-options' />
</refsect1>
<refsect1>
<title><citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>
directives</title>
<para>Directives for configuring systemd-nspawn containers.</para>
<variablelist id='nspawn-directives' />
</refsect1>
<refsect1>
<title>Program configuration options</title>
<para>Directives for configuring the behaviour of the systemd process and other tools through
configuration files.</para>
<variablelist id='config-directives' />
</refsect1>
<refsect1>
<title>Command line options</title>
<para>Command-line options accepted by programs in the systemd suite.</para>
<variablelist id='options' />
</refsect1>
<refsect1>
<title>Constants</title>
<para>Various constant used and/or defined by systemd.</para>
<variablelist id='constants' />
</refsect1>
<refsect1>
<title>Miscellaneous options and directives</title>
<para>Other configuration elements which don't fit in any of the above groups.</para>
<variablelist id='miscellaneous' />
</refsect1>
<refsect1>
<title>Specifiers</title>
<para>Short strings which are substituted in configuration directives.</para>
<variablelist id='specifiers' />
</refsect1>
<refsect1>
<title>Files and directories</title>
<para>Paths and file names referred to in the documentation.</para>
<variablelist id='filenames' />
</refsect1>
<refsect1>
<title>D-Bus interfaces</title>
<para>Interfaces exposed over D-Bus.</para>
<variablelist id='dbus-interface' />
</refsect1>
<refsect1>
<title>D-Bus methods</title>
<para>Methods exposed in the D-Bus interface.</para>
<variablelist id='dbus-method' />
</refsect1>
<refsect1>
<title>D-Bus properties</title>
<para>Properties exposed in the D-Bus interface.</para>
<variablelist id='dbus-property' />
</refsect1>
<refsect1>
<title>D-Bus signals</title>
<para>Signals emitted in the D-Bus interface.</para>
<variablelist id='dbus-signal' />
</refsect1>
<refsect1>
<title>Colophon</title>
<para id='colophon' />
</refsect1>
</refentry>

9
man/environment.d.xml
View File

@ -22,7 +22,7 @@
<refnamediv>
<refname>environment.d</refname>
<refpurpose>Definition of user session environment</refpurpose>
<refpurpose>Definition of user service environment</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -36,8 +36,8 @@
<refsect1>
<title>Description</title>
<para>The <filename>environment.d</filename> directories contain a list of environment variable
assignments for services started by the systemd user instance.
<para>Configuration files in the <filename>environment.d/</filename> directories contain lists of
environment variable assignments for services started by the systemd user instance.
<citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
parses them and updates the environment exported by the systemd user instance. See below for an
discussion of which processes inherit those variables.</para>
@ -58,7 +58,6 @@
variable assignments, separated by newlines. The right hand side of these assignments may
reference previously defined environment variables, using the <literal>${OTHER_KEY}</literal>
and <literal>$OTHER_KEY</literal> format. It is also possible to use
<literal>${<replaceable>FOO</replaceable>:-<replaceable>DEFAULT_VALUE</replaceable>}</literal>
to expand in the same way as <literal>${<replaceable>FOO</replaceable>}</literal> unless the
expansion would be empty, in which case it expands to <replaceable>DEFAULT_VALUE</replaceable>,
@ -95,7 +94,7 @@
<para>Environment variables exported by the user manager (<command>systemd --user</command> instance
started in the <filename>user@<replaceable>uid</replaceable>.service</filename> system service) apply to
any services started by that manager. In particular, this may include services which run user shells. For
example in the Gnome environment, the graphical terminal emulator runs as the
example in the GNOME environment, the graphical terminal emulator runs as the
<filename>gnome-terminal-server.service</filename> user unit, which in turn runs the user shell, so that
shell will inherit environment variables exported by the user manager. For other instances of the shell,
not launched by the user manager, the environment they inherit is defined by the program that starts

2
man/file-hierarchy.xml
View File

@ -648,7 +648,7 @@
<filename>/usr/share/</filename> hierarchy to the locations
defined by the various relevant specifications.</para>
<para>During runtime, and for local configuration and state,
<para>During runtime, and for local configuration and runtime state,
additional directories are defined:</para>
<table>

150
man/homectl.xml
View File

@ -50,7 +50,7 @@
<listitem><para>An individual LUKS2 encrypted loopback file for a user, stored in
<filename>/home/*.home</filename>. At login the file system contained in this files is mounted, after
the LUKS2 encrypted volume has been attached. The user's password is identical to the encryption
passphrase of the LUKS2 volume. Access to data without preceeding user authentication is thus not
passphrase of the LUKS2 volume. Access to data without preceding user authentication is thus not
possible, even for the system administrator. This storage mechanism provides the strongest data
security and is thus recommended.</para></listitem>
@ -119,9 +119,9 @@
<term><option>--identity=</option><replaceable>FILE</replaceable></term>
<listitem><para>Read the user's JSON record from the specified file. If passed as
<literal>-</literal> reads the user record from standard input. The supplied JSON object must follow
the structure documented on <ulink url="https://systemd.io/USER_RECORDS">JSON User
Records</ulink>. This option may be used in conjunction with the <command>create</command> and
<literal>-</literal> read the user record from standard input. The supplied JSON object must follow
the structure documented on <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink>.
This option may be used in conjunction with the <command>create</command> and
<command>update</command> commands (see below), where it allows configuring the user record in JSON
as-is, instead of setting the individual user record properties (see below).</para></listitem>
</varlistentry>
@ -247,10 +247,9 @@
different system and the configured UID is taken by another user there, then
<command>systemd-homed</command> may assign the user a different UID on that system. The specified
UID must be outside of the system user range. It is recommended to use the 60001…60513 UID range for
this purpose. If not specified the UID is automatically picked. When logging in and the home
directory is found to be owned by a UID not matching the user's assigned one the home directory and
all files and directories inside it will have their ownership changed automatically before login
completes.</para>
this purpose. If not specified, the UID is automatically picked. If the home directory is found to be
owned by a different UID when logging in, the home directory and everything underneath it will have
its ownership changed automatically before login completes.</para>
<para>Note that users managed by <command>systemd-homed</command> always have a matching group
associated with the same name as well as a GID matching the UID of the user. Thus, configuring the
@ -266,18 +265,19 @@
privileges. Note that <command>systemd-homed</command> does not manage any groups besides a group
matching the user in name and numeric UID/GID. Thus any groups listed here must be registered
independently, for example with <citerefentry
project='man-pages'><refentrytitle>groupadd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If
non-existant groups that are listed there are ignored. This option may be used more than once, in
which case all specified group lists are combined.</para></listitem>
project='man-pages'><refentrytitle>groupadd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
Any non-existent groups are ignored. This option may be used more than once, in which case all
specified group lists are combined. If the user is currently a member of a group which is not listed,
the user will be removed from the group.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--skel=</option><replaceable>PATH</replaceable></term>
<listitem><para>Takes a file system path to a directory. Specifies the skeleton directory to
initialize the home directory with. All files and directories in the specified are copied into any
newly create home directory. If not specified defaults to
<filename>/etc/skel/</filename>.</para></listitem>
initialize the home directory with. All files and directories in the specified path are copied into
any newly create home directory. If not specified defaults to <filename>/etc/skel/</filename>.
</para></listitem>
</varlistentry>
<varlistentry>
@ -312,7 +312,7 @@
<listitem><para>Takes a specifier indicating the preferred language of the user. The
<varname>$LANG</varname> environment variable is initialized from this value on login, and thus a
value suitable for this environment variable is accepted here, for example
<option>--language=de_DE.UTF8</option></para></listitem>
<option>--language=de_DE.UTF8</option>.</para></listitem>
</varlistentry>
<varlistentry>
@ -330,8 +330,50 @@
security token with exactly one pair of X.509 certificate and private key. A random secret key is
then generated, encrypted with the public key of the X.509 certificate, and stored as part of the
user record. At login time it is decrypted with the PKCS#11 module and then used to unlock the
account and associated resources. See below for an example how to set up authentication with security
token.</para></listitem>
account and associated resources. See below for an example how to set up authentication with a
security token.</para>
<para>Instead of a valid PKCS#11 URI, the special strings <literal>list</literal> and
<literal>auto</literal> may be specified. If <literal>list</literal> is passed, a brief table of
suitable, currently plugged in PKCS#11 hardware tokens is shown, along with their URIs. If
<literal>auto</literal> is passed, a suitable PKCS#11 hardware token is automatically selected (this
operation will fail if there isn't exactly one suitable token discovered). The latter is a useful
shortcut for the most common case where a single PKCS#11 hardware token is plugged in.</para>
<para>Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the
<literal>hmac-secret</literal> extension (for example: the YubiKey 5 series), as supported with the
<option>--fido2-device=</option> option below. Both mechanisms are similarly powerful, though FIDO2
is the more modern technology. PKCS#11/PIV tokens have the benefit of being recognizable before
authentication and hence can be used for implying the user identity to use for logging in, which
FIDO2 does not allow. PKCS#11/PIV devices generally require initialization (i.e. storing a
private/public key pair on them, see example below) before they can be used; FIDO2 security tokens
generally do not required that, and work out of the box.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--fido2-device=</option><replaceable>PATH</replaceable></term>
<listitem><para>Takes a path to a Linux <literal>hidraw</literal> device
(e.g. <filename>/dev/hidraw1</filename>), referring to a FIDO2 security token implementing the
<literal>hmac-secret</literal> extension, that shall be able to unlock the user account. If used, a
random salt value is generated on the host, which is passed to the FIDO2 device, which calculates a
HMAC hash of it, keyed by its internal secret key. The result is then used as key for unlocking the
user account. The random salt is included in the user record, so that whenever authentication is
needed it can be passed again to the FIDO2 token, to retrieve the actual key.</para>
<para>Instead of a valid path to a FIDO2 <literal>hidraw</literal> device the special strings
<literal>list</literal> and <literal>auto</literal> may be specified. If <literal>list</literal> is
passed, a brief table of suitable discovered FIDO2 devices is shown. If <literal>auto</literal> is
passed, a suitable FIDO2 token is automatically selected, if exactly one is discovered. The latter is
a useful shortcut for the most common case where a single FIDO2 hardware token is plugged in.</para>
<para>Note that FIDO2 devices suitable for this option must implement the
<literal>hmac-secret</literal> extension. Most current devices (such as the YubiKey 5 series) do. If
the extension is not implemented the device cannot be used for unlocking home directories.</para>
<para>Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (and thus may be
used with either <option>--fido2-device=</option> or <option>--pkcs11-token-uri=</option>), for a
discussion see above.</para></listitem>
</varlistentry>
<varlistentry>
@ -395,20 +437,20 @@
<listitem><para>Each of these options takes a time span specification as argument (in the syntax
documented in
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>) and
configure various aspects of the user's password expiration policy. Specifically,
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) and
configures various aspects of the user's password expiration policy. Specifically,
<option>--password-change-min=</option> configures how much time has to pass after changing the
password of the user until the password may be changed again. If the user tries to change their
password before this time passes the attempt is refused. <option>--password-change-max=</option>
configures how much time has to pass after the the password is changed until the password expires and
needs to be changed again. After this time passes any attempts to log in may only proceed after the
password is changed. <option>--password-change-warn=</option> specifies how much earlier than then
the time configured with <option>--password-change-max=</option> the user is warned at login to
change their password as it will expire soon. Finally <option>--password-change-inactive=</option>
configures the time which has to pass after the password as expired until the user is not permitted
to log in or change the password anymore. Note that these options only apply to password
authentication, and do not apply to other forms of authentication, for example PKCS#11-based security
token authentication.</para></listitem>
configures how soon after it has been changed the password expires and needs to be changed again.
After this time passes logging in may only proceed after the password is changed.
<option>--password-change-warn=</option> specifies how much earlier than then the time configured
with <option>--password-change-max=</option> the user is warned at login to change their password as
it will expire soon. Finally <option>--password-change-inactive=</option> configures the time which
has to pass after the password as expired until the user is not permitted to log in or change the
password anymore. Note that these options only apply to password authentication, and do not apply to
other forms of authentication, for example PKCS#11-based security token
authentication.</para></listitem>
</varlistentry>
<varlistentry>
@ -467,7 +509,7 @@
<citerefentry project='man-pages'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
or a similar tool. Use <option>--rlimit=LIMIT_NPROC=</option> to place a limit on the tasks actually
running under the UID of the user, thus excluding any child processes that might have changed user
identity. This controls the <varname>TasksMax=</varname> settting of the per-user systemd slice unit
identity. This controls the <varname>TasksMax=</varname> setting of the per-user systemd slice unit
<filename>user-$UID.slice</filename>. See
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for further details.</para></listitem>
@ -490,7 +532,7 @@
<term><option>--cpu-weight=</option><replaceable>WEIGHT</replaceable></term>
<term><option>--io-weight=</option><replaceable>WEIGHT</replaceable></term>
<listitem><para>Set a CPU and IO scheduling weights of the processes of the user, including those of
<listitem><para>Set CPU and IO scheduling weights of the processes of the user, including those of
processes forked off by the user that changed user credentials. Takes a numeric value in the range
1…10000. This controls the <varname>CPUWeight=</varname> and <varname>IOWeight=</varname> settings of
the per-user systemd slice unit <filename>user-$UID.slice</filename>. See
@ -504,9 +546,9 @@
<listitem><para>Selects the storage mechanism to use for this home directory. Takes one of
<literal>luks</literal>, <literal>fscrypt</literal>, <literal>directory</literal>,
<literal>subvolume</literal>, <literal>cifs</literal>. For details about these mechanisms, see
above. If a new home directory is created and the storage type is not specifically specified defaults
to <literal>luks</literal> if supported, <literal>subvolume</literal> as first fallback if supported,
and <literal>directory</literal> if not.</para></listitem>
above. If a new home directory is created and the storage type is not specifically specified,
<citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
defines which default storage to use.</para></listitem>
</varlistentry>
<varlistentry>
@ -525,9 +567,10 @@
<listitem><para>When LUKS2 storage is used configures the file system type to use inside the home
directory LUKS2 container. One of <literal>ext4</literal>, <literal>xfs</literal>,
<literal>btrfs</literal>. If not specified defaults to <literal>ext4</literal>. Note that
<literal>xfs</literal> is not recommended as its support for file system resizing is too
limited.</para></listitem>
<literal>btrfs</literal>. If not specified
<citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
defines which default file system type to use. Note that <literal>xfs</literal> is not recommended as
its support for file system resizing is too limited.</para></listitem>
</varlistentry>
<varlistentry>
@ -544,6 +587,16 @@
loopback file) the discard logic defaults to on.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--luks-offline-discard=</option><replaceable>BOOL</replaceable></term>
<listitem><para>Similar to <option>--luks-discard=</option>, controls the trimming of the file
system. However, while <option>--luks-discard=</option> controls what happens when the home directory
is active, <option>--luks-offline-discard=</option> controls what happens when it becomes inactive,
i.e. whether to trim/allocate the storage when deactivating the home directory. This option defaults
to on, to ensure disk space is minimized while a user is not logged in.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--luks-cipher=</option><replaceable>CIPHER</replaceable></term>
<term><option>--luks-cipher-mode=</option><replaceable>MODE</replaceable></term>
@ -641,8 +694,8 @@
<para>Activation of a home directory involves various operations that depend on the selected storage
mechanism. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a
password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file
system, mounting the file system, and potentiatlly changing the ownership of all included files to
the correct UID/GID.</para></listitem>
system, mounting the file system, and potentially changing the ownership of all included files to the
correct UID/GID.</para></listitem>
</varlistentry>
<varlistentry>
@ -707,7 +760,7 @@
<varlistentry>
<term><command>passwd</command> <replaceable>USER</replaceable></term>
<listitem><para>Change the password of the specified home direcory/user account.</para></listitem>
<listitem><para>Change the password of the specified home directory/user account.</para></listitem>
</varlistentry>
<varlistentry>
@ -798,7 +851,7 @@
</example>
<example>
<title>Set up authentication with a YubiKey security token:</title>
<title>Set up authentication with a YubiKey security token using PKCS#11/PIV:</title>
<programlisting># Clear the Yubikey from any old keys (careful!)
ykman piv reset
@ -809,16 +862,18 @@ ykman piv generate-key -a RSA2048 9d pubkey.pem
# Create a self-signed certificate from this public key, and store it on the device.
ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
# We don't need the publibc key on disk anymore
# We don't need the public key on disk anymore
rm pubkey.pem
# Check if the newly create key on the Yubikey shows up as token in PKCS#11. Have a look at the output, and
# copy the resulting token URI to the clipboard.
p11tool --list-tokens
# Allow the security token to unlock the account of user 'lafcadio'.
homectl update lafcadio --pkcs11-token-uri=auto</programlisting>
</example>
# Allow the security token referenced by the determined PKCS#11 URI to unlock the account of user
# 'lafcadio'. (Replace the '…' by the URI from the clipboard.)
homectl update lafcadio --pkcs11-token-uri=…</programlisting>
<example>
<title>Set up authentication with a FIDO2 security token:</title>
<programlisting># Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'.
homectl update nihilbaxter --fido2-device=auto</programlisting>
</example>
</refsect1>
@ -827,6 +882,7 @@ homectl update lafcadio --pkcs11-token-uri=…</programlisting>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

84
man/homed.conf.xml Normal file
View File

@ -0,0 +1,84 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="homed.conf" conditional='ENABLE_HOMED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>homed.conf</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>homed.conf</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>homed.conf</refname>
<refname>homed.conf.d</refname>
<refpurpose>Home area/user account manager configuration files</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename>/etc/systemd/homed.conf</filename></para>
<para><filename>/etc/systemd/homed.conf.d/*.conf</filename></para>
<para><filename>/run/systemd/homed.conf.d/*.conf</filename></para>
<para><filename>/usr/lib/systemd/homed.conf.d/*.conf</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>These configuration files control default parameters for home areas/user accounts created and
managed by
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</refsect1>
<xi:include href="standard-conf.xml" xpointer="main-conf" />
<refsect1>
<title>Options</title>
<para>The following options are available in the [Home] section:</para>
<variablelist class='home-directives'>
<varlistentry>
<term><varname>DefaultStorage=</varname></term>
<listitem><para>The default storage to use for home areas. Takes one of <literal>luks</literal>,
<literal>fscrypt</literal>, <literal>directory</literal>, <literal>subvolume</literal>,
<literal>cifs</literal>. For details about these options, see
<citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If not
configured or assigned the empty string, the default storage is automatically determined: if not
running in a container environment and <filename>/home/</filename> is not itself encrypted, defaults
to <literal>luks</literal>. Otherwise defaults to <literal>subvolume</literal> if
<filename>/home/</filename> is on a btrfs file system, and <literal>directory</literal>
otherwise. Note that the storage selected on the <command>homectl</command> command line always takes
precedence.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>DefaultFileSystemType=</varname></term>
<listitem><para>When using <literal>luks</literal> as storage (see above), selects the default file
system to use inside the user's LUKS volume. Takes one of <literal>ext4</literal>,
<literal>xfs</literal> or <literal>btrfs</literal>. If not specified defaults to
<literal>ext4</literal>. This setting has no effect if a different storage mechanism is used. The
file system type selected on the <command>homectl</command> command line always takes
precedence.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

4
man/hostnamectl.xml
View File

@ -57,7 +57,7 @@
<para>Use
<citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
to initialize the system host name for mounted (but not booted)
to initialize the system hostname for mounted (but not booted)
system images.</para>
</refsect1>
@ -84,7 +84,7 @@
simplified in regards to the character set used before the latter are updated. This is done by removing special
characters and spaces. This ensures that the pretty and the static hostname are always closely related while
still following the validity rules of the specific name. This simplification of the hostname string is not done
if only the transient and/or static host names are set, and the pretty host name is left untouched.</para>
if only the transient and/or static hostnames are set, and the pretty hostname is left untouched.</para>
<para>Pass the empty string <literal></literal> as the
hostname to reset the selected hostnames to their default

3
man/html.in
View File

@ -6,6 +6,9 @@ if [ -z "$1" ]; then
exit 1
fi
# make sure the rules have been regenerated (in case man/update-man-rules was just run)
ninja -C "@BUILD_ROOT@" version.h
target="man/$1.html"
ninja -C "@BUILD_ROOT@" "$target"
set -x

28
man/hwdb-usb-device.c Normal file
View File

@ -0,0 +1,28 @@
#include <stdio.h>
#include <stdint.h>
#include <sd-hwdb.h>
int print_usb_properties(uint16_t vid, uint16_t pid) {
char match[15];
sd_hwdb *hwdb;
const char *key, *value;
int r;
/* Match this USB vendor and product ID combination */
snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);
r = sd_hwdb_new(&hwdb);
if (r < 0)
return r;
SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
printf("%s: \"%s\" → \"%s\"\n", match, key, value);
sd_hwdb_unref(hwdb);
return 0;
}
int main(int argc, char **argv) {
print_usb_properties(0x046D, 0xC534);
return 0;
}

4
man/journal-remote.conf.xml
View File

@ -39,7 +39,7 @@
<para>These files configure various parameters of
<citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
See
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for a general description of the syntax.</para>
</refsect1>
@ -49,7 +49,7 @@
<title>Options</title>
<para>All options are configured in the
<literal>[Remote]</literal> section:</para>
[Remote] section:</para>
<variablelist class='config-directives'>
<varlistentry>

4
man/journal-upload.conf.xml
View File

@ -34,7 +34,7 @@
<para>These files configure various parameters of
<citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
See
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for a general description of the syntax.</para>
</refsect1>
@ -43,7 +43,7 @@
<refsect1>
<title>Options</title>
<para>All options are configured in the <literal>[Upload]</literal> section:</para>
<para>All options are configured in the [Upload] section:</para>
<variablelist class='config-directives'>
<varlistentry>

34
man/journalctl.xml
View File

@ -374,9 +374,10 @@
<option>cat</option>
</term>
<listitem>
<para>generates a very terse output, only showing the
actual message of each journal entry with no metadata,
not even a timestamp.</para>
<para>generates a very terse output, only showing the actual message of each journal entry
with no metadata, not even a timestamp. If combined with the
<option>--output-fields=</option> option will output the listed fields for each log record,
instead of the message.</para>
</listitem>
</varlistentry>
@ -398,10 +399,11 @@
<varlistentry>
<term><option>--output-fields=</option></term>
<listitem><para>A comma separated list of the fields which should be included in the output. This has an
effect only for the output modes which would normally show all fields (<option>verbose</option>,
<option>export</option>, <option>json</option>, <option>json-pretty</option>, <option>json-sse</option> and
<option>json-seq</option>). The <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>,
<listitem><para>A comma separated list of the fields which should be included in the output. This has
an effect only for the output modes which would normally show all fields (<option>verbose</option>,
<option>export</option>, <option>json</option>, <option>json-pretty</option>,
<option>json-sse</option> and <option>json-seq</option>), as well as on <option>cat</option>. For the
former, the <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>,
<literal>__MONOTONIC_TIMESTAMP</literal>, and <literal>_BOOT_ID</literal> fields are always
printed.</para></listitem>
</varlistentry>
@ -553,7 +555,7 @@
is also added for <literal>_SYSTEMD_SLICE=<replaceable>UNIT</replaceable></literal>,
such that if the provided <replaceable>UNIT</replaceable> is a
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
unit, all logs of the children of the slice will be logged.
unit, all logs of children of the slice will be shown.
</para>
<para>This parameter can be specified multiple times.</para>
@ -572,7 +574,7 @@
is also added for <literal>_SYSTEMD_USER_SLICE=<replaceable>UNIT</replaceable></literal>,
such that if the provided <replaceable>UNIT</replaceable> is a
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
unit, all logs of the children of the unit will be logged.</para>
unit, all logs of children of the unit will be shown.</para>
<para>This parameter can be specified multiple times.</para>
</listitem>
@ -619,7 +621,7 @@
<listitem><para>Filter output to entries where the <varname>MESSAGE=</varname>
field matches the specified regular expression. PERL-compatible regular expressions
are used, see
<citerefentry><refentrytitle>pcre2pattern</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry project='url'><refentrytitle url='http://pcre.org/current/doc/html/pcre2pattern.html'>pcre2pattern</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for a detailed description of the syntax.</para>
<para>If the pattern is all lowercase, matching is case insensitive.
@ -631,7 +633,7 @@
<varlistentry>
<term><option>--case-sensitive<optional>=BOOLEAN</optional></option></term>
<listitem><para>Make pattern matching case sensitive or case insenstive.</para>
<listitem><para>Make pattern matching case sensitive or case insensitive.</para>
</listitem>
</varlistentry>
@ -759,8 +761,8 @@
underneath the specified directory instead of the root
directory (e.g. <option>--update-catalog</option> will create
<filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>,
and journal files under <filename><replaceable>ROOT</replaceable>/run/journal</filename>
or <filename><replaceable>ROOT</replaceable>/var/log/journal</filename> will be displayed).
and journal files under <filename><replaceable>ROOT</replaceable>/run/journal/</filename>
or <filename><replaceable>ROOT</replaceable>/var/log/journal/</filename> will be displayed).
</para></listitem>
</varlistentry>
@ -927,10 +929,10 @@
<filename>/run/log/journal/</filename> into <filename>/var/log/journal/</filename>, if persistent
storage is enabled. This call does not return until the operation is complete. Note that this call is
idempotent: the data is only flushed from <filename>/run/log/journal/</filename> into
<filename>/var/log/journal</filename> once during system runtime (but see
<filename>/var/log/journal/</filename> once during system runtime (but see
<option>--relinquish-var</option> below), and this command exits cleanly without executing any
operation if this has already happened. This command effectively guarantees that all data is flushed
to <filename>/var/log/journal</filename> at the time it returns.</para></listitem>
to <filename>/var/log/journal/</filename> at the time it returns.</para></listitem>
</varlistentry>
<varlistentry>
@ -1020,7 +1022,7 @@ journalctl _SYSTEMD_CGROUP=/user.slice/user-42.slice/session-c1.scope</programli
+ OBJECT_SYSTEMD_UNIT=<replaceable>name</replaceable>.service _UID=0
+ COREDUMP_UNIT=<replaceable>name</replaceable>.service _UID=0 MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
</programlisting>
(see <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>5</manvolnum></citerefentry>
(see <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for an explanation of those patterns).
</para>

4
man/journald.conf.xml
View File

@ -36,7 +36,7 @@
<para>These files configure various parameters of the systemd journal service,
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
See
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for a general description of the syntax.</para>
<para>The <command>systemd-journald</command> instance managing the default namespace is configured by
@ -53,7 +53,7 @@
<title>Options</title>
<para>All options are configured in the
<literal>[Journal]</literal> section:</para>
[Journal] section:</para>
<variablelist class='config-directives'>

73
man/kernel-command-line.xml
View File

@ -109,7 +109,7 @@
<para>During early boot, the generation of core dump files is disabled until a core dump handler (if any)
takes over. This parameter allows specifying an absolute path where core dump files should be stored until
a handler is installed. The path should be absolute and may contain specifiers, see
<citerefentry><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para>
<citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para>
</listitem>
</varlistentry>
@ -271,6 +271,10 @@
<term><varname>rd.udev.exec_delay=</varname></term>
<term><varname>udev.event_timeout=</varname></term>
<term><varname>rd.udev.event_timeout=</varname></term>
<term><varname>udev.timeout_signal=</varname></term>
<term><varname>rd.udev.timeout_signal=</varname></term>
<term><varname>udev.blockdev_read_only</varname></term>
<term><varname>rd.udev.blockdev_read_only</varname></term>
<term><varname>net.ifnames=</varname></term>
<term><varname>net.naming-scheme=</varname></term>
@ -433,8 +437,71 @@
<listitem><para>Takes a boolean argument, defaults to on. If off,
<citerefentry><refentrytitle>systemd-firstboot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
will not query the user for basic system settings, even if the system boots up for the first time and the
relevant settings are not initialized yet.</para></listitem>
will not query the user for basic system settings, even if the system boots up for the first time and
the relevant settings are not initialized yet. Not to be confused with
<varname>systemd.condition-first-boot=</varname> (see below), which overrides the result of the
<varname>ConditionFirstBoot=</varname> unit file condition, and thus controls more than just
<filename>systemd-firstboot.service</filename> behaviour.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.condition-needs-update=</varname></term>
<listitem><para>Takes a boolean argument. If specified, overrides the result of
<varname>ConditionNeedsUpdate=</varname> unit condition checks. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.condition-first-boot=</varname></term>
<listitem><para>Takes a boolean argument. If specified, overrides the result of
<varname>ConditionFirstBoot=</varname> unit condition checks. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details. Not to be confused with <varname>systemd.firstboot=</varname> which only controls behaviour
of the <filename>systemd-firstboot.service</filename> system service but has no effect on the
condition check (see above).</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.clock-usec=</varname></term>
<listitem><para>Takes a decimal, numeric timestamp in µs since January 1st 1970, 00:00am, to set the
system clock to. The system time is set to the specified timestamp early during boot. It is not
propagated to the hardware clock (RTC).</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.random-seed=</varname></term>
<listitem><para>Takes a base64 encoded random seed value to credit with full entropy to the kernel's
random pool during early service manager initialization. This option is useful in testing
environments where delays due to random pool initialization in entropy starved virtual machines shall
be avoided.</para>
<para>Note that if this option is used the seed is accessible to unprivileged programs from
<filename>/proc/cmdline</filename>. This option is hence a security risk when used outside of test
systems, since the (possibly) only seed used for initialization of the kernel's entropy pool might be
easily acquired by unprivileged programs.</para>
<para>It is recommended to pass 512 bytes of randomized data (as that matches the Linux kernel pool
size), which may be generated with a command like the following:</para>
<programlisting>dd if=/dev/urandom bs=512 count=1 status=none | base64 -w 0</programlisting>
<para>Again: do not use this option outside of testing environments, it's a security risk elsewhere,
as secret key material derived from the entropy pool can possibly be reconstructed by unprivileged
programs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.hostname=</varname></term>
<listitem><para>Accepts a hostname to set during early boot. If specified takes precedence over what
is set in <filename>/etc/hostname</filename>. Note that this does not bar later runtime changes to
the hostname, it simply controls the initial hostname set during early boot.</para></listitem>
</varlistentry>
</variablelist>

8
man/kernel-install.xml
View File

@ -36,7 +36,7 @@
<title>Description</title>
<para><command>kernel-install</command> is used to install and remove kernel and initramfs images to and
from the boot loader partition, referred to as <varname>$BOOT</varname> here. It will usually be one of
<filename>/boot</filename>, <filename>/efi</filename>, or <filename>/boot/efi</filename>, see below.
<filename>/boot/</filename>, <filename>/efi/</filename>, or <filename>/boot/efi/</filename>, see below.
</para>
<para><command>kernel-install</command> will execute the files
@ -80,7 +80,7 @@
</para></listitem>
<listitem><para><filename>50-depmod.install</filename> runs
<citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
<citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
<replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
<listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable>
@ -137,7 +137,7 @@
<para>The partition where the kernels and <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>.
<command>kernel-install</command> determines the location of this partition by checking
<filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi</filename>
<filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi/</filename>
in turn. The first location where <filename>$BOOT/loader/entries/</filename> or
<filename>$BOOT/$MACHINE_ID/</filename> exists is used.</para>
</refsect1>
@ -231,7 +231,7 @@
<para>
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
</para>

2
man/loader.conf.xml
View File

@ -165,7 +165,7 @@
variable is set, and then derive the random seed to pass to the OS from the combination. If
<literal>always</literal> the boot loader will do so even if <varname>LoaderSystemToken</varname> is
not set. This mode is useful in environments where protection against OS image reuse is not a
concern, and the random seed shall be used even with no further setup in place. User <command>bootctl
concern, and the random seed shall be used even with no further setup in place. Use <command>bootctl
random-seed</command> to initialize both the random seed file in the ESP and the system token EFI
variable.</para>

19
man/logind.conf.xml
View File

@ -36,7 +36,7 @@
<para>These files configure various parameters of the systemd login manager,
<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. See
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for a general description of the syntax.</para>
</refsect1>
@ -46,7 +46,7 @@
<title>Options</title>
<para>All options are configured in the
<literal>[Login]</literal> section:</para>
[Login] section:</para>
<variablelist class='config-directives'>
@ -277,7 +277,7 @@
<varlistentry>
<term><varname>HoldoffTimeoutSec=</varname></term>
<listitem><para>Specifies the timeout after system startup or
<listitem><para>Specifies a period of time after system startup or
system resume in which systemd will hold off on reacting to
lid events. This is required for the system to properly
detect any hotplugged devices so systemd can ignore lid events
@ -304,6 +304,19 @@
memory as is needed.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>RuntimeDirectoryInodesMax=</varname></term>
<listitem><para>Sets the limit on number of inodes for the
<varname>$XDG_RUNTIME_DIR</varname> runtime directory for each
user who logs in. Takes a number, optionally suffixed with the
usual K, G, M, and T suffixes, to the base 1024 (IEC).
Defaults to <varname>RuntimeDirectorySize=</varname> divided
by 4096. Note that this size is a safety limit only.
As each runtime directory is a tmpfs file system, it will
only consume as much memory as is needed.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>InhibitorsMax=</varname></term>

2
man/machine-id.xml
View File

@ -39,7 +39,7 @@
<para>The machine ID may be set, for example when network booting, with the
<varname>systemd.machine_id=</varname> kernel command line parameter or by passing the
option <option>--machine-id=</option> to systemd. An ID is specified in this manner
option <option>--machine-id=</option> to systemd. An ID specified in this manner
has higher priority and will be used instead of the ID stored in
<filename>/etc/machine-id</filename>.</para>

2
man/machine-info.xml
View File

@ -70,7 +70,7 @@
<literal>Lennart's Computer</literal> an Internet hostname of
<literal>lennarts-computer</literal> might be a good choice.
If this parameter is not set, an application should fall back
to the Internet host name for presentation
to the Internet hostname for presentation
purposes.</para></listitem>
</varlistentry>

8
man/machinectl.xml
View File

@ -56,7 +56,7 @@
</itemizedlist>
<para>Machines are identified by names that follow the same rules
as UNIX and DNS host names. For details, see below.</para>
as UNIX and DNS hostnames. For details, see below.</para>
<para>Machines are instantiated from disk or file system images that
frequently — but not necessarily — carry the same name as machines running
@ -320,7 +320,7 @@
<listitem><para>Copies files or directories from a container
into the host system. Takes a container name, followed by the
source path in the container the destination path on the host.
source path in the container and the destination path on the host.
If the destination path is omitted, the same as the source path
is used.</para>
@ -383,7 +383,7 @@
image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
file system limitations.</para>
<para>Note that this command leaves host name, machine ID and
<para>Note that this command leaves hostname, machine ID and
all other settings that could identify the instance
unmodified. The original image and the cloned copy will hence
share these credentials, and it might be necessary to manually
@ -851,7 +851,7 @@
<para>The <command>machinectl</command> tool operates on machines
and images whose names must be chosen following strict
rules. Machine names must be suitable for use as host names
rules. Machine names must be suitable for use as hostnames
following a conservative subset of DNS and UNIX/Linux
semantics. Specifically, they must consist of one or more
non-empty label strings, separated by dots. No leading or trailing

3
man/man.in
View File

@ -6,6 +6,9 @@ if [ -z "$1" ]; then
exit 1
fi
# make sure the rules have been regenerated (in case man/update-man-rules was just run)
ninja -C "@BUILD_ROOT@" version.h
page="$(echo "$1" | sed 's/\./\\./')"
target=$(ninja -C "@BUILD_ROOT@" -t query man/man | grep -E -m1 "man/$page\.[0-9]$" | awk '{print $2}')
if [ -z "$target" ]; then

26
man/meson.build
View File

@ -34,6 +34,7 @@ custom_entities_ent = configure_file(
man_pages = []
html_pages = []
source_xml_files = []
dbus_docs = []
foreach tuple : xsltproc.found() ? manpages : []
stem = tuple[0]
section = tuple[1]
@ -90,7 +91,11 @@ foreach tuple : xsltproc.found() ? manpages : []
install_dir : join_paths(docdir, 'html'))
html_pages += p3
source_xml_files += files(tuple[0] + '.xml')
file = files(tuple[0] + '.xml')
source_xml_files += file
if tuple[0].startswith('org.freedesktop.')
dbus_docs += file
endif
else
message('Skipping @0@.@1@ because @2@ is false'.format(stem, section, condition))
endif
@ -105,9 +110,9 @@ endif
systemd_directives_xml = custom_target(
'systemd.directives.xml',
input : source_xml_files,
input : ['directives-template.xml', source_xml_files],
output : 'systemd.directives.xml',
command : [make_directive_index_py, '@OUTPUT@'] + source_xml_files)
command : [make_directive_index_py, '@OUTPUT@', '@INPUT@'])
nonindex_xml_files = source_xml_files + [systemd_directives_xml]
systemd_index_xml = custom_target(
@ -193,13 +198,26 @@ run_target(
############################################################
if dbus_docs.length() > 0
custom_target(
'update-dbus-docs',
output : 'update-dbus-docs',
command : ['python3',
'@0@/tools/update-dbus-docs.py'.format(project_source_root),
'--build-dir=@0@'.format(project_build_root),
'@INPUT@'],
input : dbus_docs)
endif
############################################################
if git.found()
custom_target(
'update-man-rules',
output : 'update-man-rules',
command : ['sh', '-c',
'cd @0@ && '.format(meson.build_root()) +
'python3 @0@/tools/make-man-rules.py $(git ls-files ":/man/*.xml") >t && '.format(project_source_root) +
'python3 @0@/tools/update-man-rules.py $(git ls-files ":/man/*.xml") >t && '.format(project_source_root) +
'mv t @0@/rules/meson.build'.format(meson.current_source_dir())],
depend_files : custom_entities_ent)
endif

24
man/networkctl.xml
View File

@ -233,7 +233,7 @@ s - Service VLAN, m - Two-port MAC Relay (TPMR)
<listitem><para>Show numerical address labels that can be used for address selection.
This is the same information that
<citerefentry><refentrytitle>ip-addrlabel</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry project='die-net'><refentrytitle>ip-addrlabel</refentrytitle><manvolnum>8</manvolnum></citerefentry>
shows. See <ulink url="https://tools.ietf.org/html/rfc3484">RFC 3484</ulink>
for a discussion of address labels.</para>
@ -259,6 +259,20 @@ s - Service VLAN, m - Two-port MAC Relay (TPMR)
<listitem><para>Deletes virtual netdevs. Takes interface name or index number.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>up</command>
</term>
<listitem><para>Bring devices up. Takes interface name or index number.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>down</command>
</term>
<listitem><para>Bring devices down. Takes interface name or index number.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>renew</command>
@ -267,6 +281,14 @@ s - Service VLAN, m - Two-port MAC Relay (TPMR)
Takes interface name or index number.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>forcerenew</command>
</term>
<listitem><para>Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration.
Takes interface name or index number.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>reconfigure</command>

11
man/networkd.conf.xml
View File

@ -45,7 +45,7 @@
<refsect1>
<title>[Network] Section Options</title>
<para>The following options are available in the <literal>[Network]</literal> section:</para>
<para>The following options are available in the [Network] section:</para>
<variablelist class='network-directives'>
<varlistentry>
@ -61,6 +61,15 @@
<listitem><para>Specifies the time interval to calculate the traffic speed of each interface.
If <varname>SpeedMeter=no</varname>, the value is ignored. Defaults to 10sec.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ManageForeignRoutes=</varname></term>
<listitem><para>A boolean. When true, <command>systemd-networkd</command> will store any routes
configured by other tools in its memory. When false, <command>systemd-networkd</command> will
not manage the foreign routes, thus they are kept even if <varname>KeepConfiguration=</varname>
is false. Defaults to yes.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>

22
man/nss-myhostname.xml
View File

@ -18,8 +18,7 @@
<refnamediv>
<refname>nss-myhostname</refname>
<refname>libnss_myhostname.so.2</refname>
<refpurpose>Provide hostname resolution for the locally
configured system hostname.</refpurpose>
<refpurpose>Hostname resolution for the locally configured system hostname</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -67,9 +66,13 @@
<para>To activate the NSS modules, add <literal>myhostname</literal> to the line starting with
<literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para>
<para>It is recommended to place <literal>myhostname</literal> last in the <filename>nsswitch.conf</filename>'
<literal>hosts:</literal> line to make sure that this mapping is only used as fallback, and that any DNS or
<filename>/etc/hosts</filename> based mapping takes precedence.</para>
<para>It is recommended to place <literal>myhostname</literal> either between <literal>resolve</literal>
and "traditional" modules like <literal>files</literal> and <literal>dns</literal>, or after them. In the
first version, well-known names like <literal>localhost</literal> and the machine hostname are given
higher priority than the external configuration. This is recommended when the external DNS servers and
network are not absolutely trusted. In the second version, external configuration is given higher
priority and <command>nss-myhostname</command> only provides a fallback mechanism. This might be suitable
in closely controlled networks, for example on a company LAN.</para>
</refsect1>
<refsect1>
@ -79,11 +82,14 @@
<command>nss-myhostname</command> correctly:</para>
<!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
<programlisting>passwd: compat mymachines systemd
group: compat mymachines systemd
<programlisting>passwd: compat systemd
group: compat systemd
shadow: compat
hosts: files mymachines resolve [!UNAVAIL=return] dns <command>myhostname</command>
# Either (untrusted network):
hosts: mymachines resolve [!UNAVAIL=return] <command>myhostname</command> files dns
# Or (only trusted networks):
hosts: mymachines resolve [!UNAVAIL=return] files dns <command>myhostname</command>
networks: files
protocols: db files

53
man/nss-mymachines.xml
View File

@ -18,8 +18,7 @@
<refnamediv>
<refname>nss-mymachines</refname>
<refname>libnss_mymachines.so.2</refname>
<refpurpose>Provide hostname resolution for local
container instances.</refpurpose>
<refpurpose>Hostname resolution for local container instances</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -40,22 +39,13 @@
Note that the name that is resolved is the one registered with <command>systemd-machined</command>, which
may be different than the hostname configured inside of the container.</para>
<para>The module also provides name resolution for user and group identifiers mapped to containers. All names from
the range allocated to a given container <replaceable>container</replaceable> are exposed on the host as
<literal>vu-<replaceable>container</replaceable>-<replaceable>uid</replaceable></literal> and
<literal>vg-<replaceable>container</replaceable>-<replaceable>gid</replaceable></literal> (see example below). This
functionality only applies to containers using user namespacing (see the description of
<option>--private-users</option> in
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
<para>To activate the NSS module, add <literal>mymachines</literal> to the lines starting with
<literal>hosts:</literal>, <literal>passwd:</literal> and <literal>group:</literal> in
<filename>/etc/nsswitch.conf</filename>.</para>
<para>To activate the NSS module, add <literal>mymachines</literal> to the line starting with
<literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para>
<para>It is recommended to place <literal>mymachines</literal> after the <literal>files</literal> or
<literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines to make sure that its mappings
are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>,
<filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para>
<literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> line to make sure that its
mappings are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>
based mappings take precedence.</para>
</refsect1>
<refsect1>
@ -65,11 +55,11 @@
<command>nss-mymachines</command> correctly:</para>
<!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
<programlisting>passwd: compat <command>mymachines</command> systemd
group: compat <command>mymachines</command> systemd
<programlisting>passwd: compat systemd
group: compat systemd
shadow: compat
hosts: files <command>mymachines</command> resolve [!UNAVAIL=return] dns myhostname
hosts: <command>mymachines</command> resolve [!UNAVAIL=return] myhostname files dns
networks: files
protocols: db files
@ -82,7 +72,7 @@ netgroup: nis</programlisting>
</refsect1>
<refsect1>
<title>Mappings provided by <filename>nss-mymachines</filename></title>
<title>Example: Mappings provided by <filename>nss-mymachines</filename></title>
<para>The container <literal>rawhide</literal> is spawned using
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>:
@ -97,29 +87,6 @@ $ machinectl --max-addresses=3
MACHINE CLASS SERVICE OS VERSION ADDRESSES
rawhide container systemd-nspawn fedora 30 169.254.40.164 fe80::94aa:3aff:fe7b:d4b9
$ getent passwd vu-rawhide-0 vu-rawhide-81
vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin
vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin
$ getent group vg-rawhide-0 vg-rawhide-81
vg-rawhide-0:*:20119552:
vg-rawhide-81:*:20119633:
$ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide'
vu-rawhide-0 692 ? /usr/lib/systemd/systemd
vu-rawhide-0 731 ? /usr/lib/systemd/systemd-journald
vu-rawhide-192 734 ? /usr/lib/systemd/systemd-networkd
vu-rawhide-193 738 ? /usr/lib/systemd/systemd-resolved
vu-rawhide-0 742 ? /usr/lib/systemd/systemd-logind
vu-rawhide-81 744 ? /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
vu-rawhide-0 746 ? /usr/sbin/sshd -D ...
vu-rawhide-0 752 ? /usr/lib/systemd/systemd --user
vu-rawhide-0 753 ? (sd-pam)
vu-rawhide-0 1628 ? login -- zbyszek
vu-rawhide-1000 1630 ? /usr/lib/systemd/systemd --user
vu-rawhide-1000 1631 ? (sd-pam)
vu-rawhide-1000 1637 pts/8 -zsh
$ ping -c1 rawhide
PING rawhide(fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide)) 56 data bytes
64 bytes from fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide): icmp_seq=1 ttl=64 time=0.045 ms

27
man/nss-resolve.xml
View File

@ -18,7 +18,7 @@
<refnamediv>
<refname>nss-resolve</refname>
<refname>libnss_resolve.so.2</refname>
<refpurpose>Provide hostname resolution via <filename>systemd-resolved.service</filename></refpurpose>
<refpurpose>Hostname resolution via <filename>systemd-resolved.service</filename></refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -29,19 +29,20 @@
<title>Description</title>
<para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
GNU C Library (<command>glibc</command>) enabling it to resolve host names via the
GNU C Library (<command>glibc</command>) enabling it to resolve hostnames via the
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network
name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves
hostnames via DNS.</para>
<para>To activate the NSS module, add <literal>resolve</literal> to the line starting with
<literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>. Specifically, it is recommended to place
<literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>'s <literal>hosts:</literal> line (but
after the <literal>files</literal> or <literal>mymachines</literal> entries), right before the
<literal>dns</literal> entry if it exists, followed by <literal>[!UNAVAIL=return]</literal>, to ensure DNS queries
are always routed via
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> if it is
running, but are routed to <command>nss-dns</command> if this service is not available.</para>
<para>To activate the NSS module, add <literal>resolve [!UNAVAIL=return]</literal> to the line starting
with <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>. Specifically, it is
recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>'s
<literal>hosts:</literal> line. It should be before the <literal>files</literal> entry, since
<filename>systemd-resolved</filename> supports <filename>/etc/hosts</filename> internally, but with
caching. To the contrary, it should be after <literal>mymachines</literal>, to give hostnames given to
local VMs and containers precedence over names received over DNS. Finally, we recommend placing
<literal>dns</literal> somewhere after <literal>resolve</literal>, to fall back to
<command>nss-dns</command> if <filename>systemd-resolved.service</filename> is not available.</para>
<para>Note that <command>systemd-resolved</command> will synthesize DNS resource
records in a few cases, for example for <literal>localhost</literal> and the
@ -62,11 +63,11 @@
correctly:</para>
<!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
<programlisting>passwd: compat mymachines systemd
group: compat mymachines systemd
<programlisting>passwd: compat systemd
group: compat systemd
shadow: compat
hosts: files mymachines <command>resolve [!UNAVAIL=return]</command> dns myhostname
hosts: mymachines <command>resolve [!UNAVAIL=return]</command> myhostname files dns
networks: files
protocols: db files

58
man/nss-systemd.xml
View File

@ -18,7 +18,7 @@
<refnamediv>
<refname>nss-systemd</refname>
<refname>libnss_systemd.so.2</refname>
<refpurpose>Provide UNIX user and group name resolution for user/group lookup via Varlink</refpurpose>
<refpurpose>UNIX user and group name resolution for user/group lookup via Varlink</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -35,8 +35,8 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> (for its
<varname>DynamicUser=</varname> feature, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details) or
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
details),
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<para>This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs
0 and 65534) remain resolvable at all times, even if they aren't listed in <filename>/etc/passwd</filename> or
@ -55,17 +55,17 @@
</refsect1>
<refsect1>
<title>Example</title>
<title>Configuration in <filename>/etc/nsswitch.conf</filename></title>
<para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
<command>nss-systemd</command> correctly:</para>
<!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
<programlisting>passwd: compat mymachines <command>systemd</command>
group: compat [SUCCESS=merge] mymachines [SUCCESS=merge] <command>systemd</command>
<programlisting>passwd: compat <command>systemd</command>
group: compat [SUCCESS=merge] <command>systemd</command>
shadow: compat
hosts: files mymachines resolve [!UNAVAIL=return] dns myhostname
hosts: mymachines resolve [!UNAVAIL=return] myhostname files dns
networks: files
protocols: db files
@ -77,6 +77,47 @@ netgroup: nis</programlisting>
</refsect1>
<refsect1>
<title>Example: Mappings provided by <filename>systemd-machined.service</filename></title>
<para>The container <literal>rawhide</literal> is spawned using
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>:
</para>
<programlisting># systemd-nspawn -M rawhide --boot --network-veth --private-users=pick
Spawning container rawhide on /var/lib/machines/rawhide.
Selected user namespace base 20119552 and range 65536.
...
$ machinectl --max-addresses=3
MACHINE CLASS SERVICE OS VERSION ADDRESSES
rawhide container systemd-nspawn fedora 30 169.254.40.164 fe80::94aa:3aff:fe7b:d4b9
$ getent passwd vu-rawhide-0 vu-rawhide-81
vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin
vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin
$ getent group vg-rawhide-0 vg-rawhide-81
vg-rawhide-0:*:20119552:
vg-rawhide-81:*:20119633:
$ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide'
vu-rawhide-0 692 ? /usr/lib/systemd/systemd
vu-rawhide-0 731 ? /usr/lib/systemd/systemd-journald
vu-rawhide-192 734 ? /usr/lib/systemd/systemd-networkd
vu-rawhide-193 738 ? /usr/lib/systemd/systemd-resolved
vu-rawhide-0 742 ? /usr/lib/systemd/systemd-logind
vu-rawhide-81 744 ? /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
vu-rawhide-0 746 ? /usr/sbin/sshd -D ...
vu-rawhide-0 752 ? /usr/lib/systemd/systemd --user
vu-rawhide-0 753 ? (sd-pam)
vu-rawhide-0 1628 ? login -- zbyszek
vu-rawhide-1000 1630 ? /usr/lib/systemd/systemd --user
vu-rawhide-1000 1631 ? (sd-pam)
vu-rawhide-1000 1637 pts/8 -zsh
</programlisting>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
@ -85,6 +126,9 @@ netgroup: nis</programlisting>
<citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>

106
man/org.freedesktop.LogControl1.xml Normal file
View File

@ -0,0 +1,106 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.LogControl1"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.LogControl1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.LogControl1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.LogControl1</refname>
<refpurpose>D-Bus interface to query and set logging configuration</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para><interfacename>org.freedesktop.LogControl1</interfacename> is a generic interface that is intended
to be used by any daemon which should allow setting the log level and target over D-Bus. It is implemented
by various daemons that are part of the
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> suite.</para>
<para>It is assumed that those settings are global for the whole program, so a fixed object path is
used. The interface should always be available under the path
<filename>/org/freedesktop/LogControl1</filename>.</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>The following interface is exposed:</para>
<programlisting executable="systemd" node="/org/freedesktop/LogControl1" interface="org.freedesktop.LogControl1">
node /org/freedesktop/LogControl1 {
interface org.freedesktop.LogControl1 {
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite s LogLevel = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite s LogTarget = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s SyslogIdentifier = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.LogControl1"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.LogControl1"/>
<variablelist class="dbus-property" generated="True" extra-ref="LogLevel"/>
<variablelist class="dbus-property" generated="True" extra-ref="LogTarget"/>
<variablelist class="dbus-property" generated="True" extra-ref="SyslogIdentifier"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Properties</title>
<para><varname>LogLevel</varname> describes the
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>-style
log-level, and should be one of <literal>emerg</literal>, <literal>alert</literal>,
<literal>crit</literal>, <literal>err</literal>, <literal>warning</literal>, <literal>notice</literal>,
<literal>info</literal>, <literal>debug</literal>, in order of increasing verbosity.</para>
<para><varname>LogTarget</varname> describes the log target (mechanism). It should be one of
<literal>console</literal> (log to the console or standard output),
<literal>kmsg</literal> (log to the kernel ring buffer),
<literal>journal</literal> (log to the journal natively, see
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
<literal>syslog</literal> (log using the
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call).
</para>
<para>Those two properties are writable, so they may be set by sufficiently privileged users.</para>
<para><varname>SyslogIdentifier</varname> is a read-only property that shows the "syslog identifier".
It is a short string that identifies the program that is the source of log messages that is passed to
the <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call.
</para>
<para>Note: <command>journalctl</command> option <option>-p</option>/<option>--priority=</option> may
be used to filter log messages by log level, option <option>-t</option>/<option>--identifier=</option>
may be used to by the syslog identifier, and filters like <literal>_TRANSPORT=syslog</literal>,
<literal>_TRANSPORT=journal</literal>, and <literal>_TRANSPORT=kernel</literal> may be used to filter
messages by the mechanism through which they reached <command>systemd-journald</command>.</para>
</refsect2>
</refsect1>
</refentry>

502
man/org.freedesktop.home1.xml Normal file
View File

@ -0,0 +1,502 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.home1" conditional='ENABLE_HOMED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.home1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.home1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.home1</refname>
<refpurpose>The D-Bus interface of systemd-homed</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service which may be used to create, remove, change or inspect home areas. This page
describes the D-Bus interface.
</para>
</refsect1>
<refsect1>
<title>The Manager Object</title>
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
<programlisting executable="systemd-homed" node="/org/freedesktop/home1" interface="org.freedesktop.home1.Manager">
node /org/freedesktop/home1 {
interface org.freedesktop.home1.Manager {
methods:
GetHomeByName(in s user_name,
out u uid,
out s home_state,
out u gid,
out s real_name,
out s home_directory,
out s shell,
out o bus_path);
GetHomeByUID(in u uid,
out s user_name,
out s home_state,
out u gid,
out s real_name,
out s home_directory,
out s shell,
out o bus_path);
GetUserRecordByName(in s user_name,
out s user_record,
out b incomplete,
out o bus_path);
GetUserRecordByUID(in u uid,
out s user_record,
out b incomplete,
out o bus_path);
ListHomes(out a(susussso) home_areas);
ActivateHome(in s user_name,
in s secret);
DeactivateHome(in s user_name);
RegisterHome(in s user_record);
UnregisterHome(in s user_name);
CreateHome(in s user_record);
RealizeHome(in s user_name,
in s secret);
RemoveHome(in s user_name);
FixateHome(in s user_name,
in s secret);
AuthenticateHome(in s user_name,
in s secret);
UpdateHome(in s user_record);
ResizeHome(in s user_name,
in t size,
in s secret);
ChangePasswordHome(in s user_name,
in s new_secret,
in s old_secret);
LockHome(in s user_name);
UnlockHome(in s user_name,
in s secret);
AcquireHome(in s user_name,
in s secret,
in b please_suspend,
out h send_fd);
RefHome(in s user_name,
in b please_suspend,
out h send_fd);
ReleaseHome(in s user_name);
LockAllHomes();
properties:
readonly a(sso) AutoLogin = [...];
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetHomeByName()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetHomeByUID()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByName()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByUID()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListHomes()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ActivateHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="DeactivateHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RegisterHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="UnregisterHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CreateHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RealizeHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RemoveHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="FixateHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="AuthenticateHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="UpdateHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResizeHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ChangePasswordHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="LockHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="UnlockHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="AcquireHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RefHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/>
<variablelist class="dbus-method" generated="True" extra-ref="LockAllHomes()"/>
<variablelist class="dbus-property" generated="True" extra-ref="AutoLogin"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para><function>GetHomeByName()</function> returns basic user information (a minimal subset of the full
user record), provided a user name. The information supplied more or less matches what
<citerefentry project='man-pages'><refentrytitle>getpwnam</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns:
the numeric UID and GID, the real name, home directory and shell. In addition it returns a state
identifier describing the state the user's home directory is in, as well as a bus path referring to the
bus object encapsulating the user record and home directory. This object implements the
<classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
<para><function>GetHomeByUID()</function> is similar to <function>GetHomeByName()</function> but
acquires the information based on the numeric UID of the user.</para>
<para><function>GetUserRecordByName()</function> is also similar to
<function>GetHomeByName()</function> but returns the full JSON user record data instead of the broken
down records. An additional returned boolean indicates whether the record is complete or not. A record
is considered complete when its <literal>privileged</literal> section is included, and incomplete if it
was removed (see <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink> for details
about the various sections of a user record). Generally, only privileged clients and clients running
under the identity of the user itself get access to the <literal>privileged</literal> section and will
thus see complete records.</para>
<para><function>GetUserRecordByUID()</function> is similar to <function>GetUserRecordByName()</function>
but returns the user record matching the specified numeric UID.</para>
<para><function>ListHomes()</function> returns an array of all locally managed users. The array
contains the same fields <function>GetHomeByName()</function> returns: user name, numeric UID, state,
numeric GID, real name, home directory, shell and bus path of the matching bus object.</para>
<para><function>ActivateHome()</function> activates (i.e. mounts) the home directory of the specified
user. The second argument shall contain a user record consisting only of a <literal>secret</literal>
section (all other sections should be stripped, see <ulink url="https://systemd.io/USER_RECORD">JSON
User Records</ulink> for details), and should contain only the secret credentials necessary for
unlocking the home directory. Typically a client would invoke this function first with an entirely
empty record (which is possibly sufficient if single-factor authentication with a plugged-in security
token is configured), and would then retry with a record populated with more information, depending on
the returned error code, in case more credentials are necessary. This function is synchronous and
returns only after the home directory was fully activated (or the operation failed), which might take
some time. Clients must be prepared for that, and typically should extend the D-Bus method call
timeout accordingly. This method is equivalent to the <function>Activate()</function> method on the
<classname>org.freedesktop.home1.Home</classname> interface documented below, but may be called on the
manager object and takes a user name as additional argument, instead.</para>
<para><function>DeactivateHome()</function> deactivates (i.e. unmounts) the home directory of the
specified user. It is equivalent to the <function>Deactivate()</function> method on the
<classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
<para><function>RegisterHome()</function> registers a new home directory locally. It receives the JSON
user record as only argument (which typically excludes the <literal>secret</literal>
section). Registering a home directory just makes the user record known to the system, it does not
create a home directory or such (which is expected to exist already, or created later). This operation
is useful to register home directories locally that are not located where
<filename>systemd-homed.service</filename> would find them automatically.</para>
<para><function>UnregisterHome()</function> unregisters an existing home directory. It takes a user
name as argument and undoes what <function>RegisterHome()</function> does. It does not attempt to
remove the home directory itself, it just unregisters it with the local system. Note that if the home
directory is placed where <filename>systemd-homed.service</filename> looks for home directories anyway
this call will only undo fixation (see below), but the record will remain known to
<filename>systemd-homed.service</filename> and be listed among known records. Since the user record is
embedded into the home directory this operation generally does not discard data belonging to the user
or their record. This method is equivalent to
<function>Unregister()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>CreateHome()</function> registers and creates a new home directory. This takes a fully
specified JSON user record as argument (including the <literal>secret</literal> section). This registers
the user record locally and creates a home directory matching it, depending on the settings specified
in the record in combination with local configuration.</para>
<para><function>RealizeHome()</function> creates a home directory whose user record is already
registered locally. This takes a user name plus a user record consisting only of the
<literal>secret</literal> section. Invoking <function>RegisterHome()</function> followed by
<function>RealizeHome()</function> is mostly equivalent to calling <function>CreateHome()</function>,
except that the latter combines the two in atomic fashion. This method is equivalent to
<function>Realize()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>RemoveHome()</function> unregisters a user record locally, and removes the home
directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to
<function>Remove()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>FixateHome()</function> <literal>fixates</literal> an automatically discovered home
directory. <filename>systemd-homed.service</filename> automatically discovers home directories dropped
in our plugged in and adds them to the runtime list of user records it manages. A user record
discovered that way may be <literal>fixated</literal>, in which case it is copied out of the home
directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract
additional (typically previously encrypted) user record data from the home directory. A home directory
mus be fixated before it can be logged into. This method call takes a user name and a JSON user record
consisting only of the <literal>secret</literal> section as argument. This method is equivalent to
<function>Fixate()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>AuthenticateHome()</function> checks passwords or other authentication credentials
associated with the home directory. It takes a user name and a JSON user record consisting only of the
<literal>secret</literal> section as argument. Note that many of the other method calls authenticate
the user first, in order to execute some other operation. This method call only authenticates and
executes no further operation. Like <function>ActivateHome()</function> it is usually first invoked
with an empty JSON user record, which is then populated for subsequent tries with additional
authentication data supplied. This method is equivalent to
<function>Authenticate()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>UpdateHome()</function> updates a locally registered user record. Takes a fully
specified JSON user record as argument (including the <literal>secret</literal> section). A user with a
matching name and realm must be registered locally already, and the last change timestamp of the newly
supplied record must be newer than the previously existing user record. Note this operation updates the
user record only, it does not propagate passwords/authentication tokens from the user record to the
storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then
the password of the underlying storage updated using <function>ChangePasswordHome()</function> as well
as the storage resized using <function>ResizeHome()</function>. This method is equivalent to
<function>Update()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>ResizeHome()</function> resizes the storage associated with a user record. Takes a user
name, a disk size in bytes and a user record consisting only of the <literal>secret</literal> section
as argument. If the size is specified as <constant>UINT64_MAX</constant> the storage is resized to the
size already specified in the user record. Typically, if the user record is updated using
<function>UpdateHome()</function> above this is used to propagate the size configured there-in down to
the underlying storage back-end. This method is equivalent to
<function>Resize()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>ChangePasswordHome()</function> changes the passwords/authentication tokens of a home
directory. Takes a user name, and two JSON user record objects, each consisting only of the
<literal>secret</literal> section, for the old and for the new passwords/authentication tokens. If the
user record with the new passwords/authentication token data is specified as empty the existing user
record's settings are propagated down to the home directory storage. This is typically used after a
user record is updated using <function>UpdateHome()</function> in order to propagate the
secrets/authentication tokens down to the storage. This method is equivalent to
<function>ChangePassword()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>LockHome()</function> temporarily suspends access to a home directory, flushing out any
cryptographic keys from memory. This is only supported on some back-ends, and usually done during system
suspend, in order to effectively secure home directories while the system is sleeping. Takes a user
name as single argument. If an application attempts to access a home directory while it is locked it
will typically freeze until the home directory is unlocked again. This method is equivalent to
<function>Lock()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>UnlockHome()</function> undoes the effect of <function>LockHome()</function>. Takes a
user name and a user record consisting only of the <literal>secret</literal> section as arguments. This
method is equivalent to <function>Unlock()</function> on the
<classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>AcquireHome()</function> activates or unlocks a home directory in a reference counted
mode of operation. Takes a user name and user record consisting only of <literal>secret</literal>
section as argument. If the home directory is not active yet, it is activated. If it is currently
locked it is unlocked. After completion a reference to the activation/unlocking of the home directory
is returned via a file descriptor. When the last client which acquired such a file descriptor closes it
the home directory is automatically deactivated again. This method is typically invoked when a user
logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home
directory can be unmounted automatically again in a robust fashion, when the user logs out. The third
argument is a boolean which indicates whether the client invoking the call is able to automatically
re-authenticate when the system comes back from suspending. It should be set by all clients that
implement a secure lock screen running outside of the user's context, that is brought up when the
system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home
directory. If a home directory has at least one client with an open reference to the home directory
that does not support this it is not suspended automatically at system suspend, otherwise it is. This
method is equivalent to <function>Acquire()</function> on the
<classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>RefHome()</function> is similar to <function>AcquireHome()</function> but takes no user
record with <literal>secret</literal> section, i.e. will take an additional reference to an already
activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the
home directory is not already activated. This method is equivalent to
<function>Ref()</function> on the <classname>org.freedesktop.home1.Home</classname>
interface.</para>
<para><function>ReleaseHome()</function> releases a home directory again, if all file descriptors
referencing it are already closed, that where acquired through <function>AcquireHome()</function> or
<function>RefHome()</function>. Note that this call does not actually cause the deactivation of the
home directory (which happens automatically when the last referencing file descriptor is closed), but
is simply a synchronization mechanism that allows delaying of the user session's termination until any
triggered deactivation is completed. This method is equivalent to <function>Release()</function> on the
<classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>LockAllHomes()</function> locks all active home directories that only have references
that opted into automatic suspending during system suspend. This is usually invoked automatically
shortly before system suspend.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>AutoLogin</varname> exposes an array of structures consisting of user name, seat name
and object path of an home directory object. All locally managed users that have the
<literal>autoLogin</literal> field set are listed here, with the seat name they are associated with. A
display manager may watch this property and pre-fill the login screen with the users exposed this
way.</para>
</refsect2>
</refsect1>
<refsect1>
<title>The Home Object</title>
<programlisting executable="systemd-homed" node="/org/freedesktop/home1/home" interface="org.freedesktop.home1.Home">
node /org/freedesktop/home1/home {
interface org.freedesktop.home1.Home {
methods:
Activate(in s secret);
Deactivate();
Unregister();
Realize(in s secret);
Remove();
Fixate(in s secret);
Authenticate(in s secret);
Update(in s user_record);
Resize(in t size,
in s secret);
ChangePassword(in s new_secret,
in s old_secret);
Lock();
Unlock(in s secret);
Acquire(in s secret,
in b please_suspend,
out h send_fd);
Ref(in b please_suspend,
out h send_fd);
Release();
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s UserName = '...';
readonly u UID = ...;
readonly (suusss) UnixRecord = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s State = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
readonly (sb) UserRecord = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
interface org.freedesktop.DBus.ObjectManager { ... };
};
</programlisting>
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/>
<variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Deactivate()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Unregister()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Realize()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Remove()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Fixate()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Authenticate()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Update()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Resize()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ChangePassword()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Lock()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Acquire()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Ref()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Release()"/>
<variablelist class="dbus-property" generated="True" extra-ref="UserName"/>
<variablelist class="dbus-property" generated="True" extra-ref="UID"/>
<variablelist class="dbus-property" generated="True" extra-ref="UnixRecord"/>
<variablelist class="dbus-property" generated="True" extra-ref="State"/>
<variablelist class="dbus-property" generated="True" extra-ref="UserRecord"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para><function>Activate()</function>, <function>Deactivate()</function>,
<function>Unregister()</function>, <function>Realize()</function>, <function>Remove()</function>,
<function>Fixate()</function>, <function>Authenticate()</function>, <function>Update()</function>,
<function>Resize()</function>, <function>ChangePassword()</function>, <function>Lock()</function>,
<function>Unlock()</function>, <function>Acquire()</function>, <function>Ref()</function>,
<function>Release()</function> operate like their matching counterparts on the
<classname>org.freedesktop.home1.Manager</classname> interface (see above). The main difference is that
they are methods of the home directory objects, and hence carry no additional user name
parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
client side: if only the user name is known, it's preferable to use the methods on the manager object
since they operate with user names only. If however the home object path was already acquired some way
it is preferable to operate on the <classname>org.freedesktop.home1.Home</classname> objects
instead.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>UserName</varname> contains the user name of the user account/home directory.</para>
<para><varname>UID</varname> contains the numeric UNIX UID of the user account.</para>
<para><varname>UnixRecord</varname> contains a structure encapsulating the six fields a
<structname>struct passwd</structname> typically contains (the password field is suppressed).</para>
<para><varname>State</varname> exposes the current state home the home directory.</para>
<para><varname>UserRecord</varname> contains the full JSON user record string of the user account.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

367
man/org.freedesktop.hostname1.xml Normal file
View File

@ -0,0 +1,367 @@
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.hostname1" conditional='ENABLE_HOSTNAMED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.hostname1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.hostname1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.hostname1</refname>
<refpurpose>The D-Bus interface of systemd-hostnamed</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that can be used to control the hostname and related machine metadata from user
programs. This page describes the hostname semantics and the D-Bus interface.</para>
</refsect1>
<refsect1>
<title>The D-Bus API</title>
<para>The service exposes the following interfaces on the bus:</para>
<programlisting executable="systemd-hostnamed" node="/org/freedesktop/hostname1" interface="org.freedesktop.hostname1">
node /org/freedesktop/hostname1 {
interface org.freedesktop.hostname1 {
methods:
SetHostname(in s hostname,
in b interactive);
SetStaticHostname(in s hostname,
in b interactive);
SetPrettyHostname(in s hostname,
in b interactive);
SetIconName(in s icon,
in b interactive);
SetChassis(in s chassis,
in b interactive);
SetDeployment(in s deployment,
in b interactive);
SetLocation(in s location,
in b interactive);
GetProductUUID(in b interactive,
out ay uuid);
properties:
readonly s Hostname = '...';
readonly s StaticHostname = '...';
readonly s PrettyHostname = '...';
readonly s IconName = '...';
readonly s Chassis = '...';
readonly s Deployment = '...';
readonly s Location = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s KernelName = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s KernelRelease = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s KernelVersion = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s OperatingSystemPrettyName = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s OperatingSystemCPEName = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HomeURL = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetHostname()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetStaticHostname()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetPrettyHostname()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetIconName()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetChassis()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDeployment()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLocation()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetProductUUID()"/>
<variablelist class="dbus-property" generated="True" extra-ref="Hostname"/>
<variablelist class="dbus-property" generated="True" extra-ref="StaticHostname"/>
<variablelist class="dbus-property" generated="True" extra-ref="PrettyHostname"/>
<variablelist class="dbus-property" generated="True" extra-ref="IconName"/>
<variablelist class="dbus-property" generated="True" extra-ref="Chassis"/>
<variablelist class="dbus-property" generated="True" extra-ref="Deployment"/>
<variablelist class="dbus-property" generated="True" extra-ref="Location"/>
<variablelist class="dbus-property" generated="True" extra-ref="KernelName"/>
<variablelist class="dbus-property" generated="True" extra-ref="KernelRelease"/>
<variablelist class="dbus-property" generated="True" extra-ref="KernelVersion"/>
<variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemPrettyName"/>
<variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemCPEName"/>
<variablelist class="dbus-property" generated="True" extra-ref="HomeURL"/>
<!--End of Autogenerated section-->
<para>Whenever the hostname or other metadata is changed via the daemon,
<function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname
using this interface is authenticated via
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
</refsect1>
<refsect1>
<title>Semantics</title>
<para>The <emphasis>static (configured) hostname</emphasis> is the one configured in
<filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the
current hostname as returned by the
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>
system call. If no hostname is configured this property will be the empty string. Setting this property
to the empty string will remove <filename>/etc/hostname</filename>. This property should be an
internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
<para>The <emphasis>transient (dynamic) hostname</emphasis> is the one configured via the kernel's
<citerefentry project="man-pages"><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
It can be different from the static hostname if DHCP or mDNS have been configured to change the name
based on network information. <!-- FIXME: it's not DHCP that configures this... -->
This property is never empty. If no hostname is set this will default to
<literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the
empty string will reset the dynamic hostname to the static hostname. If no static hostname is
configured the dynamic hostname will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This property
should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
<para>The <emphasis>pretty hostname</emphasis> is a free-form UTF-8 hostname for presentation to the
user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync.
I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be
<literal>lennarts-computer</literal>. If no pretty hostname is set this setting will be the empty
string. Applications should then find a suitable fallback, such as the dynamic hostname.</para>
<para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set,
information such as the chassis type (see below) is used to find a suitable fallback icon name
(i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the
chassis information). If no such data is available, the empty string is returned. In that case an application
should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set
to the empty string, the automatic fallback name selection is enabled again.</para>
<para>The <emphasis>chassis type</emphasis> should be one of the currently defined chassis types:
<literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>,
<literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types
<literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases
the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to
this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if
it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of
the chassis type from firmware information.</para>
<para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a
short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent
out for changes made directly on the files (as in: administrator edits the files with vi). This is
the intended behavior: manual configuration changes should require manual reloading.</para>
<para>The transient (dynamic) hostname maps directly to the kernel hostname. This hostname should be
assumed to be highly dynamic, and hence should be watched directly, without depending on
<function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. To accomplish
this, open <filename>/proc/sys/kernel/hostname</filename> and
<citerefentry project="man-pages"><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again:
this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed)
hostname.</para>
<para>Applications may read the hostname data directly if hostname change notifications
are not necessary. Use
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for that. For more information on these files and syscalls see the respective man pages.</para>
<refsect2>
<title>Methods and Properties</title>
<para><function>SetHostname()</function> sets the transient (dynamic) hostname which is exposed by the
<varname>Hostname</varname> property. If empty, the transient hostname is set to the static hostname.
</para>
<para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the
<varname>StaticHostname</varname> property. If empty, the built-in default of
<literal>&FALLBACK_HOSTNAME;</literal> is used.</para>
<para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the
<varname>PrettyHostname</varname> property.</para>
<para><function>SetIconName()</function>, <function>SetChassis()</function>,
<function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties
<varname>IconName</varname> (the name of the icon representing for the machine),
<varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system
deployment environment), and <varname>Location</varname> (physical system location), respectively.
</para>
<para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>,
<varname>Deployment</varname>, and <varname>Location</varname> are stored in
<filename>/etc/machine-info</filename>. See
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
the semantics of those settings.</para>
<para><function>GetProductUUID()</function> returns the "product uuid" as exposed by the kernel based
on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly
requires root privileges, and this method allows access to unprivileged clients through the polkit
framework.</para>
<para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and
<varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release
(e.g. <literal>5.0.0-11</literal>), and version (i.e. the build number, e.g. <literal>#11</literal>) as
reported by
<citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
<varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and
<varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and
<varname>HOME_URL=</varname> fields from
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
purpose of those properties is to allow remote clients to access this information over D-Bus. Local
clients can access the information directly.</para>
</refsect2>
<refsect2>
<title>Security</title>
<para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit
should interactively ask the user for authentication credentials if required.</para>
<para>The polkit action for <function>SetHostname()</function> is
<interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
<function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
<interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
<function>SetIconName()</function> and <function>SetChassis()</function> it is
<interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Recommendations</title>
<para>Here are three examples that show how the pretty hostname and the icon name should be used:
<itemizedlist>
<listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass
the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon
on each service. This is especially useful for WebDAV applications or UPnP media sharing.
</para></listitem>
<listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem>
<listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname
if set, and the icon with the icon name, if it is set.</para></listitem>
</itemizedlist></para>
<para>To properly handle name lookups with changing local hostnames without having to edit
<filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
<para>A client that wants to change the local hostname for DHCP/mDNS should invoke
<code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
<code>SetHostname("")</code>.</para>
<para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty
name:
<itemizedlist>
<listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them,
or replace them with <literal>-</literal>.</para></listitem>
<listitem><para>It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way
these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>.
Strip other chars, or try to replace them in some smart way with chars from this set, for example
<literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as the replacement for all
punctuation characters and whitespace.</para></listitem>
<listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as
the first or last char.</para></listitem>
<listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem>
<listitem><para>If after stripping special chars the empty string is the result, you can pass this
as-is to <filename>systemd-hostnamed</filename> in which case it will automatically use
<literal>&FALLBACK_HOSTNAME;</literal>.</para></listitem>
<listitem><para>Uppercase charaacters should be replaced with their lowercase equivalents.
</para></listitem>
</itemizedlist></para>
<para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass
they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename>
will also accept <literal>_</literal> in the hostname, but we recommend not using this to avoid clashes
with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but
because of the DNS label limitations, we recommend not making use of this.</para>
<para>Here are a couple of example conversions:
<itemizedlist>
<listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem>
<listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem>
<listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem>
<listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem>
<listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem>
<listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem>
<listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem>
</itemizedlist></para>
<para>Of course, an already valid internet hostname label you enter and pass through this
conversion should stay unmodified, so that users have direct control of it, if they want — by simply
ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
name.</para>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title>
<programlisting>$ gdbus introspect --system \
--dest org.freedesktop.hostname1 \
--object-path /org/freedesktop/hostname1
</programlisting>
</example>
</refsect1>
<refsect1>
<title>See also</title>
<para>David Zeuthen's original Fedora
<ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para>
</refsect1>
</refentry>

348
man/org.freedesktop.import1.xml Normal file
View File

@ -0,0 +1,348 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.import1" conditional='ENABLE_IMPORTD'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.import1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.import1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.import1</refname>
<refpurpose>The D-Bus interface of systemd-importd</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service which may be used to import, export and download additional system images. These
images can be used by tools such as
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
to run local containers. The service is used as the backend for <command>machinectl pull-raw</command>,
<command>machinectl pull-tar</command> and related commands. This page describes the D-Bus interface.
</para>
<para>Note that
<citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is mostly a small companion service for
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
Many operations to manipulate local container and VM images are hence available via the <command>systemd-machined</command> D-Bus API, c.f.
<citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
<title>The Manager Object</title>
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
<programlisting executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager">
node /org/freedesktop/import1 {
interface org.freedesktop.import1.Manager {
methods:
ImportTar(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportRaw(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportFileSystem(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ExportTar(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportRaw(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
PullTar(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullRaw(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
ListTransfers(out a(usssdo) transfers);
CancelTransfer(in u transfer_id);
signals:
TransferNew(u transfer_id,
o transfer_path);
TransferRemoved(u transfer_id,
o transfer_path,
s result);
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--method ImportFileSystem is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/>
<variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/>
<variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/>
<variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="TransferNew"/>
<variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para><function>ImportTar()</function> and <function>ImportRaw()</function> import a system image and
place it into <filename>/var/lib/machines/</filename>. The first argument should be a file descriptor
(opened for reading) referring to the tar or raw file to import. It should reference a file on disk,
a pipe or a socket. When <function>ImportTar()</function> is used the file descriptor should
refer to a tar file, optionally compressed with
<citerefentry project="die-net"><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project="die-net"><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
or
<citerefentry project="die-net"><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<command>systemd-importd</command> will detect the used compression scheme (if any) automatically. When
<function>ImportRaw()</function> is used the file descriptor should refer to a raw or qcow2 disk image
containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case,
if the file is specified as a file descriptor on disk, progress information is generated for the import
operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not
available. The file descriptor argument is followed by a local name for the image. This should be a
name suitable as a hostname and will be used to name the imported image below
<filename>/var/lib/machines</filename>. A tar import is placed as a directory tree or a
<citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
subvolume below <filename>/var/lib/machines/</filename> under the specified name with no suffix
appended. A raw import is placed as a file in <filename>/var/lib/machines/</filename> with the
<filename>.raw</filename> suffix appended. If the <option>force</option> argument is true, any
pre-existing image with the same name is removed before starting the operation. Otherwise, the
operation fails if an image with the same name already exists. Finally, the
<option>read_only</option> argument controls
whether to create a writable or read-only image. Both methods return immediately after starting the import,
with the import transfer ongoing. They return a pair of transfer identifier and object path, which may
be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a
simple numeric identifier, the object path references an
<interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a
<function>TransferRemoved</function> signal for the transfer ID in order to detect when a transfer is
complete. The returned transfer object is useful to determine the current progress or log output of the
ongoing import operation.</para>
<para><function>ExportTar()</function> and <function>ExportRaw()</function> implement the reverse
operation, and may be used to export a system image in order to place it in a tar or raw image. They
take the machine name to export as their first parameter, followed by a file descriptor (opened for writing)
where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The
third argument specifies in which compression format to write the image. It takes one of
<literal>uncompressed</literal>, <literal>xz</literal>, <literal>bzip2</literal> or
<literal>gzip</literal>, depending on which compression scheme is required. The image written to the
specified file descriptor will be a tar file in case of <function>ExportTar()</function> or a raw disk
image in case of <function>ExportRaw()</function>. Note that currently raw disk images may not be
exported as tar files, and vice versa. This restriction might be lifted eventually. The method
returns a transfer identifier and object path for cancelling or tracking the export operation, similar
to <function>ImportTar()</function> or <function>ImportRaw()</function> as described above.</para>
<para><function>PullTar()</function> and <function>PullRaw()</function> may be used to download, verify
and import a system image from a URL. They take an URL argument which should point to a tar or
raw file on the <literal>http://</literal> or <literal>https://</literal> protocols, possibly
compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be
suitable as a hostname, similar to the matching argument of the <function>ImportTar()</function> and
<function>ImportRaw()</function> methods above. The third argument indicates the verification mode for
the image. It may be one of <literal>no</literal>, <literal>checksum</literal>,
<literal>signature</literal>. <literal>no</literal> turns off any kind of verification of the image;
<literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file next to the downloaded
image and verifies any SHA256 hash value in that file against the image; <literal>signature</literal>
does the same but also tries to authenticate the <filename>SHA256SUM</filename> file via
<citerefentry project="man-pages"><refentrytitle>gpg</refentrytitle><manvolnum>8</manvolnum></citerefentry>
first. The last argument indicates whether to replace a possibly pre-existing image with the same local
name (if <literal>true</literal>), or whether to fail (if <literal>false</literal>). Like the import
and export calls above, these calls return a pair of transfer identifier and object path for the ongoing
download.</para>
<para><function>ListTransfers()</function> returns a list of ongoing import, export or download
operations as created with the six calls described above. It returns an array of structures which
consist of the numeric transfer identifier, a string indicating the operation (one of
<literal>import-tar</literal>, <literal>import-raw</literal>, <literal>export-tar</literal>,
<literal>export-raw</literal>, <literal>pull-tar</literal> or <literal>pull-raw</literal>), a string
describing the remote file (in case of download operations this is the source URL, in case of
import/export operations this is a short string describing the file descriptor passed in), a string
with the local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as
the transfer object path.</para>
<para><function>CancelTransfer()</function> may be used to cancel an ongoing import, export or download
operation. Simply specify the transfer identifier to cancel the ongoing operation.</para>
</refsect2>
<refsect2>
<title>Signals</title>
<para>The <function>TransferNew</function> signal is generated each time a new transfer is started with
the import, export or download calls described above. It carries the transfer ID and object path that
have just been created.</para>
<para>The <function>TransferRemoved</function> signal is sent each time a transfer finishes,
is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating
the result of the operation, which is one of <literal>done</literal> (on success),
<literal>canceled</literal> or <literal>failed</literal>.</para>
</refsect2>
</refsect1>
<refsect1>
<title>The Transfer Object</title>
<programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer">
node /org/freedesktop/import1/transfer/_1 {
interface org.freedesktop.import1.Transfer {
methods:
Cancel();
signals:
LogMessage(u priority,
s line);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Id = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Local = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Remote = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Type = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Verify = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly d Progress = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--signal LogMessage is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/>
<variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="LogMessage"/>
<variablelist class="dbus-property" generated="True" extra-ref="Id"/>
<variablelist class="dbus-property" generated="True" extra-ref="Local"/>
<variablelist class="dbus-property" generated="True" extra-ref="Remote"/>
<variablelist class="dbus-property" generated="True" extra-ref="Type"/>
<variablelist class="dbus-property" generated="True" extra-ref="Verify"/>
<variablelist class="dbus-property" generated="True" extra-ref="Progress"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no
parameters. This method is pretty much equivalent to the <function>CancelTransfer()</function> method
on the <structname>Manager</structname> interface (see above), but is exposed on the
<structname>Transfer</structname> object itself instead of taking a transfer ID.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para>The <varname>Id</varname> property exposes the numeric transfer ID of the transfer object.</para>
<para>The <varname>Local</varname>, <varname>Remote</varname> and <varname>Type</varname> properties
expose the local container name of this transfer, the remote source (in case of download: the URL, in
case of import/export: a string describing the file descriptor passed in), and the type of operation
(see the Manager's <function>ListTransfer()</function> method above for an explanation of the possible
values).</para>
<para>The <varname>Verify</varname> property exposes the selected verification setting and is only
defined for download operations (see above).</para>
<para>The <varname>Progress</varname> property exposes the current progress of the transfer as a value
between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular
intervals, for example every 500 ms or so.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title>
<programlisting>$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1
</programlisting>
</example>
<example>
<title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title>
<programlisting>$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1/transfer/_1
</programlisting>
</example>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
</refentry>

188
man/org.freedesktop.locale1.xml Normal file
View File

@ -0,0 +1,188 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.locale1" conditional='ENABLE_LOCALED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.locale1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.locale1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.locale1</refname>
<refpurpose>The D-Bus interface of systemd-localed</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that can be used to control the system locale and keyboard mapping from user
programs. This page describes the D-Bus interface.</para>
</refsect1>
<refsect1>
<title>The D-Bus API</title>
<para>The service exposes the following interfaces on the bus:</para>
<programlisting executable="systemd-localed" node="/org/freedesktop/locale1" interface="org.freedesktop.locale1">
node /org/freedesktop/locale1 {
interface org.freedesktop.locale1 {
methods:
SetLocale(in as locale,
in b interactive);
SetVConsoleKeyboard(in s keymap,
in s keymap_toggle,
in b convert,
in b interactive);
SetX11Keyboard(in s layout,
in s model,
in s variant,
in s options,
in b convert,
in b interactive);
properties:
readonly as Locale = ['...', ...];
readonly s X11Layout = '...';
readonly s X11Model = '...';
readonly s X11Variant = '...';
readonly s X11Options = '...';
readonly s VConsoleKeymap = '...';
readonly s VConsoleKeymapToggle = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.locale1"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.locale1"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLocale()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetVConsoleKeyboard()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetX11Keyboard()"/>
<variablelist class="dbus-property" generated="True" extra-ref="Locale"/>
<variablelist class="dbus-property" generated="True" extra-ref="X11Layout"/>
<variablelist class="dbus-property" generated="True" extra-ref="X11Model"/>
<variablelist class="dbus-property" generated="True" extra-ref="X11Variant"/>
<variablelist class="dbus-property" generated="True" extra-ref="X11Options"/>
<variablelist class="dbus-property" generated="True" extra-ref="VConsoleKeymap"/>
<variablelist class="dbus-property" generated="True" extra-ref="VConsoleKeymapToggle"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para>If you set a new system locale all old system locale settings will be dropped and the new
settings will be saved to disk. The locale will also be passed to the system manager, and subsequently started
daemons will inherit the new system locale. Note that already running daemons will not learn about the
new value.</para>
<para>The <function>SetVConsoleKeyboard()</function> method may be used to set the key mapping for the
virtual console. Similarly, <function>SetX11Keyboard()</function> may be used to set the default key
mapping of any X11 servers.</para>
<para>Note that <function>SetVConsoleKeyboard()</function> instantly applies the new key mapping to the
console, while <function>SetX11Keyboard()</function> simply sets a default that may be used by later
sessions.</para>
<para>The boolean argument <varname>convert</varname> may be set to optionally convert the console
keyboard configuration to X11 keyboard mappings and vice versa. If true and
<function>SetVConsoleKeyboard()</function> is used, the nearest X11 keyboard setting for the chosen
console setting is set. If true and <function>SetX11Keyboard()</function> is used, the nearest console
keyboard setting for the chosen X11 setting is set. Hence, it is usually sufficient to call only one of the
two functions.</para>
<para>For graphical UIs that need to set the system keyboard mapping simply invoke
<function>SetX11Keyboard()</function>, set <varname>convert=true</varname> and ignore
<function>SetVConsoleKeyboard()</function>.</para>
<para>Use the empty string for the keymap parameters you wish not to set.</para>
<para>The <varname>interactive</varname> boolean parameters can be used to control whether
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
should interactively ask the user for authentication credentials if required.</para>
</refsect2>
<refsect2>
<title>Signals</title>
<para>Whenever the system locale or keymap is changed via the daemon,
<function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para>The system locale is shown in the <varname>Locale</varname> property. It is an array containing
environment-variable-assignment-like strings. The following strings are known:
<varname>LANG=</varname>, <varname>LC_CTYPE=</varname>, <varname>LC_NUMERIC=</varname>,
<varname>LC_TIME=</varname>, <varname>LC_COLLATE=</varname>, <varname>LC_MONETARY=</varname>,
<varname>LC_MESSAGES=</varname>, <varname>LC_PAPER=</varname>, <varname>LC_NAME=</varname>,
<varname>LC_ADDRESS=</varname>, <varname>LC_TELEPHONE=</varname>, <varname>LC_MEASUREMENT=</varname>,
<varname>LC_IDENTIFICATION=</varname>.</para>
<para>The <varname>X11Layout</varname>, <varname>X11Model</varname>, <varname>X11Variant</varname>, and
<varname>X11Options</varname> properties show values configurable with
<function>SetX11Keyboard()</function> described above (or <function>SetVConsoleKeyboard()</function>
with <varname>convert=true</varname>). The <varname>VConsoleKeymap</varname> and
<varname>VConsoleKeymapToggle</varname> properties show values configurable with
<function>SetVConsoleKeyboard()</function> (or <function>SetX11Keyboard()</function> with
<varname>convert=true</varname>).</para>
</refsect2>
<refsect2>
<title>Security</title>
<para>Changing the system locale or keymap using this interface is authenticated via polkit. The
polkit action for <function>SetLocale()</function> is
<constant>org.freedesktop.locale1.set-locale</constant>. The polkit action for
<function>SetX11Keyboard()</function> and <function>SetVConsoleKeyboard()</function> is
<constant>org.freedesktop.locale1.set-keyboard</constant>.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.locale1</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.locale1 \
--object-path /org/freedesktop/locale1
</programlisting>
</example>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
</refentry>

1390
man/org.freedesktop.login1.xml Normal file
View File

File diff suppressed because it is too large Load Diff

643
man/org.freedesktop.machine1.xml Normal file
View File

@ -0,0 +1,643 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.machine1" conditional='ENABLE_MACHINED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.machine1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.machine1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.machine1</refname>
<refpurpose>The D-Bus interface of systemd-machined</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that keeps track of locally running virtual machines and containers.
This page describes the D-Bus interface.</para>
</refsect1>
<refsect1>
<title>The Manager Object</title>
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
<programlisting executable="systemd-machined" node="/org/freedesktop/machine1" interface="org.freedesktop.machine1.Manager">
node /org/freedesktop/machine1 {
interface org.freedesktop.machine1.Manager {
methods:
GetMachine(in s name,
out o machine);
GetImage(in s name,
out o image);
GetMachineByPID(in u pid,
out o machine);
ListMachines(out a(ssso) machines);
ListImages(out a(ssbttto) images);
CreateMachine(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
in a(sv) scope_properties,
out o path);
CreateMachineWithNetwork(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
in ai ifindices,
in a(sv) scope_properties,
out o path);
RegisterMachine(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
out o path);
RegisterMachineWithNetwork(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
in ai ifindices,
out o path);
UnregisterMachine(in s name);
TerminateMachine(in s id);
KillMachine(in s name,
in s who,
in i signal);
GetMachineAddresses(in s name,
out a(iay) addresses);
GetMachineOSRelease(in s name,
out a{ss} fields);
OpenMachinePTY(in s name,
out h pty,
out s pty_path);
OpenMachineLogin(in s name,
out h pty,
out s pty_path);
OpenMachineShell(in s name,
in s user,
in s path,
in as args,
in as environment,
out h pty,
out s pty_path);
BindMountMachine(in s name,
in s source,
in s destination,
in b read_only,
in b mkdir);
CopyFromMachine(in s name,
in s source,
in s destination);
CopyToMachine(in s name,
in s source,
in s destination);
OpenMachineRootDirectory(in s name,
out h fd);
GetMachineUIDShift(in s name,
out u shift);
RemoveImage(in s name);
RenameImage(in s name,
in s new_name);
CloneImage(in s name,
in s new_name,
in b read_only);
MarkImageReadOnly(in s name,
in b read_only);
GetImageHostname(in s name,
out s hostname);
GetImageMachineID(in s name,
out ay id);
GetImageMachineInfo(in s name,
out a{ss} machine_info);
GetImageOSRelease(in s name,
out a{ss} os_release);
SetPoolLimit(in t size);
SetImageLimit(in s name,
in t size);
CleanPool(in s mode,
out a(st) images);
MapFromMachineUser(in s name,
in u uid_inner,
out u uid_outer);
MapToMachineUser(in u uid_outer,
out s machine_name,
out o machine_path,
out u uid_inner);
MapFromMachineGroup(in s name,
in u gid_inner,
out u gid_outer);
MapToMachineGroup(in u gid_outer,
out s machine_name,
out o machine_path,
out u gid_inner);
signals:
MachineNew(s machine,
o path);
MachineRemoved(s machine,
o path);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s PoolPath = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t PoolUsage = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t PoolLimit = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--method UnregisterMachine is not documented!-->
<!--method OpenMachineRootDirectory is not documented!-->
<!--method GetMachineUIDShift is not documented!-->
<!--method GetImageHostname is not documented!-->
<!--method GetImageMachineID is not documented!-->
<!--method GetImageMachineInfo is not documented!-->
<!--method GetImageOSRelease is not documented!-->
<!--method CleanPool is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineByPID()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListMachines()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CreateMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CreateMachineWithNetwork()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RegisterMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RegisterMachineWithNetwork()"/>
<variablelist class="dbus-method" generated="True" extra-ref="UnregisterMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="TerminateMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="KillMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineAddresses()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineOSRelease()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachinePTY()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachineLogin()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachineShell()"/>
<variablelist class="dbus-method" generated="True" extra-ref="BindMountMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyFromMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyToMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachineRootDirectory()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineUIDShift()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RenameImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CloneImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageHostname()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineID()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineInfo()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CleanPool()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineUser()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapToMachineUser()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineGroup()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapToMachineGroup()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="MachineNew"/>
<variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved"/>
<variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/>
<variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/>
<variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para><function>GetMachine()</function> may be used to get the machine object path for the machine with
the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the
specified PID belongs to if there is any.</para>
<para><function>GetImage()</function> may be used to get the image object path of the image with the
specified name.</para>
<para><function>ListMachines()</function> returns an array of all currently registered machines. The
structures in the array consist of the following fields: machine name, machine class, an identifier for
the service that registered the machine and the machine object path.</para>
<para><function>ListImages()</function> returns an array of all currently known images. The
structures in the array consist of the following fields: image name, type, read-only flag, creation
time, modification time, current disk space, and image object path.</para>
<para><function>CreateMachine()</function> may be used to register a new virtual machine or container
with <command>systemd-machined</command>, creating a scope unit for it. It accepts the following arguments: a
machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the
service that registers the machine, a class string, the PID of the leader process of the machine, an
optional root directory of the container, and an array of additional properties to use for the scope
registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual
DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is
permitted, a maximum length of 64 characters is enforced, only characters from the set
<literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain
two dots immediately following each other. Container and VM managers should ideally use the hostname
used internally in the machine for this parameter. This recommendation is made in order to make the
machine name naturally resolvable using
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If
a container manager needs to embed characters outside of the indicated range, escaping is required,
possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be
to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is
available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify
the virtual machine/container uniquely and should ideally be the same UUID that
<filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be
free-form, but it is recommended to pass a short lowercase identifier like
<literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should
be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to
register is of the respective class. The leader PID should be the host PID of the init process of the
container or the encapsulating process of the VM. If the root directory of the container is known and
available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the
scope properties are passed as array in the same way as to PID1's
<function>StartTransientUnit()</function> method. Calling this method will internally register a transient scope
unit for the calling client (utilizing the passed scope_properties) and move the leader PID into
it. The method returns an object path for the registered machine object that implements the
<interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
Interfaces</ulink> for details about scope units and how to alter resource control settings on the
created machine at runtime.</para>
<para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>.
However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is
registered. We recommend to only use this method for container or VM managers that are run
multiple times, one instance for each container/VM they manage, and are invoked as system
services.</para>
<para><function>CreateMachineWithNetwork()</function> and
<function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function>
and <function>RegisterMachine()</function> but take an extra argument: an array of network interface
indices that point towards the virtual machine or container. The interface indices should reference one
or more network interfaces on the host that can be used to communicate with the guest. Commonly, the
passed interface index refers to the host side of a "veth" link (in case of containers), a
"tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the
VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6
communication to the machines since the scope field of sockaddr_in6 can be initialized by the
specified ifindex.
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>
makes use of this information.</para>
<para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a
machine name (as originally passed to <function>CreateMachine()</function> or returned by
<function>ListMachines()</function>), an identifier that specifies what precisely to send the signal to (either
<literal>leader</literal> or <literal>all</literal>), and a numeric UNIX signal integer.</para>
<para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It
takes a machine name as its only argument.</para>
<para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This method
returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or
<constant>AF_INET6</constant>) and a byte array containing the addresses. This is only supported for
containers that make use of network namespacing.</para>
<para><function>GetMachineOSRelease()</function> retrieves the OS release information of a
container. This method returns an array of key value pairs read from the
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
the container and is useful to identify the operating system used in a container.</para>
<para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file
descriptor and its path. This is equivalent to transitioning into the container and invoking
<citerefentry project='man-pages'><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
<para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that
a getty login prompt of the container is running on the other end. It returns the file descriptor of
the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the
container.</para>
<para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified
user, and invokes the executable at the specified path with a list of arguments (starting from
argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY
path.</para>
<para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the
container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the
container, and two booleans, one indicating whether the bind mount shall be
read-only, the other indicating whether the destination mount point shall be created first, if it is
missing.</para>
<para><function>CopyFromMachine()</function> copies files or directories from a container into the
host. It takes a container name, a source directory in the container and a destination directory on the
host as arguments. <function>CopyToMachine()</function> does the opposite and copies files from a source
directory on the host into a destination directory in the container.</para>
<para><function>RemoveImage()</function> removes the image with the specified name.</para>
<para><function>RenameImage()</function> renames the specified image.</para>
<para><function>CloneImage()</function> clones the specified image under a new name. It also takes a
boolean argument indicating whether the resulting image shall be read-only or not.</para>
<para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para>
<para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para>
<para><function>SetImageLimit()</function> sets a per-image quota limit.</para>
<para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>,
<function>MapFromMachineGroup()</function>, and <function>MapToMachineGroup()</function> may be used to map
UIDs/GIDs from the host user namespace to a container user namespace or vice versa.</para>
</refsect2>
<refsect2>
<title>Signals</title>
<para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new
machine is registered or removed. These signals carry the machine name and the object path to the corresponding
<interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>PoolPath</varname> specifies the file system path where images are written to.</para>
<para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para>
<para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Machine Objects</title>
<programlisting executable="systemd-machined" node="/org/freedesktop/machine1/machine/rawhide" interface="org.freedesktop.machine1.Machine">
node /org/freedesktop/machine1/machine/rawhide {
interface org.freedesktop.machine1.Machine {
methods:
Terminate();
Kill(in s who,
in i signal);
GetAddresses(out a(iay) addresses);
GetOSRelease(out a{ss} fields);
GetUIDShift(out u shift);
OpenPTY(out h pty,
out s pty_path);
OpenLogin(out h pty,
out s pty_path);
OpenShell(in s user,
in s path,
in as args,
in as environment,
out h pty,
out s pty_path);
BindMount(in s source,
in s destination,
in b read_only,
in b mkdir);
CopyFrom(in s source,
in s destination);
CopyTo(in s source,
in s destination);
OpenRootDirectory(out h fd);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Name = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly ay Id = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t Timestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t TimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Service = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Unit = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Leader = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Class = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s RootDirectory = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly ai NetworkInterfaces = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s State = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--method GetUIDShift is not documented!-->
<!--method OpenPTY is not documented!-->
<!--method OpenLogin is not documented!-->
<!--method OpenShell is not documented!-->
<!--method BindMount is not documented!-->
<!--method CopyFrom is not documented!-->
<!--method CopyTo is not documented!-->
<!--method OpenRootDirectory is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/>
<variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Kill()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetAddresses()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetUIDShift()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenPTY()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenLogin()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenShell()"/>
<variablelist class="dbus-method" generated="True" extra-ref="BindMount()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyFrom()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyTo()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenRootDirectory()"/>
<variablelist class="dbus-property" generated="True" extra-ref="Name"/>
<variablelist class="dbus-property" generated="True" extra-ref="Id"/>
<variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/>
<variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/>
<variablelist class="dbus-property" generated="True" extra-ref="Service"/>
<variablelist class="dbus-property" generated="True" extra-ref="Unit"/>
<variablelist class="dbus-property" generated="True" extra-ref="Leader"/>
<variablelist class="dbus-property" generated="True" extra-ref="Class"/>
<variablelist class="dbus-property" generated="True" extra-ref="RootDirectory"/>
<variablelist class="dbus-property" generated="True" extra-ref="NetworkInterfaces"/>
<variablelist class="dbus-property" generated="True" extra-ref="State"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods
take the same arguments as <function>TerminateMachine()</function> and
<function>KillMachine()</function> on the Manager interface, respectively.</para>
<para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get the IP address and OS
release information from the machine. These methods take the same arguments as
<function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the
Manager interface, respectively.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>Name</varname> is the machine name as it was passed in during registration with
<function>CreateMachine()</function> on the manager object.</para>
<para><varname>Id</varname> is the machine UUID.</para>
<para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and
monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para>
<para><varname>Service</varname> contains a short string identifying the registering service as passed
in during registration of the machine.</para>
<para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para>
<para><varname>Leader</varname> is the PID of the leader process of the machine.</para>
<para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs
based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the
same kernel as the host).</para>
<para><varname>RootDirectory</varname> is the root directory of the container if it is known and
applicable or the empty string.</para>
<para><varname>NetworkInterfaces</varname> contains an array of network interface indices that point
towards the container, the VM or the host. For details about this information see the description of
<function>CreateMachineWithNetwork()</function> above.</para>
<para><varname>State</varname> is the state of the machine and is one of <literal>opening</literal>,
<literal>running</literal>, or <literal>closing</literal>. Note that the state machine is not considered
part of the API and states might be removed or added without this being considered API breakage.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.machine1.Manager</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1
</programlisting>
</example>
<example>
<title>Introspect <interfacename>org.freedesktop.machine1.Machine</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1/machine/rawhide
</programlisting>
</example>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
</refentry>

810
man/org.freedesktop.resolve1.xml Normal file
View File

@ -0,0 +1,810 @@
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.resolve1" conditional='ENABLE_RESOLVE'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.resolve1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.resolve1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.resolve1</refname>
<refpurpose>The D-Bus interface of systemd-resolved</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS. It also
does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface.</para>
<para>This page contains an API reference only. If you are looking for a longer explanation how to use
this API, please consult
<ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers">
Writing Network Configuration Managers</ulink> and
<ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients">Writing Resolver
Clients</ulink>.
</para>
</refsect1>
<refsect1>
<title>The Manager Object</title>
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
<programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1" interface="org.freedesktop.resolve1.Manager">
node /org/freedesktop/resolve1 {
interface org.freedesktop.resolve1.Manager {
methods:
ResolveHostname(in i ifindex,
in s name,
in i family,
in t flags,
out a(iiay) addresses,
out s canonical,
out t flags);
ResolveAddress(in i ifindex,
in i family,
in ay address,
in t flags,
out a(is) names,
out t flags);
ResolveRecord(in i ifindex,
in s name,
in q class,
in q type,
in t flags,
out a(iqqay) records,
out t flags);
ResolveService(in i ifindex,
in s name,
in s type,
in s domain,
in i family,
in t flags,
out a(qqqsa(iiay)s) srv_data,
out aay txt_data,
out s canonical_name,
out s canonical_type,
out s canonical_domain,
out t flags);
GetLink(in i ifindex,
out o path);
SetLinkDNS(in i ifindex,
in a(iay) addresses);
SetLinkDomains(in i ifindex,
in a(sb) domains);
SetLinkDefaultRoute(in i ifindex,
in b enable);
SetLinkLLMNR(in i ifindex,
in s mode);
SetLinkMulticastDNS(in i ifindex,
in s mode);
SetLinkDNSOverTLS(in i ifindex,
in s mode);
SetLinkDNSSEC(in i ifindex,
in s mode);
SetLinkDNSSECNegativeTrustAnchors(in i ifindex,
in as names);
RevertLink(in i ifindex);
RegisterService(in s name,
in s name_template,
in s type,
in q service_port,
in q service_priority,
in q service_weight,
in aa{say} txt_datas,
out o service_path);
UnregisterService(in o service_path);
ResetStatistics();
FlushCaches();
ResetServerFeatures();
properties:
readonly s LLMNRHostname = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s LLMNR = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s MulticastDNS = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s DNSOverTLS = '...';
readonly a(iiay) DNS = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly a(iiay) FallbackDNS = [...];
readonly (iiay) CurrentDNSServer = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly a(isb) Domains = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly (tt) TransactionStatistics = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly (ttt) CacheStatistics = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s DNSSEC = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly (tttt) DNSSECStatistics = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b DNSSECSupported = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly as DNSSECNegativeTrustAnchors = ['...', ...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s DNSStubListener = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--method SetLinkDefaultRoute is not documented!-->
<!--method SetLinkDNSOverTLS is not documented!-->
<!--method RegisterService is not documented!-->
<!--method UnregisterService is not documented!-->
<!--method FlushCaches is not documented!-->
<!--method ResetServerFeatures is not documented!-->
<!--property LLMNR is not documented!-->
<!--property MulticastDNS is not documented!-->
<!--property DNSOverTLS is not documented!-->
<!--property FallbackDNS is not documented!-->
<!--property CurrentDNSServer is not documented!-->
<!--property DNSSEC is not documented!-->
<!--property DNSSECNegativeTrustAnchors is not documented!-->
<!--property DNSStubListener is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResolveHostname()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResolveAddress()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResolveRecord()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResolveService()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetLink()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNS()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkDomains()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkDefaultRoute()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkLLMNR()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkMulticastDNS()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSOverTLS()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSEC()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSECNegativeTrustAnchors()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RevertLink()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RegisterService()"/>
<variablelist class="dbus-method" generated="True" extra-ref="UnregisterService()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResetStatistics()"/>
<variablelist class="dbus-method" generated="True" extra-ref="FlushCaches()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ResetServerFeatures()"/>
<variablelist class="dbus-property" generated="True" extra-ref="LLMNRHostname"/>
<variablelist class="dbus-property" generated="True" extra-ref="LLMNR"/>
<variablelist class="dbus-property" generated="True" extra-ref="MulticastDNS"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSOverTLS"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNS"/>
<variablelist class="dbus-property" generated="True" extra-ref="FallbackDNS"/>
<variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServer"/>
<variablelist class="dbus-property" generated="True" extra-ref="Domains"/>
<variablelist class="dbus-property" generated="True" extra-ref="TransactionStatistics"/>
<variablelist class="dbus-property" generated="True" extra-ref="CacheStatistics"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSEC"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSECStatistics"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSECSupported"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSECNegativeTrustAnchors"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSStubListener"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para><function>ResolveHostname()</function> takes a hostname and resolves it to one or more IP addresses.
As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be
done on any suitable interface. The <varname>name</varname> parameter specifies the hostname to
resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The <varname>family</varname> parameter
limits the results to a specific address family. It may be <constant>AF_INET</constant>,
<constant>AF_INET6</constant> or <constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> is specified (recommended), both kinds are retrieved, subject
to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is
retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field may be used to alter the
behaviour of the resolver operation (see below). The method returns an array of address records. Each
address record consists of the interface index the address belongs to, an address family as well as a
byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address
family). The returned address family will be one of <constant>AF_INET</constant> or
<constant>AF_INET6</constant>. For IPv6, the returned address interface index should be used to
initialize the .sin6_scope_id field of a <structname>struct sockaddr_in6</structname> instance to permit
support for resolution to link-local IP addresses. The address array is followed by the canonical name
of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit
<varname>flags</varname> field is returned that is defined similarly to the <varname>flags</varname>
field that was passed in, but contains information about the resolved data (see below). If the hostname
passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In
this case, no network communication is done.</para>
<para><function>ResolveAddress()</function> executes the reverse operation: it takes an IP address and
acquires one or more hostnames for it. As parameters it takes the interface index to execute the query
on, or <constant>0</constant> if all suitable interfaces are OK. The <varname>family</varname>
parameter indicates the address family of the IP address to resolve. It may be either
<constant>AF_INET</constant> or <constant>AF_INET6</constant>. The <varname>address</varname> parameter
takes the raw IP address data (as either a 4 or 16 byte array). The <varname>flags</varname> input
parameter may be used to alter the resolver operation (see below). The method returns an array of name
records, each consisting of an interface index and a hostname. The <varname>flags</varname> output
field contains additional information about the resolver operation (see below).</para>
<para><function>ResolveRecord()</function> takes a DNS resource record (RR) type, class and name, and
retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the
Linux network interface index to execute the query on, or <constant>0</constant> if it may be done on
any suitable interface. The <varname>name</varname> parameter specifies the RR domain name to look up
(no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be
ANY). Finally, a <varname>flags</varname> field may be passed in to alter behaviour of the look-up (see
below). On completion, an array of RR items is returned. Each array entry consists of the network interface
index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw
RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
by the RR type, class, TTL and RDATA, in the binary format documented in
<ulink url="https://www.ietf.org/rfc/rfc1035.txt">RFC 1035</ulink>. For RRs that support name
compression in the payload (such as MX or PTR), the compression is expanded in the returned
data.</para>
<para>Note that currently, the class field has to be specified as IN or ANY. Specifying a different
class will return an error indicating that look-ups of this kind are unsupported. Similarly, some
special types are not supported either (AXFR, OPT, …). While <filename>systemd-resolved</filename> parses and validates resource
records of many types, it is crucial that clients using this API understand that the RR data originates
from the network and should be thoroughly validated before use.</para>
<para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as well as the
hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
service metadata. The primary benefit of using this method over <function>ResolveRecord()</function>
specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
name, a service type and a service domain. This method may be invoked in three different modes:</para>
<orderedlist>
<listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
Files</literal>), the service type (e.g. <literal>_webdav._tcp</literal>) and the domain to search in
(e.g. <literal>local</literal>) as the three service parameters. The service name must be in UTF-8
format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD
specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para>
</listitem>
<listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string
and set the service type and domain properly. (IDNA conversion is applied to the domain, if
necessary.)</para></listitem>
<listitem><para>Alternatively, leave both the service name and type empty and specify the full
domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA
coversion is applied in this mode.)</para></listitem>
</orderedlist>
<para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
the desired family of the addresses to resolve (use <constant>AF_INET</constant>,
<constant>AF_INET6</constant>, or <constant>AF_UNSPEC</constant>). If this is enabled (Use the
<constant>NO_ADDRESS</constant> flag to turn address resolution off, see below). The
<varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
operation.</para>
<para>On completion, <function>ResolveService()</function> returns an array of SRV record structures. Each
items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV
record. Immediately following is an array of the addresses of this hostname, with each item consisting
of the interface index, the address family and the address data in a byte array. This address array is
followed by the canonicalized hostname. After this array of SRV record structures an array of byte
arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
are the canonical service name, type and domain. This may or may not be identical to the parameters
passed in. Finally, a <varname>flags</varname> field is returned that contains information about the
resolver operation performed.</para>
<para>The <function>ResetStatistics()</function> method resets the various statistics counters that
<filename>systemd-resolved</filename> maintains to zero. (For details, see the statistics properties below.)</para>
<para>The <function>GetLink()</function> method takes a network interface index and returns the object
path to the <interfacename>org.freedesktop.resolve1.Link</interfacename> object corresponding to it.
</para>
<para>The <function>SetLinkDNS()</function> method sets the DNS servers to use on a specific
interface. This method (and the following ones) may be used by network management software to configure
per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP
address records. Each array item consists of an address family (either <constant>AF_INET</constant> or
<constant>AF_INET6</constant>), followed by a 4-byte or 16-byte array with the raw address data. This
method is a one-step shortcut for retrieving the Link object for a network interface using
<function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> method
(see below) on it.
</para>
<para>Network management software integrating with <filename>systemd-resolved</filename> should
call this method (and the five below) after the interface appeared in the kernel (and thus after a
network interface index has been assigned), but before the network interfaces is activated
(<constant>IFF_UP</constant> set) so that all settings take effect during the full time the network
interface is up. It is safe to alter settings while the interface is up, however. Use
<function>RevertLink()</function> (described below) to reset all per-interface settings.</para>
<para>The <function>SetLinkDomains()</function> method sets the search and routing domains to use on a
specific network interface for DNS look-ups. It takes a network interface index and an array of domains,
each with a boolean parameter indicating whether the specified domain shall be used as a search domain
(false), or just as a routing domain (true). Search domains are used for qualifying single-label names into
FQDN when looking up hostnames, as well as for making routing decisions on which interface to send
queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label
name qualification. Pass the search domains in the order they should be used.</para>
<para>The <function>SetLinkLLMNR()</function> method enables or disables LLMNR support on a specific
network interface. It takes a network interface index as well as a string that may either be empty or one of
<literal>yes</literal>, <literal>no</literal> or <literal>resolve</literal>. If empty, the systemd-wide
default LLMNR setting is used. If <literal>yes</literal>, LLMNR is used for resolution of single-label
names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If
<literal>no</literal>, LLMNR is turned off fully on this interface. If <literal>resolve</literal>, LLMNR
is only enabled for resolving names, but the local hostname is not registered for other peers to
use.</para>
<para>Similarly, the <function>SetLinkMulticastDNS()</function> method enables or disables MulticastDNS
support on a specific interface. It takes the same parameters as <function>SetLinkLLMNR()</function>
described above.</para>
<para>The <function>SetLinkDNSSEC()</function> method enables or disables DNSSEC validation on a
specific network interface. It takes a network interface index as well as a string that may either be
empty or one of <literal>yes</literal>, <literal>no</literal>, or <literal>allow-downgrade</literal>. When
empty, the system-wide default DNSSEC setting is used. If <literal>yes</literal>, full DNSSEC validation
is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this
mode is used. If <literal>no</literal>, DNSSEC validation is fully disabled. If
<literal>allow-downgrade</literal>, DNSSEC validation is enabled, but is turned off automatically if the
selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC
only applies to traditional DNS, not to LLMNR or MulticastDNS.</para>
<para>The <function>SetLinkDNSSECNegativeTrustAnchors()</function> method may be used to configure DNSSEC
Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a
list of domains as arguments.</para>
<para>The <function>RevertLink()</function> method may be used to revert all per-link settings done with
the six methods described above to the defaults again.</para>
<refsect3>
<title>The Flags Parameter</title>
<para>The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
and recommended. However, the following flags are defined to alter the look-up:</para>
<programlisting>
#define SD_RESOLVED_DNS (UINT64_C(1) &lt;&lt; 0)
#define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) &lt;&lt; 1)
#define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) &lt;&lt; 2)
#define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) &lt;&lt; 3)
#define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) &lt;&lt; 4)
#define SD_RESOLVED_NO_CNAME (UINT64_C(1) &lt;&lt; 5)
#define SD_RESOLVED_NO_TXT (UINT64_C(1) &lt;&lt; 6)
#define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) &lt;&lt; 7)
#define SD_RESOLVED_NO_SEARCH (UINT64_C(1) &lt;&lt; 8)
#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) &lt;&lt; 9)
</programlisting>
<para>On input, the first five flags control the protocols to use for the look-up. They refer to
classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the
look-up will be done via all suitable protocols for the specific look-up. Note that these flags
operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, <filename>systemd-resolved</filename>
will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address
domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route
neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces
suitable for multicast.</para>
<para>On output, these five flags indicate which protocol was used to execute the operation, and hence
where the data was found.</para>
<para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
used to discover the first DNS result.</para>
<para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
look-up. This flag is only available at input, none of the functions will return it on output. If a
CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default,
when the flag is off, CNAME/DNAME RRs are followed.</para>
<para>The NO_TXT and NO_ADDRESS flags only influence operation of the
<function>ResolveService()</function> method. They are only defined for input, not output. If
NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified,
the hostnames discovered are not implicitly translated to their addresses.</para>
<para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
<function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
will never qualify single-label domain names using search domains. Also note that
multi-label hostnames are never subject to search list expansion.</para>
<para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data
for which a full trust chain may be established to a trusted domain anchor. It is also set for locally
synthesized data, such as <literal>localhost</literal> or data from
<filename>/etc/hosts</filename>. Moreover, it is set for all LLMNR or mDNS RRs which originate from the
local host. Applications that require authenticated RR data for operation should check this flag before
trusting the data. Note that <filename>systemd-resolved</filename> will never return invalidated data, hence this flag
simply allows to discern the cases where data is known to be trustable, or where there is proof that
the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server
does not support authenticating data).</para>
</refsect3>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>LLMNRHostname</varname> contains the hostname currently exposed on the network via
LLMNR. It usually follows the system hostname as may be queried via
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but may differ if a conflict is detected on the network.</para>
<para><varname>DNS</varname> contains an array of all DNS servers currently used by
<filename>systemd-resolved</filename>. It contains similar information as the DNS server data written to
/run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface
index, an address family, and a byte array containing the DNS server address (either 4 bytes in length
for IPv4 or 16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide,
including those possibly read from a foreign <filename>/etc/resolv.conf</filename> or the
<varname>DNS=</varname> setting in <filename>/etc/systemd/resolved.conf</filename>, as well as
per-interface DNS server information either retrieved from
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
or configured by external software via <function>SetLinkDNS()</function> (see above). The network
interface index will be 0 for the system-wide configured services and non-zero for the per-link
servers.</para>
<para>Similarly, the <varname>Domains</varname> property contains an array of all search and
routing domains currently used by <filename>systemd-resolved</filename>. Each entry consists of a network interface index (again, 0
encodes system-wide entries), the actual domain name, and whether the entry is used only for routing
(true) or for both routing and searching (false).</para>
<para>The <varname>TransactionStatistics</varname> property contains information about the number of
transactions <filename>systemd-resolved</filename> has processed. It contains a pair of unsigned 64-bit counters, the first
containing the number of currently ongoing transactions, the second the number of total transactions
<filename>systemd-resolved</filename> is processing or has processed. The latter value may be reset using the
<function>ResetStatistics()</function> method described above. Note that the number of transactions does
not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a
single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC
are in use.</para>
<para>The <varname>CacheStatistics</varname> property contains information about the executed cache
operations so far. It exposes three 64-bit counters: the first being the total number of current cache
entries (both positive and negative), the second the number of cache hits, and the third the number of
cache misses. The latter counters may be reset using <function>ResetStatistics()</function> (see
above). </para>
<para>The <varname>DNSSECStatistics</varname> property contains information about the DNSSEC
validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus,
and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and
each non-existance proof. The secure counter is increased for each operation that successfully verified
a signed reply, the insecure counter is increased for each operation that successfully verified that an
unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
validation did not check out and the data is likely to have been tempered with. Finally the
indeterminate counter is increased for each operation which did not complete because the necessary keys
could not be acquired or the cryptographic algorithms were unknown.</para>
<para>The <varname>DNSSECSupported</varname> boolean property reports whether DNSSEC is enabled and
the selected DNS servers support it. It combines information about system-wide and per-link DNS
settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for
which DNS is configured and for the system-wide settings if there are any. Note that <filename>systemd-resolved</filename> assumes
DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported
value may initially be true, until the first transactions are executed.</para>
<para>The <varname>LogLevel</varname> property shows the (maximum) log level of the manager, with the
same values as the <option>--log-level=</option> option described in
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Link Object</title>
<programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1/link/_1" interface="org.freedesktop.resolve1.Link">
node /org/freedesktop/resolve1/link/_1 {
interface org.freedesktop.resolve1.Link {
methods:
SetDNS(in a(iay) addresses);
SetDomains(in a(sb) domains);
SetDefaultRoute(in b enable);
SetLLMNR(in s mode);
SetMulticastDNS(in s mode);
SetDNSOverTLS(in s mode);
SetDNSSEC(in s mode);
SetDNSSECNegativeTrustAnchors(in as names);
Revert();
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t ScopesMask = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly a(iay) DNS = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly (iay) CurrentDNSServer = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly a(sb) Domains = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b DefaultRoute = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s LLMNR = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s MulticastDNS = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s DNSOverTLS = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s DNSSEC = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly as DNSSECNegativeTrustAnchors = ['...', ...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b DNSSECSupported = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--method SetDomains is not documented!-->
<!--method SetDefaultRoute is not documented!-->
<!--method SetLLMNR is not documented!-->
<!--method SetMulticastDNS is not documented!-->
<!--method SetDNSOverTLS is not documented!-->
<!--method SetDNSSEC is not documented!-->
<!--method SetDNSSECNegativeTrustAnchors is not documented!-->
<!--method Revert is not documented!-->
<!--property CurrentDNSServer is not documented!-->
<!--property DefaultRoute is not documented!-->
<!--property LLMNR is not documented!-->
<!--property MulticastDNS is not documented!-->
<!--property DNSOverTLS is not documented!-->
<!--property DNSSEC is not documented!-->
<!--property DNSSECNegativeTrustAnchors is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDNS()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDomains()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDefaultRoute()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLLMNR()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetMulticastDNS()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDNSOverTLS()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDNSSEC()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetDNSSECNegativeTrustAnchors()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Revert()"/>
<variablelist class="dbus-property" generated="True" extra-ref="ScopesMask"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNS"/>
<variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServer"/>
<variablelist class="dbus-property" generated="True" extra-ref="Domains"/>
<variablelist class="dbus-property" generated="True" extra-ref="DefaultRoute"/>
<variablelist class="dbus-property" generated="True" extra-ref="LLMNR"/>
<variablelist class="dbus-property" generated="True" extra-ref="MulticastDNS"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSOverTLS"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSEC"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSECNegativeTrustAnchors"/>
<variablelist class="dbus-property" generated="True" extra-ref="DNSSECSupported"/>
<!--End of Autogenerated section-->
<para>For each Linux network interface a "Link" object is created which exposes per-link DNS
configuration and state. Use <function>GetLink()</function> on the Manager interface to retrieve the
object path for a link object given the network interface index (see above).</para>
<refsect2>
<title>Methods</title>
<para>The various methods exposed by the Link interface are equivalent to their similarly named
counterparts on the Manager interface. e.g. <function>SetDNS()</function> on the Link object maps to
<function>SetLinkDNS()</function> on the Manager object, the main difference being that the later
expects an interface index to be specified. Invoking the methods on the Manager interface has the
benefit of reducing roundtrips, as it is not necessary to first request the Link object path via
<function>GetLink()</function> before invoking the methods. For further details on these methods see
the <interfacename>Manager</interfacename> documentation above.</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>ScopesMask</varname> defines which resolver scopes are currently active on this
interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the
flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific
interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in
the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR
and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured*
to be used on the interface, the former expose what is actually used on the interface, taking into
account the abilities of the interface.</para>
<para><varname>DNSSECSupported</varname> exposes a boolean field that indicates whether DNSSEC is
currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is
assumed available until it is detected that the configured server does not actually support it. Thus,
this property may initially report that DNSSEC is supported on an interface.</para>
<para>The other properties reflect the state of the various configuration settings for the link which
may be set with the various methods calls such as SetDNS() or SetLLMNR().</para>
</refsect2>
</refsect1>
<refsect1>
<title>Common Errors</title>
<para>Many bus methods <filename>systemd-resolved</filename> exposes (in particular the resolver methods such
as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) may return
some of the following errors:</para>
<variablelist>
<varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers</constant></term>
<listitem><para>No suitable DNS servers were found to resolve a request.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply</constant></term>
<listitem><para>A response from the selected DNS server was not understood.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR</constant></term>
<listitem><para>The requested name exists, but there is no resource record of the requested type for
it. (This is the DNS NODATA case).</para></listitem></varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.CNameLoop</constant></term>
<listitem><para>The look-up failed because a CNAME or DNAME loop was detected.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.Aborted</constant></term>
<listitem><para>The look-up was aborted because the selected protocol became unavailable while the
operation was ongoing.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term>
<listitem><para>A service look-up was successful, but the SRV record reported that the service is not
available.</para></listitem></varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term>
<listitem><para>The acquired response did not pass DNSSEC validation.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor</constant></term>
<listitem><para>No chain of trust could be established for the response to a configured DNSSEC trust
anchor.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.ResourceRecordTypeUnsupported</constant></term>
<listitem><para>The requested resource record type is not supported on the selected DNS servers. This
error is generated for example when an RRSIG record is requested from a DNS server that does not
support DNSSEC.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchLink</constant></term>
<listitem><para>No network interface with the specified network interface index exists.
</para></listitem></varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy</constant></term>
<listitem><para>The requested configuration change could not be made because
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
already took possession of the interface and supplied configuration data for it.</para></listitem>
</varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.NetworkDown</constant></term>
<listitem><para>The requested look-up failed because the system is currently not connected to any
suitable network.</para></listitem></varlistentry>
<varlistentry><term><constant>org.freedesktop.resolve1.DnsError.NXDOMAIN</constant></term>
<term><constant>org.freedesktop.resolve1.DnsError.REFUSED</constant></term>
<term>...</term>
<listitem><para>The look-up failed with a DNS return code reporting a failure. The error names used as
suffixes here are defined in by IANA in
<ulink url="https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6">DNS RCODEs</ulink>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.resolve1.Manager</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.resolve1 \
--object-path /org/freedesktop/resolve1
</programlisting>
</example>
<example>
<title>Introspect <interfacename>org.freedesktop.resolve1.Link</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.resolve1 \
--object-path /org/freedesktop/resolve1/link/_11
</programlisting>
</example>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
</refentry>

9400
man/org.freedesktop.systemd1.xml Normal file
View File

File diff suppressed because it is too large Load Diff

205
man/org.freedesktop.timedate1.xml Normal file
View File

@ -0,0 +1,205 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="org.freedesktop.timedate1" conditional='ENABLE_TIMEDATED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.timedate1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.timedate1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.timedate1</refname>
<refpurpose>The D-Bus interface of systemd-timedated</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that can be used to control the system time and related settings. This page
describes the D-Bus interface.</para>
</refsect1>
<refsect1>
<title>The D-Bus API</title>
<para>The service exposes the following interfaces on the bus:</para>
<programlisting executable="systemd-timedated" node="/org/freedesktop/timedate1" interface="org.freedesktop.timedate1">
node /org/freedesktop/timedate1 {
interface org.freedesktop.timedate1 {
methods:
SetTime(in x usec_utc,
in b relative,
in b interactive);
SetTimezone(in s timezone,
in b interactive);
SetLocalRTC(in b local_rtc,
in b fix_system,
in b interactive);
SetNTP(in b use_ntp,
in b interactive);
ListTimezones(out as timezones);
properties:
readonly s Timezone = '...';
readonly b LocalRTC = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b CanNTP = ...;
readonly b NTP = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b NTPSynchronized = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t TimeUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t RTCTimeUSec = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
</programlisting>
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.timedate1"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetTime()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetTimezone()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetLocalRTC()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetNTP()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListTimezones()"/>
<variablelist class="dbus-property" generated="True" extra-ref="Timezone"/>
<variablelist class="dbus-property" generated="True" extra-ref="LocalRTC"/>
<variablelist class="dbus-property" generated="True" extra-ref="CanNTP"/>
<variablelist class="dbus-property" generated="True" extra-ref="NTP"/>
<variablelist class="dbus-property" generated="True" extra-ref="NTPSynchronized"/>
<variablelist class="dbus-property" generated="True" extra-ref="TimeUSec"/>
<variablelist class="dbus-property" generated="True" extra-ref="RTCTimeUSec"/>
<!--End of Autogenerated section-->
<refsect2>
<title>Methods</title>
<para>Use <function>SetTime()</function> to change the system clock. Pass a value of microseconds since
the UNIX epoch (1 Jan 1970 UTC). If <varname>relative</varname> is true, the passed usec value will be
added to the current system time. If it is false, the current system time will be set to the passed usec
value. If the system time is set with this method, the RTC will be updated as well.</para>
<para>Use <function>SetTimezone()</function> to set the system timezone. Pass a value like
<literal>Europe/Berlin</literal> to set the timezone. Valid timezones are listed in
<filename>/usr/share/zoneinfo/zone.tab</filename>. If the RTC is configured to be maintained in local
time, it will be updated accordingly.</para>
<para>Use <function>SetLocalRTC()</function> to control whether the RTC is in local time or UTC. It is
strongly recommended to maintain the RTC in UTC. However, some OSes (Windows) maintain the RTC in local
time, which might make it necessary to enable this feature. Note that this might create various problems as
daylight changes could be missed. If <varname>fix_system</varname> is <literal>true</literal>,
the time from the RTC is read again and the system clock is adjusted according to the new setting. If
<varname>fix_system</varname> is <literal>false</literal>, the system time is written to the RTC
taking the new setting into account. Use <varname>fix_system=true</varname> in installers and livecds
where the RTC is probably more reliable than the system time. Use <varname>fix_system=false</varname>
in configuration UIs that are run during normal operation and where the system clock is probably more
reliable than the RTC.</para>
<para>Use <function>SetNTP()</function> to control whether the system clock is synchronized with the
network using <filename>systemd-timesyncd</filename>. This will enable and start or disable and stop
the chosen time synchronization service.</para>
<para><function>ListTimezones()</function> returns a list of time zones known on the local system as an
array of names (<literal>["Africa/Abidjan", "Africa/Accra", ..., "UTC"]</literal>).</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>Timezone</varname> shows the currently configured time zone.
<varname>LocalRTC</varname> shows whether the RTC is configured to use UTC (false), or the local time
zone (true). <varname>CanNTP</varname> shows whether a service to perform time synchronization over the
network is available, and <varname>NTP</varname> shows whether such a service is enabled.</para>
<para><varname>NTPSynchronized</varname> shows whether the kernel reports the time as synchronized
(c.f.
<citerefentry project="man-pages"><refentrytitle>adjtimex</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
<varname>TimeUSec</varname> and <varname>RTCTimeUSec</varname> show the current time on the system and
in the RTC. The purpose of those three properties is to allow remote clients to access this information
over D-Bus. Local clients can access the information directly.</para>
<para>Whenever the <varname>Timezone</varname> and <varname>LocalRTC</varname> settings are changed via
the daemon, <function>PropertyChanged</function> signals are sent out to which clients can subscribe.
</para>
<para>Note that this service will not inform you about system time changes. Use
<citerefentry project="man-pages"><refentrytitle>timerfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
with <constant>CLOCK_REALTIME</constant> and <constant>TFD_TIMER_CANCEL_ON_SET</constant> for that.
</para>
</refsect2>
<refsect2>
<title>Security</title>
<para>The <varname>interactive</varname> boolean parameters can be used to control whether
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
should interactively ask the user for authentication credentials if required.</para>
<para>The polkit action for <function>SetTimezone()</function> is
<interfacename>org.freedesktop.timedate1.set-timezone</interfacename>. For
<function>SetLocalRTC()</function> it is
<interfacename>org.freedesktop.timedate1.set-local-rtc</interfacename>, for
<function>SetTime()</function> it is <interfacename>org.freedesktop.timedate1.set-time</interfacename>
and for <function>SetNTP()</function> it is
<interfacename>org.freedesktop.timedate1.set-ntp</interfacename>.
<function>ListTimezones()</function> does not require any privileges.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.timedate1</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.timedate1 \
--object-path /org/freedesktop/timedate1
</programlisting>
</example>
</refsect1>
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para><ulink url="https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html">More information on how the system clock and RTC interact</ulink></para>
</refsect1>
</refentry>

42
man/os-release.xml
View File

@ -192,13 +192,11 @@
<varlistentry>
<term><varname>ANSI_COLOR=</varname></term>
<listitem><para>A suggested presentation color when showing
the OS name on the console. This should be specified as string
suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code
for setting graphical rendition. This field is optional.
Example: <literal>ANSI_COLOR="0;31"</literal> for red, or
<literal>ANSI_COLOR="1;34"</literal> for light
blue.</para></listitem>
<listitem><para>A suggested presentation color when showing the OS name on the console. This should
be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
graphical rendition. This field is optional. Example: <literal>ANSI_COLOR="0;31"</literal> for red,
<literal>ANSI_COLOR="1;34"</literal> for light blue, or
<literal>ANSI_COLOR="0;38;2;60;110;180"</literal> for Fedora blue.</para></listitem>
</varlistentry>
<varlistentry>
@ -220,7 +218,7 @@
<term><varname>BUG_REPORT_URL=</varname></term>
<term><varname>PRIVACY_POLICY_URL=</varname></term>
<listitem><para>Links to resources on the Internet related to
<listitem><para>Links to resources on the Internet related to
the operating system.
<varname>HOME_URL=</varname> should refer to the homepage of
the operating system, or alternatively some homepage of the
@ -341,20 +339,36 @@
name in order to avoid name clashes. Applications
reading this file must ignore unknown fields. Example:
<literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
<para>Container and sandbox runtime managers may make the host's
identification data available to applications by providing the host's
<filename>/etc/os-release</filename> (if available, otherwise
<filename>/usr/lib/os-release</filename> as a fallback) as
<filename>/run/host/os-release</filename>.</para>
</refsect1>
<refsect1>
<title>Example</title>
<programlisting>NAME=Fedora
VERSION="17 (Beefy Miracle)"
VERSION="32 (Workstation Edition)"
ID=fedora
VERSION_ID=17
PRETTY_NAME="Fedora 17 (Beefy Miracle)"
ANSI_COLOR="0;34"
CPE_NAME="cpe:/o:fedoraproject:fedora:17"
VERSION_ID=32
PRETTY_NAME="Fedora 32 (Workstation Edition)"
ANSI_COLOR="0;38;2;60;110;180"
LOGO=fedora-logo-icon
CPE_NAME="cpe:/o:fedoraproject:fedora:32"
HOME_URL="https://fedoraproject.org/"
BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
BUG_REPORT_URL="https://bugzilla.redhat.com/"
REDHAT_BUGZILLA_PRODUCT="Fedora"
REDHAT_BUGZILLA_PRODUCT_VERSION=32
REDHAT_SUPPORT_PRODUCT="Fedora"
REDHAT_SUPPORT_PRODUCT_VERSION=32
PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
VARIANT="Workstation Edition"
VARIANT_ID=workstation</programlisting>
</refsect1>
<refsect1>

4
man/pam_systemd.xml
View File

@ -153,7 +153,7 @@
hence be used to uniquely label files or other resources of this session. Combine this ID with the boot
identifier, as returned by
<citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, for a
globally unique identifier for the current session.</para></listitem>
globally unique identifier.</para></listitem>
</varlistentry>
<varlistentry>
@ -253,7 +253,7 @@
<para> See
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information about the resources.
Also, see <citerefentry><refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> for additional information about how to set
Also, see <citerefentry project='man-pages'><refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> for additional information about how to set
the context objects.
</para>

Some files were not shown because too many files have changed in this diff Show More