package: systemd

title: org.freedesktop.timedate1(5)

summary: The D\-Bus interface of systemd\-timedated

text:
# org.freedesktop.timedate1(5)

## NAME
org.freedesktop.timedate1 - The D-Bus interface of systemd-timedated

## INTRODUCTION
systemd-timedated.service(8) is a system service that can be used to control the system time and related settings. This page describes the D-Bus interface.

## THE D-BUS API
The service exposes the following interfaces on the bus:

```
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 { ... };
};
```

### Methods
Use SetTime() to change the system clock. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC). If relative 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.

Use SetTimezone() to set the system timezone. Pass a value like "Europe/Berlin" to set the timezone. Valid timezones are listed in /usr/share/zoneinfo/zone.tab. If the RTC is configured to be maintained in local time, it will be updated accordingly.

Use SetLocalRTC() 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 fix_system is "true", the time from the RTC is read again and the system clock is adjusted according to the new setting. If fix_system is "false", the system time is written to the RTC taking the new setting into account. Use fix_system=true in installers and livecds where the RTC is probably more reliable than the system time. Use fix_system=false in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC.

Use SetNTP() to control whether the system clock is synchronized with the network using systemd-timesyncd. This will enable and start or disable and stop the chosen time synchronization service.

ListTimezones() returns a list of time zones known on the local system as an array of names ("["Africa/Abidjan", "Africa/Accra", ..., "UTC"]").

### Properties
Timezone shows the currently configured time zone. LocalRTC shows whether the RTC is configured to use UTC (false), or the local time zone (true). CanNTP shows whether a service to perform time synchronization over the network is available, and NTP shows whether such a service is enabled.

NTPSynchronized shows whether the kernel reports the time as synchronized (c.f. adjtimex(3)). TimeUSec and RTCTimeUSec 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.

Whenever the Timezone and LocalRTC settings are changed via the daemon, PropertyChanged signals are sent out to clients which have subscribed.

Note that this service will not inform you about system time changes. Use timerfd(3) with CLOCK_REALTIME and TFD_TIMER_CANCEL_ON_SET for that.

### Security
The interactive boolean parameters can be used to control whether polkit[1] should interactively ask the user for authentication credentials if required.

The polkit action for SetTimezone() is org.freedesktop.timedate1.set-timezone. For SetLocalRTC() it is org.freedesktop.timedate1.set-local-rtc, for SetTime() it is org.freedesktop.timedate1.set-time and for SetNTP() it is org.freedesktop.timedate1.set-ntp. ListTimezones() does not require any privileges.

## EXAMPLES
Example 1. Introspect org.freedesktop.timedate1 on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.timedate1 \

  --object-path /org/freedesktop/timedate1
```

## VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[2].

## SEE ALSO
systemd(1), systemd-timedated.service(8), timedatectl(1), More information on how the system clock and RTC interact[3]

## NOTES
1.

polkit

https://www.freedesktop.org/software/polkit/docs/latest/

2.

the usual interface versioning guidelines

https://0pointer.de/blog/projects/versioning-dbus.html

3.

More information on how the system clock and RTC interact

https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html


os-release

title: os-release(5)

summary: Operating system identification

text:
# os-release(5)

## NAME
os-release, initrd-release, extension-release - Operating system identification

## SYNOPSIS
/etc/os-release

/usr/lib/os-release

/etc/initrd-release

/usr/lib/extension-release.d/extension-release.IMAGE

## DESCRIPTION
The /etc/os-release and /usr/lib/os-release files contain operating system identification data.

The format of os-release is a newline-separated list of environment-like shell-compatible variable assignments. It is possible to source the configuration from Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this means variable expansion is explicitly not supported), allowing applications to read the file without implementing a shell compatible execution engine. Variable assignment values must be enclosed in double or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z, 0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes, following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#" are treated as comments. Blank lines are permitted and ignored.

The file /etc/os-release takes precedence over /usr/lib/os-release. Applications should check for the former, and exclusively use its data if it exists, and only fall back to /usr/lib/os-release if that is missing. Applications should not combine the data from both files. /usr/lib/os-release is the recommended place to store OS release information as part of vendor trees. /etc/os-release should be a relative symlink to /usr/lib/os-release, to provide compatibility with applications only looking at /etc/. A relative symlink instead of an absolute symlink is necessary to avoid breaking the link in a chroot or initrd environment.

os-release contains data that is defined by the operating system vendor and should generally not be changed by the administrator.

As this file only encodes names and identifiers it should not be localized.

The /etc/os-release and /usr/lib/os-release files might be symlinks to other files, but it is important that the file is available from earliest boot on, and hence must be located on the root file system.

os-release must not contain repeating keys. Nevertheless, readers should pick the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A reader may warn about repeating entries.

For a longer rationale for os-release please refer to the Announcement of /etc/os-release[1].

### /etc/initrd-release
In the initrd[2] and exitrd, /etc/initrd-release plays the same role as os-release in the main system. Additionally, the presence of that file means that the system is in the initrd/exitrd phase. /etc/os-release should be symlinked to /etc/initrd-release (or vice versa), so programs that only look for /etc/os-release (as described above) work correctly.

The rest of this document that talks about os-release should be understood to apply to initrd-release too.

### /usr/lib/extension-release.d/extension-release.IMAGE
/usr/lib/extension-release.d/extension-release.IMAGE plays the same role for extension images as os-release for the main system, and follows the syntax and rules as described in the Portable Services[3] page. The purpose of this file is to identify the extension and to allow the operating system to verify that the extension image matches the base OS. This is typically implemented by checking that the extension ID= option either matches the host ID= option or is included the host ID_LIKE= option, and either SYSEXT_LEVEL= exists and matches too, or if it is not present, VERSION_ID= exists and matches. This ensures ABI/API compatibility between the layers and prevents merging of an incompatible image in an overlay.

In order to identify the extension image itself, the same fields defined below can be added to the extension-release file with a SYSEXT_ prefix (to disambiguate from fields used to match on the base image). E.g.: SYSEXT_ID=myext, SYSEXT_VERSION_ID=1.2.3.

In the extension-release.IMAGE filename, the IMAGE part must exactly match the file name of the containing image with the suffix removed. In case it is not possible to guarantee that an image file name is stable and does not change between the build and the deployment phases, it is possible to relax this check: if exactly one file whose name matches "extension-release.*" is present in this directory, and the file is tagged with a user.extension-release.strict xattr(7) set to the string "0", it will be used instead.

The rest of this document that talks about os-release should be understood to apply to extension-release too.

## OPTIONS
The following OS identifications parameters may be set using os-release:

### General information identifying the operating system
NAME=

A string identifying the operating system, without a version component, and suitable for presentation to the user. If not set, a default of "NAME=Linux" may be used. Examples: "NAME=Fedora", "NAME="Debian GNU/Linux"".

ID=

A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system, excluding any version information and suitable for processing by scripts or usage in generated filenames. If not set, a default of "ID=linux" may be used. Note that even though this string may not include characters that require shell quoting, quoting may nevertheless be used. Examples: "ID=fedora", "ID=debian".

ID_LIKE=

A space-separated list of operating system identifiers in the same syntax as the ID= setting. It should list identifiers of operating systems that are closely related to the local operating system in regards to packaging and programming interfaces, for example listing one or more OS identifiers the local OS is a derivative from. An OS should generally only list other OS identifiers it itself is a derivative of, and not any OSes that are derived from it, though symmetric relationships are possible. Build scripts and similar should check this variable if they need to identify the local operating system and the value of ID= is not recognized. Operating systems should be listed in order of how closely the local operating system relates to the listed ones, starting with the closest. This field is optional. Examples: for an operating system with "ID=centos", an assignment of "ID_LIKE="rhel fedora"" would be appropriate. For an operating system with "ID=ubuntu", an assignment of "ID_LIKE=debian" is appropriate.

PRETTY_NAME=

A pretty operating system name in a format suitable for presentation to the user. May or may not contain a release code name or OS version of some kind, as suitable. If not set, a default of "PRETTY_NAME="Linux"" may be used Example: "PRETTY_NAME="Fedora 17 (Beefy Miracle)"".

CPE_NAME=

A CPE name for the operating system, in URI binding syntax, following the Common Platform Enumeration Specification[4] as proposed by the NIST. This field is optional. Example: "CPE_NAME="cpe:/o:fedoraproject:fedora:17""

VARIANT=

A string identifying a specific variant or edition of the operating system suitable for presentation to the user. This field may be used to inform the user that the configuration of this system is subject to a specific divergent set of rules or default configuration settings. This field is optional and may not be implemented on all systems. Examples: "VARIANT="Server Edition"", "VARIANT="Smart Refrigerator Edition"".

Note: this field is for display purposes only. The VARIANT_ID field should be used for making programmatic decisions.

Added in version 220.

VARIANT_ID=

A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and "-"), identifying a specific variant or edition of the operating system. This may be interpreted by other packages in order to determine a divergent default configuration. This field is optional and may not be implemented on all systems. Examples: "VARIANT_ID=server", "VARIANT_ID=embedded".

Added in version 220.

### Information about the version of the operating system
VERSION=

A string identifying the operating system version, excluding any OS name information, possibly including a release code name, and suitable for presentation to the user. This field is optional. Examples: "VERSION=17", "VERSION="17 (Beefy Miracle)"".

VERSION_ID=

A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information or release code name, and suitable for processing by scripts or usage in generated filenames. This field is optional. Examples: "VERSION_ID=17", "VERSION_ID=11.04".

VERSION_CODENAME=

A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system release code name, excluding any OS name information or release version, and suitable for processing by scripts or usage in generated filenames. This field is optional and may not be implemented on all systems. Examples: "VERSION_CODENAME=buster", "VERSION_CODENAME=xenial".

Added in version 231.

BUILD_ID=

A string uniquely identifying the system image originally used as the installation base. In most cases, VERSION_ID or IMAGE_ID+IMAGE_VERSION are updated when the entire system image is replaced during an update. BUILD_ID may be used in distributions where the original installation image version is important: VERSION_ID would change during incremental system updates, but BUILD_ID would not. This field is optional. Examples: "BUILD_ID="2013-03-20.3"", "BUILD_ID=201303203".

Added in version 200.

IMAGE_ID=

A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and "-"), identifying a specific image of the operating system. This is supposed to be used for environments where OS images are prepared, built, shipped and updated as comprehensive, consistent OS images. This field is optional and may not be implemented on all systems, in particularly not on those that are not managed via images but put together and updated from individual packages and on the local system. Examples: "IMAGE_ID=vendorx-cashier-system", "IMAGE_ID=netbook-image".

Added in version 249.

IMAGE_VERSION=

A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with IMAGE_ID described above, to discern different versions of the same image. Examples: "IMAGE_VERSION=33", "IMAGE_VERSION=47.1rc1".

Added in version 249.

RELEASE_TYPE=

A lower-case string (no spaces or other characters outside of 0-9, a-z, ".", "_", and "-"), describing what kind of release this version of the OS is. Known values follow:

•"stable" is for normal releases of the system, suitable for production use. Generally, stable releases become end-of-life soon after the next major stable release is out, although this might not be the case if, for example, a distribution adopts a rolling release model and still be production ready. Examples include Fedora 40, Ubuntu 23.10, OpenSUSE Tumbleweed, and Arch Linux.

•"lts" is for long term support releases of the system, suitable for production use and supported for an extended period of time. Generally, LTS releases continue to receive support even if newer major releases of the distribution are available. Examples include Ubuntu 24.04, Debian 12 Bookworm, and RHEL 9.4.

•"development" is for unstable versions of the system, unsuitable for production use, such as alpha, beta, or rolling unstable releases. Examples include Fedora Rawhide, Debian Testing, Fedora 40 Beta, and GNOME OS Nightly.

•"experiment" is for experimental builds of the system, created specifically to test some work-in-progress feature. This is meant to be used in combination with EXPERIMENT=.

If unset, or an unknown value, assume that the release is "stable".

Examples: "RELEASE_TYPE=development", "RELEASE_TYPE=lts".

Added in version 257.

To summarize: if the image updates are built and shipped as comprehensive units, IMAGE_ID+IMAGE_VERSION is the best fit. Otherwise, if updates eventually completely replace previously installed contents, as in a typical binary distribution, VERSION_ID should be used to identify major releases of the operating system. BUILD_ID may be used instead or in addition to VERSION_ID when the original system image version is important.

### Presentation information and links
HOME_URL=, DOCUMENTATION_URL=, SUPPORT_URL=, BUG_REPORT_URL=, PRIVACY_POLICY_URL=

Links to resources on the Internet related to the operating system. HOME_URL= should refer to the homepage of the operating system, or alternatively some homepage of the specific version of the operating system. DOCUMENTATION_URL= should refer to the main documentation page for this operating system. SUPPORT_URL= should refer to the main support page for the operating system, if there is any. This is primarily intended for operating systems which vendors provide support for. BUG_REPORT_URL= should refer to the main bug reporting page for the operating system, if there is any. This is primarily intended for operating systems that rely on community QA. PRIVACY_POLICY_URL= should refer to the main privacy policy page for the operating system, if there is any. These settings are optional, and providing only some of these settings is common. These URLs are intended to be exposed in "About this system" UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a Bug", or "Privacy Policy". The values should be in RFC3986 format[5], and should be "http:" or "https:" URLs, and possibly "mailto:" or "tel:". Only one URL shall be listed in each setting. If multiple resources need to be referenced, it is recommended to provide an online landing page linking all available resources. Examples: "HOME_URL="https://fedoraproject.org/"", "BUG_REPORT_URL="https://bugzilla.redhat.com/"".

SUPPORT_END=

The date at which support for this version of the OS ends. (What exactly "lack of support" means varies between vendors, but generally users should assume that updates, including security fixes, will not be provided.) The value is a date in the ISO 8601 format "YYYY-MM-DD", and specifies the first day on which support is not provided. For example, "SUPPORT_END=2001-01-01" means that the system was supported until the end of the last day of the previous millennium.

Added in version 252.

LOGO=

A string, specifying the name of an icon as defined by freedesktop.org Icon Theme Specification[6]. This can be used by graphical applications to display an operating system's or distributor's logo. This field is optional and may not necessarily be implemented on all systems. Examples: "LOGO=fedora-logo", "LOGO=distributor-logo-opensuse"

Added in version 240.

ANSI_COLOR=

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. Examples: "ANSI_COLOR="0;31"" for red, "ANSI_COLOR="1;34"" for light blue, or "ANSI_COLOR="0;38;2;60;110;180"" for Fedora blue.

VENDOR_NAME=

The name of the OS vendor. This is the name of the organization or company which produces the OS. This field is optional. This name is intended to be exposed in "About this system" UIs or software update UIs when needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.

Examples: "VENDOR_NAME="Fedora Project"" for Fedora Linux, "VENDOR_NAME="Canonical"" for Ubuntu.

Added in version 254.

VENDOR_URL=

The homepage of the OS vendor. This field is optional. The VENDOR_NAME= field should be set if this one is, although clients must be robust against either field not being set. The value should be in RFC3986 format[5], and should be "http:" or "https:" URLs. Only one URL shall be listed in the setting.

Examples: "VENDOR_URL="https://fedoraproject.org/"", "VENDOR_URL="https://canonical.com/"".

Added in version 254.

EXPERIMENT=

A human-presentable description of what makes this build of the OS experimental. This field is optional. The RELEASE_TYPE field should be set to "experiment" if this field is set, otherwise clients should ignore this field. This description is intended to be exposed at system installation time, or in "About this system" UIs, to warn the user that they're installing/running an experimental build of the OS. If RELEASE_TYPE is "experiment" but this field is unset, the UI should still warn the user, but it will be unable to explain what exactly is experimental about the current build of the OS.

Examples: "EXPERIMENT="Switch to DNF5"" for an experimental build of Fedora Linux made to test DNF5, "EXPERIMENT="Port to Apple M3 chip"" for experimental builds of Asahi Linux ported to the Apple M3 SoC, "EXPERIMENT="Mutter !1441: Dynamic triple/double buffering (v4)"" for builds of GNOME OS created by Mutter's CI for merge request !1441.

Added in version 257.

EXPERIMENT_URL=

The main informational page about what makes the current OS build experimental, where users can learn more about the experiment's status and potentially leave feedback. This field is optional. The EXPERIMENT= field should be set if this one is, although clients must be robust against either field not being set. The value should be in RFC3986 format[5], and should be "http:" or "https:" URLs. Only one URL shall be listed in the setting.

Examples, corresponding to the examples above in EXPERIMENT=: "EXPERIMENT_URL="https://fedoraproject.org/wiki/Changes/SwitchToDnf5"", "EXPERIMENT_URL="https://github.com/AsahiLinux/docs/wiki/M3-Series-Feature-Support"", "EXPERIMENT_URL="https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1441"".

Added in version 257.

### Distribution-level defaults and metadata
DEFAULT_HOSTNAME=

A string specifying the hostname if hostname(5) is not present and no other configuration source specifies the hostname. Must be either a single DNS label (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the format allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names). See org.freedesktop.hostname1(5) for a description of how systemd-hostnamed.service(8) determines the fallback hostname.

Added in version 248.

ARCHITECTURE=

A string that specifies which CPU architecture the userspace binaries require. The architecture identifiers are the same as for ConditionArchitecture= described in systemd.unit(5). The field is optional and should only be used when just single architecture is supported. It may provide redundant information when used in a GPT partition with a GUID type that already encodes the architecture. If this is not the case, the architecture should be specified in e.g., an extension image, to prevent an incompatible host from loading it. Added in version 252.

SYSEXT_LEVEL=

A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which extension images are supported. See /usr/lib/extension-release.d/extension-release.IMAGE, initrd[2] and systemd-sysext(8)) for more information. Examples: "SYSEXT_LEVEL=2", "SYSEXT_LEVEL=15.14".

Added in version 248.

CONFEXT_LEVEL=

Semantically the same as SYSEXT_LEVEL= but for confext images. See /etc/extension-release.d/extension-release.IMAGE for more information. Examples: "CONFEXT_LEVEL=2", "CONFEXT_LEVEL=15.14".

Added in version 254.

SYSEXT_SCOPE=

Takes a space-separated list of one or more of the strings "system", "initrd" and "portable". This field is only supported in extension-release.d/ files and indicates what environments the system extension is applicable to: i.e. to regular systems, to initrds and exitrds, or to portable service images. If not specified, "SYSEXT_SCOPE=system portable" is implied, i.e. any system extension without this field is applicable to regular systems and to portable service environments, but not to initrd/exitrd environments. Added in version 250.

CONFEXT_SCOPE=

Semantically the same as SYSEXT_SCOPE= but for confext images. Added in version 254.

PORTABLE_PREFIXES=

Takes a space-separated list of one or more valid prefix match strings for the Portable Services[3] logic. This field serves two purposes: it is informational, identifying portable service images as such (and thus allowing them to be distinguished from other OS images, such as bootable system images). It is also used when a portable service image is attached: the specified or implied portable service prefix is checked against the list specified here, to enforce restrictions how images may be attached to a system. Added in version 250.

### Notes
If you are using this file to determine the OS or a specific version of it, use the ID and VERSION_ID fields, possibly with ID_LIKE as fallback for ID. When looking for an OS identification string for presentation to the user use the PRETTY_NAME field.

Note that operating system vendors may choose not to provide version information, for example to accommodate for rolling releases. In this case, VERSION and VERSION_ID may be unset. Applications should not rely on these fields to be set.

Operating system vendors may extend the file format and introduce new fields. It is highly recommended to prefix new fields with an OS-specific name in order to avoid name clashes. Applications reading this file must ignore unknown fields.

Example: "DEBIAN_BTS="debbugs://bugs.debian.org/"".

Container and sandbox runtime managers may make the host's identification data available to applications by providing the host's /etc/os-release (if available, otherwise /usr/lib/os-release as a fallback) as /run/host/os-release.

## EXAMPLES
Example 1. os-release file for Fedora Workstation

```
NAME=Fedora
VERSION="32 (Workstation Edition)"
ID=fedora
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/"
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
```

Example 2. extension-release file for an extension for Fedora Workstation 32

```
ID=fedora
VERSION_ID=32
```

Example 3. Reading os-release in sh(1)

```
#!/bin/sh -eu
# SPDX-License-Identifier: MIT-0
test -e /etc/os-release && os_release='/etc/os-release' || os_release='/usr/lib/os-release'
. "${os_release}"
echo "Running on ${PRETTY_NAME:-Linux}"
if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]; then

    echo "Looks like Debian!"
fi
```

Example 4. Reading os-release in python(1) (versions >= 3.10)

```
#!/usr/bin/python
# SPDX-License-Identifier: MIT-0
import platform
os_release = platform.freedesktop_os_release()
pretty_name = os_release.get('PRETTY_NAME', 'Linux')
print(f'Running on {pretty_name!r}')
if 'fedora' in [os_release.get('ID', 'linux'),

                *os_release.get('ID_LIKE', '').split()]:

    print('Looks like Fedora!')
```

See docs for platform.freedesktop_os_release[7] for more details.

Example 5. Reading os-release in python(1) (any version)

```
#!/usr/bin/python
# SPDX-License-Identifier: MIT-0
import ast
import re
import sys
def read_os_release():

    try:

        filename = '/etc/os-release'

        f = open(filename)

    except FileNotFoundError:

        filename = '/usr/lib/os-release'

        f = open(filename)

    for line_number, line in enumerate(f, start=1):

        line = line.rstrip()

        if not line or line.startswith('#'):

            continue

        m = re.match(r'([A-Z][A-Z_0-9]+)=(.*)', line)

        if m:

            name, val = m.groups()

            if val and val[0] in '"\'':

                val = ast.literal_eval(val)

            yield name, val

        else:

            print(f'{filename}:{line_number}: bad line {line!r}',

                  file=sys.stderr)
os_release = dict(read_os_release())
pretty_name = os_release.get('PRETTY_NAME', 'Linux')
print(f'Running on {pretty_name!r}')
if 'debian' in [os_release.get('ID', 'linux'),

                *os_release.get('ID_LIKE', '').split()]:

    print('Looks like Debian!')
```

Note that the above version that uses the built-in implementation is preferred in most cases, and the open-coded version here is provided for reference.

## SEE ALSO
systemd(1), lsb_release(1), hostname(5), machine-id(5), machine-info(5)

## NOTES
1.

Announcement of /etc/os-release

https://0pointer.de/blog/projects/os-release

2.

initrd

https://docs.kernel.org/admin-guide/initrd.html

3.

Portable Services

https://systemd.io/PORTABLE_SERVICES

4.

Common Platform Enumeration Specification

http://scap.nist.gov/specifications/cpe/

5.

RFC3986 format

https://tools.ietf.org/html/rfc3986

6.

freedesktop.org Icon Theme Specification

https://standards.freedesktop.org/icon-theme-spec/latest

7.

platform.freedesktop_os_release

https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release


pstore.conf

title: pstore.conf(5)

summary: PStore configuration file

text:
# pstore.conf(5)

## NAME
pstore.conf, pstore.conf.d - PStore configuration file

## SYNOPSIS
/etc/systemd/pstore.conf

/run/systemd/pstore.conf

/usr/local/lib/systemd/pstore.conf

/usr/lib/systemd/pstore.conf

/etc/systemd/pstore.conf.d/*.conf

/run/systemd/pstore.conf.d/*.conf

/usr/local/lib/systemd/pstore.conf.d/*.conf

/usr/lib/systemd/pstore.conf.d/*.conf

## DESCRIPTION
This file configures the behavior of systemd-pstore(8), a tool for archiving the contents of the persistent storage filesystem, pstore[1].

## CONFIGURATION DIRECTORIES AND PRECEDENCE
The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [2], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

In addition to the main configuration file, drop-in configuration snippets are read from /usr/lib/systemd/*.conf.d/, /usr/local/lib/systemd/*.conf.d/, and /etc/systemd/*.conf.d/. Those drop-ins have higher precedence and override the main configuration file. Files in the *.conf.d/ configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files.

When packages need to customize the configuration, they can install drop-ins under /usr/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in /usr/ and the range 60-90 for drop-ins in /etc/ and /run/, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor.

To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file.

## OPTIONS
All options are configured in the [PStore] section:

Storage=

Controls where to archive (i.e. copy) files from the pstore filesystem. One of "none", "external", and "journal". When "none", the tool exits without processing files in the pstore filesystem. When "external" (the default), files are archived into /var/lib/systemd/pstore/, and logged into the journal. When "journal", pstore file contents are logged only in the journal. Added in version 243.

Unlink=

Controls whether or not files are removed from pstore after processing. Takes a boolean value. When true, a pstore file is removed from the pstore once it has been archived (either to disk or into the journal). When false, processing of pstore files occurs normally, but the files remain in the pstore. The default is true in order to maintain the pstore in a nearly empty state, so that the pstore has storage available for the next kernel error event. Added in version 243.

The defaults for all values are listed as comments in the template /etc/systemd/pstore.conf file that is installed by default.

## SEE ALSO
systemd-pstore.service(8)

## NOTES
1.

pstore

https://docs.kernel.org/admin-guide/abi-testing.html#abi-sys-fs-pstore

2.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.


repart.d

title: repart.d(5)

summary: Partition Definition Files for Automatic Boot\-Time Repartitioning

text:
# repart.d(5)

## NAME
repart.d - Partition Definition Files for Automatic Boot-Time Repartitioning

## SYNOPSIS
/etc/repart.d/*.conf

/run/repart.d/*.conf

/usr/local/lib/repart.d/*.conf

/usr/lib/repart.d/*.conf

## DESCRIPTION
repart.d/*.conf files describe basic properties of partitions of block devices of the local system. They may be used to declare types, names and sizes of partitions that shall exist. The systemd-repart(8) service reads these files and attempts to add new partitions currently missing and enlarge existing partitions according to these definitions. Operation is generally incremental, i.e. when applied, what exists already is left intact, and partitions are never shrunk, moved or deleted.

These definition files are useful for implementing operating system images that are prepared and delivered with minimally sized images (for example lacking any state or swap partitions), and which on first boot automatically take possession of any remaining disk space following a few basic rules.

Currently, support for partition definition files is only implemented for GPT partition tables.

Partition files are generally matched against any partitions already existing on disk in a simple algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then compared in order against existing partitions matching the same partition type UUID. Specifically, the first existing partition with a specific partition type UUID is assigned the first definition file with the same partition type UUID, and the second existing partition with a specific type UUID the second partition file with the same type UUID, and so on. Any left-over partition files that have no matching existing partition are assumed to define new partition that shall be created. Such partitions are appended to the end of the partition table, in the order defined by their names utilizing the first partition slot greater than the highest slot number currently in use. Any existing partitions that have no matching partition file are left as they are.

Note that these definitions may only be used to create and initialize new partitions or to grow existing ones. In the latter case, it will not grow the contained files systems however; separate mechanisms, such as systemd-growfs(8) may be used to grow the file systems inside of these partitions. Partitions may also be marked for automatic growing via the GrowFileSystem= setting, in which case the file system is grown on first mount by tools that respect this flag. See below for details.

## [PARTITION] SECTION OPTIONS
Type=

The GPT partition type UUID to match. This may be a GPT partition type UUID such as 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, or an identifier. The supported identifiers are:

Table 1. GPT partition type identifiers

Identifier

Explanation

esp

EFI System Partition

xbootldr

Extended Boot Loader Partition

swap

Swap partition

home

Home (/home/) partition

srv

Server data (/srv/) partition

var

Variable data (/var/) partition

tmp

Temporary data (/var/tmp/) partition

linux-generic

Generic Linux file system partition

root

Root file system partition type appropriate for the local architecture (an alias for an architecture root file system partition type listed below, e.g. root-x86-64)

root-verity

Verity data for the root file system partition for the local architecture

root-verity-sig

Verity signature data for the root file system partition for the local architecture

root-secondary

Root file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture)

root-secondary-verity

Verity data for the root file system partition of the secondary architecture

root-secondary-verity-sig

Verity signature data for the root file system partition of the secondary architecture

root-{arch}

Root file system partition of the given architecture (such as root-x86-64 or root-riscv64)

root-{arch}-verity

Verity data for the root file system partition of the given architecture

root-{arch}-verity-sig

Verity signature data for the root file system partition of the given architecture

usr

/usr/ file system partition type appropriate for the local architecture (an alias for an architecture /usr/ file system partition type listed below, e.g. usr-x86-64)

usr-verity

Verity data for the /usr/ file system partition for the local architecture

usr-verity-sig

Verity signature data for the /usr/ file system partition for the local architecture

usr-secondary

/usr/ file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture)

usr-secondary-verity

Verity data for the /usr/ file system partition of the secondary architecture

usr-secondary-verity-sig

Verity signature data for the /usr/ file system partition of the secondary architecture

usr-{arch}

/usr/ file system partition of the given architecture

usr-{arch}-verity

Verity data for the /usr/ file system partition of the given architecture

usr-{arch}-verity-sig

Verity signature data for the /usr/ file system partition of the given architecture

Architecture specific partition types can use one of these architecture identifiers:

alpha, arc, arm (32-bit), arm64 (64-bit, aka aarch64), ia64, loongarch64, mips-le, mips64-le, parisc, ppc, ppc64, ppc64-le, riscv32, riscv64, s390, s390x, tilegx, x86 (32-bit, aka i386) and x86-64 (64-bit, aka amd64).

Most of the partition type UUIDs listed above are defined in the Discoverable Partitions Specification[1].

Added in version 245.

Label=

The textual label to assign to the partition if none is assigned yet. Note that this setting is not used for matching. It is also not used when a label is already set for an existing partition. It is thus only used when a partition is newly created or when an existing one had a no label set (that is: an empty label). If not specified, a label derived from the partition type is automatically used. Simple specifier expansion is supported, see below. Added in version 245.

UUID=

The UUID to assign to the partition if none is assigned yet. Note that this setting is not used for matching. It is also not used when a UUID is already set for an existing partition. It is thus only used when a partition is newly created or when an existing one had a all-zero UUID set. If set to "null", the UUID is set to all zeroes. If not specified a UUID derived from the partition type is automatically used. Added in version 246.

Priority=

A numeric priority to assign to this partition, in the range -2147483648...2147483647, with smaller values indicating higher priority, and higher values indicating smaller priority. This priority is used in case the configured size constraints on the defined partitions do not permit fitting all partitions onto the available disk space. If the partitions do not fit, the highest numeric partition priority of all defined partitions is determined, and all defined partitions with this priority are removed from the list of new partitions to create (which may be multiple, if the same priority is used for multiple partitions). The fitting algorithm is then tried again. If the partitions still do not fit, the now highest numeric partition priority is determined, and the matching partitions removed too, and so on. Partitions of a priority of 0 or lower are never removed. If all partitions with a priority above 0 are removed and the partitions still do not fit on the device the operation fails. Note that this priority has no effect on ordering partitions, for that use the alphabetical order of the filenames of the partition definition files. Defaults to 0. Added in version 245.

Weight=

A numeric weight to assign to this partition in the range 0...1000000. Available disk space is assigned the defined partitions according to their relative weights (subject to the size constraints configured with SizeMinBytes=, SizeMaxBytes=), so that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with weight 333 a third of that. Defaults to 1000. The Weight= setting is used to distribute available disk space in an "elastic" fashion, based on the disk size and existing partitions. If a partition shall have a fixed size use both SizeMinBytes= and SizeMaxBytes= with the same value in order to fixate the size to one value, in which case the weight has no effect.

Added in version 245.

PaddingWeight=

Similar to Weight=, but sets a weight for the free space after the partition (the "padding"). When distributing available space the weights of all partitions and all defined padding is summed, and then each partition and padding gets the fraction defined by its weight. Defaults to 0, i.e. by default no padding is applied. Padding is useful if empty space shall be left for later additions or a safety margin at the end of the device or between partitions.

Added in version 245.

SizeMinBytes=, SizeMaxBytes=

Specifies minimum and maximum size constraints in bytes. Takes the usual K, M, G, T, ... suffixes (to the base of 1024). If SizeMinBytes= is specified the partition is created at or grown to at least the specified size. If SizeMaxBytes= is specified the partition is created at or grown to at most the specified size. The precise size is determined through the weight value configured with Weight=, see above. When SizeMinBytes= is set equal to SizeMaxBytes= the configured weight has no effect as the partition is explicitly sized to the specified fixed value. Note that partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the previous size of the partition (in case the partition already exists) is also enforced as lower bound for the new size. The values should be specified as multiples of 4096 bytes, and are rounded upwards (in case of SizeMinBytes=) or downwards (in case of SizeMaxBytes=) otherwise. If the backing device does not provide enough space to fulfill the constraints placing the partition will fail. For partitions that shall be created, depending on the setting of Priority= (see above) the partition might be dropped and the placing algorithm restarted. By default, a minimum size constraint of 10M and no maximum size constraint is set. Added in version 245.

PaddingMinBytes=, PaddingMaxBytes=

Specifies minimum and maximum size constraints in bytes for the free space after the partition (the "padding"). Semantics are similar to SizeMinBytes= and SizeMaxBytes=, except that unlike partition sizes free space can be shrunk and can be as small as zero. By default, no size constraints on padding are set, so that only PaddingWeight= determines the size of the padding applied. Added in version 245.

CopyBlocks=

Takes a path to a regular file, block device node, char device node or directory, or the special value "auto". If specified and the partition is newly created, the data from the specified path is written to the newly created partition, on the block level. If a directory is specified, the backing block device of the file system the directory is on is determined, and the data read directly from that. This option is useful to efficiently replicate existing file systems onto new partitions on the block level — for example to build a simple OS installer or an OS image builder. Specify /dev/urandom as value to initialize a partition with random data. If the special value "auto" is specified, the source to copy from is automatically picked up from the running system (or the image specified with --image= — if used). A partition that matches both the configured partition type (as declared with Type= described above), and the currently mounted directory appropriate for that partition type is determined. For example, if the partition type is set to "root" the partition backing the root directory (/) is used as source to copy from — if its partition type is set to "root" as well. If the declared type is "usr" the partition backing /usr/ is used as source to copy blocks from — if its partition type is set to "usr" too. The logic is capable of automatically tracking down the backing partitions for encrypted and Verity-enabled volumes. "CopyBlocks=auto" is useful for implementing "self-replicating" systems, i.e. systems that are their own installer.

The file specified here must have a size that is a multiple of the basic block size 512 and not be empty. If this option is used, the size allocation algorithm is slightly altered: the partition is created at least as big as required to fit the data in, i.e. the data size is an additional minimum size value taken into consideration for the allocation algorithm, similar to and in addition to the SizeMin= value configured above.

This option has no effect if the partition it is declared for already exists, i.e. existing data is never overwritten. Note that the data is copied in before the partition table is updated, i.e. before the partition actually is persistently created. This provides robustness: it is guaranteed that the partition either does not exist or exists fully populated; it is not possible that the partition exists but is not or only partially populated.

This option cannot be combined with Format= or CopyFiles=.

Added in version 246.

Format=

Takes a file system name, such as "ext4", "btrfs", "xfs", "vfat", "erofs", "squashfs" or the special value "swap". If specified and the partition is newly created it is formatted with the specified file system (or as swap device). The file system UUID and label are automatically derived from the partition UUID and label. If this option is used, the size allocation algorithm is slightly altered: the partition is created at least as big as required for the minimal file system of the specified type (or 4KiB if the minimal size is not known). This option has no effect if the partition already exists.

Similarly to the behaviour of CopyBlocks=, the file system is formatted before the partition is created, ensuring that the partition only ever exists with a fully initialized file system.

This option cannot be combined with CopyBlocks=.

Added in version 247.

CopyFiles=

Takes a pair of colon separated absolute file system paths. The first path refers to a source file or directory on the host, the second path refers to a target in the file system of the newly created partition and formatted file system. This setting may be used to copy files or directories from the host into the file system that is created due to the Format= option. If CopyFiles= is used without Format= specified explicitly, "Format=" with a suitable default is implied (currently "vfat" for "ESP" and "XBOOTLDR" partitions, and "ext4" otherwise, but this may change in the future). This option may be used multiple times to copy multiple files or directories from host into the newly formatted file system. The colon and second path may be omitted in which case the source path is also used as the target path (relative to the root of the newly created file system). If the source path refers to a directory it is copied recursively. This option has no effect if the partition already exists: it cannot be used to copy additional files into an existing partition, it may only be used to populate a file system created anew.

The copy operation is executed before the file system is registered in the partition table, thus ensuring that a file system populated this way only ever exists fully initialized.

Note that CopyFiles= will skip copying files that are not supported by the target filesystem (e.g symlinks, fifos, sockets and devices on vfat). When an unsupported file type is encountered, systemd-repart will skip copying this file and write a log message about it.

Note that systemd-repart does not change the UIDs/GIDs of any copied files and directories. When running systemd-repart as an unprivileged user to build an image of files and directories owned by the same user, you can run systemd-repart in a user namespace with the current user mapped to the root user to make sure the files and directories in the image are owned by the root user.

Note that when populating XFS filesystems with systemd-repart and loop devices are not available, populating XFS filesystems with files containing spaces, tabs or newlines might fail on old versions of mkfs.xfs(8) due to limitations of its protofile format.

Note that when populating XFS filesystems with systemd-repart and loop devices are not available, extended attributes will not be copied into generated XFS filesystems due to limitations mkfs.xfs(8)'s protofile format.

This option cannot be combined with CopyBlocks=.

When systemd-repart(8) is invoked with the --copy-source= command line switch the file paths are taken relative to the specified directory. If --copy-source= is not used, but the --image= or --root= switches are used, the source paths are taken relative to the specified root directory or disk image root.

Added in version 247.

ExcludeFiles=, ExcludeFilesTarget=

Takes one or more absolute paths, separated by whitespace, each referring to a source file or directory on the host. This setting may be used to exclude files or directories from the host from being copied into the file system when CopyFiles= is used. This option may be used multiple times to exclude multiple files or directories from host from being copied into the newly formatted file system. If the path is a directory and ends with "/", only the directory's contents are excluded but not the directory itself. If the path is a directory and does not end with "/", both the directory and its contents are excluded.

ExcludeFilesTarget= is like ExcludeFiles= except that instead of excluding the path on the host from being copied into the partition, it excludes any files and directories from being copied into the given path in the partition.

When systemd-repart(8) is invoked with the --image= or --root= command line switches the paths specified are taken relative to the specified root directory or disk image root.

Added in version 254.

MakeDirectories=

Takes one or more absolute paths, separated by whitespace, each declaring a directory to create within the new file system. Behaviour is similar to CopyFiles=, but instead of copying in a set of files this just creates the specified directories with the default mode of 0755 owned by the root user and group, plus all their parent directories (with the same ownership and access mode). To configure directories with different ownership or access mode, use CopyFiles= and specify a source tree to copy containing appropriately owned/configured directories. This option may be used more than once to create multiple directories. When CopyFiles= and MakeDirectories= are used together the former is applied first. If a directory listed already exists no operation is executed (in particular, the ownership/access mode of the directories is left as is). The primary use case for this option is to create a minimal set of directories that may be mounted over by other partitions contained in the same disk image. For example, a disk image where the root file system is formatted at first boot might want to automatically pre-create /usr/ in it this way, so that the "usr" partition may over-mount it.

Consider using systemd-tmpfiles(8) with its --image= option to pre-create other, more complex directory hierarchies (as well as other inodes) with fine-grained control of ownership, access modes and other file attributes.

Added in version 249.

MakeSymlinks=

Takes one or more arguments, separated by whitespace, each declaring a symlink to create within the new file system. Each argument is a pair of symlink source and target paths, separated by a colon. This option may be used more than once to create multiple symlinks. When CopyFiles= and MakeSymlinks= are used together the former is applied first. The primary use case for this option is to create symlinks that need to exist before systemd-tmpfiles(8) is executed. For example, when using systemd-confext(8), this setting can be used to create symlinks in /var/lib/extensions.mutable to redirect writes to mutable confexts to a custom location.

Consider using systemd-tmpfiles(8) with its --image= option to pre-create other symlinks (as well as other inodes) with fine-grained control of ownership, access modes and other file attributes.

Added in version 257.

Subvolumes=

Takes one or more absolute paths, separated by whitespace, each declaring a directory that should be a subvolume within the new file system. Each path may optionally be followed by a colon and a list of comma-separated subvolume flags. The following flags are understood: Table 2. Subvolume Flags

Flag

Purpose

"ro"

Make this subvolume read-only.

Note that this option does not create the directories themselves, that can be configured with

MakeDirectories= and CopyFiles=.

Note that this option only takes effect if the target filesystem supports subvolumes, such as btrfs(8).

Note that this option is only supported in combination with --offline=yes since btrfs-progs 6.12 or newer.

Added in version 255.

DefaultSubvolume=

Takes an absolute path specifying the default subvolume within the new filesystem. Note that this setting does not create the subvolume itself, that can be configured with Subvolumes=. Note that this option only takes effect if the target filesystem supports subvolumes, such as btrfs(8).

Note that this option is only supported in combination with --offline=yes since btrfs-progs 6.12 or newer.

Added in version 256.

Encrypt=

Takes one of "off", "key-file", "tpm2" and "key-file+tpm2" (alternatively, also accepts a boolean value, which is mapped to "off" when false, and "key-file" when true). Defaults to "off". If not "off" the partition will be formatted with a LUKS2 superblock, before the blocks configured with CopyBlocks= are copied in or the file system configured with Format= is created. The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If "key-file" or "key-file+tpm2" is used, a key is added to the LUKS2 superblock, configurable with the --key-file= option to systemd-repart. If "tpm2" or "key-file+tpm2" is used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured with the --tpm2-device= and --tpm2-pcrs= options to systemd-repart.

When used this slightly alters the size allocation logic as the implicit, minimal size limits of Format= and CopyBlocks= are increased by the space necessary for the LUKS2 superblock (see above).

This option has no effect if the partition already exists.

Added in version 247.

Verity=

Takes one of "off", "data", "hash" or "signature". Defaults to "off". If set to "off" or "data", the partition is populated with content as specified by CopyBlocks= or CopyFiles=. If set to "hash", the partition will be populated with verity hashes from the matching verity data partition. If set to "signature", the partition will be populated with a JSON object containing a signature of the verity root hash of the matching verity hash partition. A matching verity partition is a partition with the same verity match key (as configured with VerityMatchKey=).

If not explicitly configured, the data partition's UUID will be set to the first 128 bits of the verity root hash. Similarly, if not configured, the hash partition's UUID will be set to the final 128 bits of the verity root hash. The verity root hash itself will be included in the output of systemd-repart.

This option has no effect if the partition already exists.

Usage of this option in combination with Encrypt= is not supported.

For each unique VerityMatchKey= value, a single verity data partition ("Verity=data") and a single verity hash partition ("Verity=hash") must be defined.

Added in version 252.

VerityMatchKey=

Takes a short, user-chosen identifier string. This setting is used to find sibling verity partitions for the current verity partition. See the description for Verity=. Added in version 252.

VerityDataBlockSizeBytes=

Configures the data block size of the generated verity hash partition. Must be between 512 and 4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if systemd-repart is not operating on a block device. Added in version 255.

VerityHashBlockSizeBytes=

Configures the hash block size of the generated verity hash partition. Must be between 512 and 4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if systemd-repart is not operating on a block device. Added in version 255.

FactoryReset=

Takes a boolean argument. If specified the partition is marked for removal during a factory reset operation. This functionality is useful to implement schemes where images can be reset into their original state by removing partitions and creating them anew. Defaults to off. Added in version 245.

Flags=

Configures the 64-bit GPT partition flags field to set for the partition when creating it. This option has no effect if the partition already exists. If not specified, the flags value is set to all zeroes, except for the three bits that can also be configured via NoAuto=, ReadOnly= and GrowFileSystem=; see below for details on the defaults for these three flags. Specify the flags value in hexadecimal (by prefixing it with "0x"), binary (prefix "0b") or decimal (no prefix). Added in version 249.

NoAuto=, ReadOnly=, GrowFileSystem=

Configures the No-Auto, Read-Only and Grow-File-System partition flags (bit 63, 60 and 59) of the partition table entry, as defined by the Discoverable Partitions Specification[1]. Only available for partition types supported by the specification. This option is a friendly way to set bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set via Flags= too, see above. If Flags= is used in conjunction with one or more of NoAuto=/ReadOnly=/GrowFileSystem= the latter control the value of the relevant flags, i.e. the high-level settings NoAuto=/ReadOnly=/GrowFileSystem= override the relevant bits of the low-level setting Flags=.

Note that the three flags affect only automatic partition mounting, as implemented by systemd-gpt-auto-generator(8) or the --image= option of various commands (such as systemd-nspawn(1)). It has no effect on explicit mounts, such as those done via mount(8) or fstab(5).

If both bit 60 and 59 are set for a partition (i.e. the partition is marked both read-only and marked for file system growing) the latter is typically without effect: the read-only flag takes precedence in most tools reading these flags, and since growing the file system involves writing to the partition it is consequently ignored.

NoAuto= defaults to off. ReadOnly= defaults to on for Verity partition types, and off for all others. GrowFileSystem= defaults to on for all partition types that support it, except if the partition is marked read-only (and thus effectively, defaults to off for Verity partitions).

Added in version 249.

SplitName=

Configures the suffix to append to split artifacts when the --split option of systemd-repart(8) is used. Simple specifier expansion is supported, see below. Defaults to "%t". To disable split artifact generation for a partition, set SplitName= to "-". Added in version 252.

Minimize=

Takes one of "off", "best", and "guess" (alternatively, also accepts a boolean value, which is mapped to "off" when false, and "best" when true). Defaults to "off". If set to "best", the partition will have the minimal size required to store the sources configured with CopyFiles=. "best" is currently only supported for read-only filesystems. If set to "guess", the partition is created at least as big as required to store the sources configured with CopyFiles=. Note that unless the filesystem is a read-only filesystem, systemd-repart will have to populate the filesystem twice to guess the minimal required size, so enabling this option might slow down repart when populating large partitions. Added in version 253.

MountPoint=

Specifies where and how the partition should be mounted. Takes at least one and at most two fields separated with a colon (":"). The first field specifies where the partition should be mounted. The second field specifies extra mount options to append to the default mount options. These fields correspond to the second and fourth column of the fstab(5) format. This setting may be specified multiple times to mount the partition multiple times. This can be used to add mounts for different btrfs(8) subvolumes located on the same btrfs partition. Note that this setting is only taken into account when --generate-fstab= is specified on the systemd-repart command line.

Added in version 256.

EncryptedVolume=

Specifies how the encrypted partition should be set up. Takes at least one and at most three fields separated with a colon (":"). The first field specifies the encrypted volume name under /dev/mapper/. If not specified, "luks-UUID" will be used where "UUID" is the LUKS UUID. The second field specifies the keyfile to use following the same format as specified in crypttab. The third field specifies a comma-delimited list of crypttab options. These fields correspond to the first, third and fourth column of the crypttab(5) format. Note that this setting is only taken into account when --generate-crypttab= is specified on the systemd-repart command line.

Added in version 256.

Compression=

Specifies the compression algorithm to use for the filesystem configured with Format=. Takes a single argument specifying the compression algorithm. Note that this setting is only taken into account when the filesystem configured with Format= supports compression ( btrfs(8), squashfs, erofs(5)). Here's an incomplete list of compression algorithms supported by the filesystems known to systemd-repart:

Table 3. File System Compression Algorithms

File System

Compression Algorithms

Documentation

squashfs

gzip, lzo, lz4, xz, zstd, lzma

mksquashfs(1)

erofs

lz4, lz4hc, lzma, deflate, libdeflate, zstd

mkfs.erofs(1)

Added in version 257.

CompressionLevel=

Specifies the compression level to use for the filesystem configured with Format=. Takes a single argument specifying the compression level to use for the configured compression algorithm. The possible compression levels and their meaning are filesystem specific (refer to the filesystem's documentation for the exact meaning of a particular compression level). Note that this setting is only taken into account when the filesystem configured with Format= supports compression and the Compression= setting is configured explicitly.

Added in version 257.

SupplementFor=

Takes a partition definition name, such as "10-esp". If specified, systemd-repart will avoid creating this partition and instead prefer to partially merge the two definitions. However, depending on the existing layout of partitions on disk, systemd-repart may be forced to fall back onto un-merging the definitions and using them as originally written, potentially creating this partition. Specifically, systemd-repart will fall back if this partition is found to already exist on disk, or if the target partition already exists on disk but is too small, or if it cannot allocate space for the merged partition for some other reason. The following fields are merged into the target definition in the specified ways: Weight= and PaddingWeight= are simply overwritten; SizeMinBytes= and PaddingMinBytes= use the larger of the two values; SizeMaxBytes= and PaddingMaxBytes= use the smaller value; and CopyFiles=, ExcludeFiles=, ExcludeFilesTarget=, MakeDirectories=, and Subvolumes= are concatenated.

Usage of this option in combination with CopyBlocks=, Encrypt=, or Verity= is not supported. The target definition cannot set these settings either. A definition cannot simultaneously be a supplement and act as a target for some other supplement definition. A target cannot have more than one supplement partition associated with it.

For example, distributions can use this to implement $BOOT as defined in the Boot Loader Specification[2]. Distributions may prefer to use the ESP as $BOOT whenever possible, but to adhere to the spec XBOOTLDR must sometimes be used instead. So, they should create two definitions: the first defining an ESP big enough to hold just the bootloader, and a second for the XBOOTLDR that's sufficiently large to hold kernels and configured as a supplement for the ESP. Whenever possible, systemd-repart(8) will try to merge the two definitions to create one large ESP, but if that's not allowable due to the existing conditions on disk a small ESP and a large XBOOTLDR will be created instead.

As another example, distributions can also use this to seamlessly share a single /home partition in a multi-boot scenario, while preferring to keep /home on the root partition by default. Having a /home partition separated from the root partition entails some extra complexity: someone has to decide how to split the space between the two partitions. On the other hand, it allows a user to share their home area between multiple installed OSs (i.e. via systemd-homed.service(8)). Distributions should create two definitions: the first for a root partition that takes up some relatively small percentage of the disk, and the second as a supplement for the first to create a /home partition that takes up all the remaining free space. On first boot, if systemd-repart finds an existing /home partition on disk, it'll un-merge the definitions and create just a small root partition. Otherwise, the definitions will be merged and a single large root partition will be created.

Added in version 257.

## SPECIFIERS
Specifiers may be used in the Label=, CopyBlocks=, CopyFiles=, MakeDirectories=, SplitName= settings. The following expansions are understood:

Table 4. Specifiers available

Specifier

Meaning

Details

"%a"

Architecture

A short string identifying the architecture of the local system. A string such as x86, x86-64 or arm64. See the architectures defined for ConditionArchitecture= in systemd.unit(5) for a full list.

"%A"

Operating system image version

The operating system image version identifier of the running system, as read from the IMAGE_VERSION= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information.

"%b"

Boot ID

The boot ID of the running system, formatted as string. See random(4) for more information.

"%B"

Operating system build ID

The operating system build identifier of the running system, as read from the BUILD_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information.

"%H"

Host name

The hostname of the running system.

"%l"

Short host name

The hostname of the running system, truncated at the first dot to remove any domain component.

"%m"

Machine ID

The machine ID of the running system, formatted as string. See machine-id(5) for more information.

"%M"

Operating system image identifier

The operating system image identifier of the running system, as read from the IMAGE_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information.

"%o"

Operating system ID

The operating system identifier of the running system, as read from the ID= field of /etc/os-release. See os-release(5) for more information.

"%q"

Pretty host name

The pretty hostname of the running system, as read from the PRETTY_HOSTNAME= field of /etc/machine-info. If not set, resolves to the short hostname. See machine-info(5) for more information.

"%v"

Kernel release

Identical to uname -r output.

"%w"

Operating system version ID

The operating system version identifier of the running system, as read from the VERSION_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information.

"%W"

Operating system variant ID

The operating system variant identifier of the running system, as read from the VARIANT_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information.

"%T"

Directory for temporary files

This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Note that the directory may be specified without a trailing slash.)

"%V"

Directory for larger and persistent temporary files

This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Note that the directory may be specified without a trailing slash.)

"%%"

Single percent sign

Use "%%" in place of "%" to specify a single percent sign.

Additionally, for the

SplitName= setting, the following specifiers are also understood:

Table 5. Specifiers available

Specifier

Meaning

Details

"%T"

Partition Type UUID

The partition type UUID, as configured with Type=

"%t"

Partition Type Identifier

The partition type identifier corresponding to the partition type UUID

"%U"

Partition UUID

The partition UUID, as configured with UUID=

"%n"

Partition Number

The partition number assigned to the partition

## ENVIRONMENT
Extra filesystem formatting options can be provided using filesystem-specific environment variables:

$SYSTEMD_REPART_MKFS_OPTIONS_BTRFS, $SYSTEMD_REPART_MKFS_OPTIONS_XFS, $SYSTEMD_REPART_MKFS_OPTIONS_VFAT, $SYSTEMD_REPART_MKFS_OPTIONS_EROFS, and $SYSTEMD_REPART_MKFS_OPTIONS_SQUASHFS. Each variable accepts valid mkfs.filesystem command-line arguments. The content of those variables is passed as-is to the command, without any verification.

## EXAMPLES
Example 1. Grow the root partition to the full disk size at first boot

With the following file the root partition is automatically grown to the full disk if possible during boot.

```
# /usr/lib/repart.d/50-root.conf
[Partition]
Type=root
```

Example 2. Create a swap and home partition automatically on boot, if missing

The home partition gets all available disk space while the swap partition gets 1G at most and 64M at least. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not enough space is available. For every three bytes assigned to the home partition the swap partition gets assigned one.

```
# /usr/lib/repart.d/60-home.conf
[Partition]
Type=home
```

```
# /usr/lib/repart.d/70-swap.conf
[Partition]
Type=swap
SizeMinBytes=64M
SizeMaxBytes=1G
Priority=1
Weight=333
```

Example 3. Create B partitions in an A/B Verity setup, if missing

Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions (and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize image sizes the original image is shipped only with one root and one Verity partition (the "A" set), and the second root and Verity partitions (the "B" set) shall be created on first boot on the free space on the medium.

```
# /usr/lib/repart.d/50-root.conf
[Partition]
Type=root
SizeMinBytes=512M
SizeMaxBytes=512M
```

```
# /usr/lib/repart.d/60-root-verity.conf
[Partition]
Type=root-verity
SizeMinBytes=64M
SizeMaxBytes=64M
```

The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of partitions, since after all they shall have the same properties and sizes as the "A" set.

```
# ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf
# ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf
```

Example 4. Create a data partition and corresponding verity partitions from a OS tree

Assuming we have an OS tree at /var/tmp/os-tree that we want to package in a root partition together with matching verity partitions, we can do so as follows:

```
# 50-root.conf
[Partition]
Type=root
CopyFiles=/var/tmp/os-tree
Verity=data
VerityMatchKey=root
Minimize=guess
```

```
# 60-root-verity.conf
[Partition]
Type=root-verity
Verity=hash
VerityMatchKey=root
# Explicitly set the hash and data block size to 4K
VerityDataBlockSizeBytes=4096
VerityHashBlockSizeBytes=4096
Minimize=best
```

```
# 70-root-verity-sig.conf
[Partition]
Type=root-verity-sig
Verity=signature
VerityMatchKey=root
```

## SEE ALSO
systemd(1), systemd-repart(8), sfdisk(8), systemd-cryptenroll(1)

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification

2.

Boot Loader Specification

https://uapi-group.org/specifications/specs/boot_loader_specification/


sysctl.d

title: sysctl.d(5)

summary: Configure kernel parameters at boot

text:
# sysctl.d(5)

## NAME
sysctl.d - Configure kernel parameters at boot

## SYNOPSIS
/etc/sysctl.d/*.conf

/run/sysctl.d/*.conf

/usr/local/lib/sysctl.d/*.conf

/usr/lib/sysctl.d/*.conf

```
key.name.under.proc.sys = some value
key/name/under/proc/sys = some value
key/middle.part.with.dots/foo = 123
key.middle/part/with/dots.foo = 123
-key.that.will.not.fail = value
key.pattern.*.with.glob = whatever
-key.pattern.excluded.with.glob
key.pattern.overridden.with.glob = custom
```

## DESCRIPTION
At boot, systemd-sysctl.service(8) reads configuration files from the above directories to configure sysctl(8) kernel parameters.

## CONFIGURATION FORMAT
The configuration files contain a list of variable assignments, separated by newlines. Empty lines and lines whose first non-whitespace character is "#" or ";" are ignored.

Note that either "/" or "." may be used as separators within sysctl variable names. If the first separator is a slash, remaining slashes and dots are left intact. If the first separator is a dot, dots and slashes are interchanged. "kernel.domainname=foo" and "kernel/domainname=foo" are equivalent and will cause "foo" to be written to /proc/sys/kernel/domainname. Either "net.ipv4.conf.enp3s0/200.forwarding" or "net/ipv4/conf/enp3s0.200/forwarding" may be used to refer to /proc/sys/net/ipv4/conf/enp3s0.200/forwarding. A glob glob(7) pattern may be used to write the same value to all matching keys. Keys for which an explicit pattern exists will be excluded from any glob matching. In addition, a key may be explicitly excluded from being set by any matching glob patterns by specifying the key name prefixed with a "-" character and not followed by "=", see SYNOPSIS.

Any access permission errors and attempts to write variables not present on the local system are logged at debug level and do not cause the service to fail. Other types of errors when setting variables are logged with higher priority and cause the service to return failure at the end (after processing other variables). As an exception, if a variable assignment is prefixed with a single "-" character, failure to set the variable for any reason will be logged at debug level and will not cause the service to fail.

The settings configured with sysctl.d files will be applied early on boot. The network interface-specific options will also be applied individually for each network interface as it shows up in the system. (More specifically, net.ipv4.conf.*, net.ipv6.conf.*, net.ipv4.neigh.* and net.ipv6.neigh.*).

Many sysctl parameters only become available when certain kernel modules are loaded. Modules are usually loaded on demand, e.g. when certain hardware is plugged in or network brought up. This means that systemd-sysctl.service(8) which runs during early boot will not configure such parameters if they become available after it has run. To set such parameters, it is recommended to add an udev(7) rule to set those parameters when they become available. Alternatively, a slightly simpler and less efficient option is to add the module to modules-load.d(5), causing it to be loaded statically before sysctl settings are applied (see example below).

## CONFIGURATION DIRECTORIES AND PRECEDENCE
Configuration files are read from directories in /etc/, /run/, /usr/local/lib/, and /usr/lib/, in order of precedence, as listed in the SYNOPSIS section above. Files must have the ".conf" extension. Files in /etc/ override files with the same name in /run/, /usr/local/lib/, and /usr/lib/. Files in /run/ override files with the same name under /usr/.

All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later).

Packages should install their configuration files in /usr/lib/ (distribution packages) or /usr/local/lib/ (local installs) [1]. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages.

It is recommended to prefix all filenames with a two-digit number and a dash to simplify the ordering. It is recommended to use the range 10-40 for configuration files in /usr/ and the range 60-90 for configuration files in /etc/ and /run/, to make sure that local and transient configuration files will always take priority over configuration files shipped by the OS vendor.

If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file. If the vendor configuration file is included in the initrd image, the image has to be regenerated.

## EXAMPLES
Example 1. Set kernel YP domain name

/etc/sysctl.d/domain-name.conf:

```
kernel.domainname=example.com
```

Example 2. Apply settings available only when a certain module is loaded (method one)

/etc/udev/rules.d/99-bridge.rules:

```
ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \

      RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge"
```

/etc/sysctl.d/bridge.conf:

```
net.bridge.bridge-nf-call-ip6tables = 0
net.bridge.bridge-nf-call-iptables = 0
net.bridge.bridge-nf-call-arptables = 0
```

This method applies settings when the module is loaded. Please note that, unless the br_netfilter module is loaded, bridged packets will not be filtered by Netfilter (starting with kernel 3.18), so simply not loading the module is sufficient to avoid filtering.

Example 3. Apply settings available only when a certain module is loaded (method two)

/etc/modules-load.d/bridge.conf:

```
br_netfilter
```

/etc/sysctl.d/bridge.conf:

```
net.bridge.bridge-nf-call-ip6tables = 0
net.bridge.bridge-nf-call-iptables = 0
net.bridge.bridge-nf-call-arptables = 0
```

This method forces the module to be always loaded. Please note that, unless the br_netfilter module is loaded, bridged packets will not be filtered with Netfilter (starting with kernel 3.18), so simply not loading the module is sufficient to avoid filtering.

Example 4. Set network routing properties for all interfaces

/etc/sysctl.d/20-rp_filter.conf:

```
net.ipv4.conf.default.rp_filter = 2
net.ipv4.conf.*.rp_filter = 2
-net.ipv4.conf.all.rp_filter
net.ipv4.conf.hub0.rp_filter = 1
```

The rp_filter key will be set to "2" for all interfaces, except "hub0". We set net.ipv4.conf.default.rp_filter first, so any interfaces which are added later will get this value (this also covers any interfaces detected while we're running). The glob matches any interfaces which were detected earlier. The glob will also match net.ipv4.conf.all.rp_filter, which we do not want to set at all, so it is explicitly excluded. And "hub0" is excluded from the glob because it has an explicit setting.

## SEE ALSO
systemd(1), systemd-sysctl.service(8), systemd-delta(1), sysctl(8), sysctl.conf(5), modprobe(8)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.


systemd-sleep.conf

title: systemd-sleep.conf(5)

text:
# systemd-sleep.conf(5)

## NAME
systemd-sleep.conf, sleep.conf.d - Suspend and hibernation configuration file

## SYNOPSIS
/etc/systemd/sleep.conf

/run/systemd/sleep.conf

/usr/lib/systemd/sleep.conf

/etc/systemd/sleep.conf.d/*.conf

/run/systemd/sleep.conf.d/*.conf

/usr/lib/systemd/sleep.conf.d/*.conf

## DESCRIPTION
systemd supports four general power-saving modes:

suspend

a low-power state where execution of the OS is paused, and complete power loss might result in lost data, and which is fast to enter and exit. This corresponds to suspend, standby, or freeze states as understood by the kernel. Added in version 203.

hibernate

a low-power state where execution of the OS is paused, and complete power loss does not result in lost data, and which might be slow to enter and exit. This corresponds to the hibernation as understood by the kernel. Added in version 203.

hybrid-sleep

a low-power state where execution of the OS is paused, which might be slow to enter, and on complete power loss does not result in lost data but might be slower to exit in that case. This mode is called suspend-to-both by the kernel. Added in version 203.

suspend-then-hibernate

A low power state where the system is initially suspended (the state is stored in RAM). When the battery level is too low (less than 5%) or a certain timespan has passed, whichever happens first, the system is automatically woken up and then hibernated. This establishes a balance between speed and safety. If the system has no battery, it would be hibernated after HibernateDelaySec= has passed. If not set, then defaults to "2h".

If the system has battery and HibernateDelaySec= is not set, low-battery alarms (ACPI _BTP) are tried first for detecting battery percentage and wake up the system for hibernation. If not available, or HibernateDelaySec= is set, the system would regularly wake up to check the time and detect the battery percentage/discharging rate. The rate is used to schedule the next detection. If that is also not available, SuspendEstimationSec= is used as last resort.

Added in version 239.

Settings in these files determine what strings will be written to /sys/power/disk and /sys/power/state by systemd-sleep(8) when systemd(1) attempts to suspend or hibernate the machine. See systemd.syntax(7) for a general description of the syntax.

## CONFIGURATION DIRECTORIES AND PRECEDENCE
The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [1], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

In addition to the main configuration file, drop-in configuration snippets are read from /usr/lib/systemd/*.conf.d/, /usr/local/lib/systemd/*.conf.d/, and /etc/systemd/*.conf.d/. Those drop-ins have higher precedence and override the main configuration file. Files in the *.conf.d/ configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files.

When packages need to customize the configuration, they can install drop-ins under /usr/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in /usr/ and the range 60-90 for drop-ins in /etc/ and /run/, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor.

To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file.

## OPTIONS
The following options can be configured in the [Sleep] section of /etc/systemd/sleep.conf or a sleep.conf.d file:

AllowSuspend=, AllowHibernation=, AllowHybridSleep=, AllowSuspendThenHibernate=

By default, any power-saving mode is advertised if possible (i.e. the kernel supports that mode, the necessary resources are available). Those switches can be used to disable specific modes. If AllowHibernation=no or AllowSuspend=no is used, this implies AllowSuspendThenHibernate=no and AllowHybridSleep=no, since those methods use both suspend and hibernation internally. AllowSuspendThenHibernate=yes and AllowHybridSleep=yes can be used to override and enable those specific modes.

Added in version 240.

SuspendState=

The string to be written to /sys/power/state by systemd-suspend.service(8). More than one value can be specified by separating multiple values with whitespace. They will be tried in turn, until one is written without error. If none of the writes succeed, the operation will be aborted. The allowed set of values is determined by the kernel and is shown in the file itself (use cat /sys/power/state to display). See Basic sysfs Interfaces for System Suspend and Hibernation[2] for more details.

systemd-suspend-then-hibernate.service(8) uses this value when suspending.

Added in version 203.

HibernateMode=

The string to be written to /sys/power/disk by systemd-hibernate.service(8). More than one value can be specified by separating multiple values with whitespace. They will be tried in turn, until one is written without error. If none of the writes succeed, the operation will be aborted. The allowed set of values is determined by the kernel and is shown in the file itself (use cat /sys/power/disk to display). See the kernel documentation page Basic sysfs Interfaces for System Suspend and Hibernation[2] for more details.

systemd-suspend-then-hibernate.service(8) uses the value of HibernateMode= when hibernating.

Added in version 203.

MemorySleepMode=

The string to be written to /sys/power/mem_sleep when SuspendState=mem or hybrid-sleep is used. More than one value can be specified by separating multiple values with whitespace. They will be tried in turn, until one is written without error. If none of the writes succeed, the operation will be aborted. Defaults to empty, i.e. the kernel default or kernel command line option mem_sleep_default= is respected. The allowed set of values is determined by the kernel and is shown in the file itself (use cat /sys/power/mem_sleep to display). See the kernel documentation page Basic sysfs Interfaces for System Suspend and Hibernation[2] for more details.

Added in version 256.

HibernateDelaySec=

The amount of time the system spends in suspend mode before the system is automatically put into hibernate mode. Only used by systemd-suspend-then-hibernate.service(8). Refer to suspend-then-hibernate for details on how this option interacts with other options/system battery state. Added in version 239.

HibernateOnACPower=

Whether to allow hibernation when the system has AC power. Only used by systemd-suspend-then-hibernate.service(8) when HibernateDelaySec= is set. If this option is disabled, the countdown of HibernateDelaySec= starts only after AC power is disconnected, keeping the system in the suspend state otherwise.

This option is only effective on systems with a battery.

Added in version 257.

SuspendEstimationSec=

The RTC alarm will wake the system after the specified timespan to measure the system battery capacity level and estimate battery discharging rate. Only used by systemd-suspend-then-hibernate.service(8). Refer to suspend-then-hibernate for details on how this option interacts with other options/system battery state. Added in version 253.

## EXAMPLE: FREEZE
Example: to exploit the “freeze” mode added in Linux 3.9, one can use systemctl suspend with

```
[Sleep]
SuspendState=freeze
```

## SEE ALSO
systemd-sleep(8), systemd-suspend.service(8), systemd-hibernate.service(8), systemd-hybrid-sleep.service(8), systemd-suspend-then-hibernate.service(8), systemd(1), systemd.directives(7)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.

2.

Basic sysfs Interfaces for System Suspend and Hibernation

https://docs.kernel.org/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation