journald.conf

title: journald.conf(5)

summary: Journal service configuration files

text:
# journald.conf(5)

## NAME
journald.conf, journald.conf.d, journald@.conf - Journal service configuration files

## SYNOPSIS
/etc/systemd/journald.conf

/run/systemd/journald.conf

/usr/local/lib/systemd/journald.conf

/usr/lib/systemd/journald.conf

/etc/systemd/journald.conf.d/*.conf

/run/systemd/journald.conf.d/*.conf

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

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

/etc/systemd/journald@NAMESPACE.conf

/etc/systemd/journald@NAMESPACE.conf.d/*.conf

/run/systemd/journald@NAMESPACE.conf.d/*.conf

/usr/local/lib/systemd/journald@NAMESPACE.conf.d/*.conf

/usr/lib/systemd/journald@NAMESPACE.conf.d/*.conf

## DESCRIPTION
These files configure various parameters of the systemd journal service, systemd-journald.service(8). See systemd.syntax(7) for a general description of the syntax.

The systemd-journald instance managing the default namespace is configured by /etc/systemd/journald.conf and associated drop-ins. Instances managing other namespaces read /etc/systemd/journald@NAMESPACE.conf and associated drop-ins with the namespace identifier filled in. This allows each namespace to carry a distinct configuration. See systemd-journald.service(8) for details about journal namespaces.

## 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
All options are configured in the [Journal] section:

Storage=

Controls where to store journal data. One of "volatile", "persistent", "auto" and "none". If "volatile", journal log data will be stored only in memory, i.e. below the /run/log/journal hierarchy (which is created if needed). If "persistent", data will be stored preferably on disk, i.e. below the /var/log/journal hierarchy (which is created if needed), with a fallback to /run/log/journal (which is created if needed), during early boot and if the disk is not writable. "auto" behaves like "persistent" if the /var/log/journal directory exists, and "volatile" otherwise (the existence of the directory controls the storage mode). "none" turns off all storage, all log data received will be dropped (but forwarding to other targets, such as the console, the kernel log buffer, or a syslog socket will still work). Defaults to "auto" in the default journal namespace, and "persistent" in all others. Note that journald will initially use volatile storage, until a call to journalctl --flush (or sending SIGUSR1 to journald) will cause it to switch to persistent logging (under the conditions mentioned above). This is done automatically on boot via "systemd-journal-flush.service".

Note that when this option is changed to "volatile", existing persistent data is not removed. In the other direction, journalctl(1) with the --flush option may be used to move volatile data to persistent storage.

When journal namespacing (see LogNamespace= in systemd.exec(5)) is used, setting Storage= to "volatile" or "auto" will not have an effect on the creation of the per-namespace logs directory in /var/log/journal/, as the systemd-journald@.service service file by default carries LogsDirectory=. To turn that off, add a unit file drop-in file that sets LogsDirectory= to an empty string.

Note that per-user journal files are not supported unless persistent storage is enabled, thus making journalctl --user unavailable.

The storage to use can also be specified via the "journal.storage" credential. Values configured via configuration files take priority over values configured via the credential.

Added in version 186.

Compress=

Can take a boolean value. If enabled (the default), data objects that shall be stored in the journal and are larger than the default threshold of 512 bytes are compressed before they are written to the file system. It can also be set to a number of bytes to specify the compression threshold directly. Suffixes like K, M, and G can be used to specify larger units.

Seal=

Takes a boolean value. If enabled (the default), and a sealing key is available (as created by journalctl(1)'s --setup-keys command), Forward Secure Sealing (FSS) for all persistent journal files is enabled. FSS is based on Seekable Sequential Key Generators[2] by G. A. Marson and B. Poettering (doi:10.1007/978-3-642-40203-6_7) and may be used to protect journal files from unnoticed alteration. Added in version 189.

SplitMode=

Controls whether to split up journal files per user, either "uid" or "none". Split journal files are primarily useful for access control: on UNIX/Linux access control is managed per file, and the journal daemon will assign users read access to their journal files. If "uid", all regular users (with UID outside the range of system users, dynamic service users, and the nobody user) will each get their own journal files, and system users will log to the system journal. See Users, Groups, UIDs and GIDs on systemd systems[3] for more details about UID ranges. If "none", journal files are not split up by user and all messages are instead stored in the single system journal. In this mode unprivileged users generally do not have access to their own log data. Note that splitting up journal files by user is only available for journals stored persistently. If journals are stored on volatile storage (see Storage= above), only a single journal file is used. Defaults to "uid". Added in version 190.

RateLimitIntervalSec=, RateLimitBurst=

Configures the rate limiting that is applied to all messages generated on the system. If, in the time interval defined by RateLimitIntervalSec=, more messages than specified in RateLimitBurst= are logged by a service, all further messages within the interval are dropped until the interval is over. A message about the number of dropped messages is generated. This rate limiting is applied per-service, so that two services which log do not interfere with each other's limits. Defaults to 10000 messages in 30s. The time specification for RateLimitIntervalSec= may be specified in the following units: "s", "min", "h", "ms", "us". To turn off any kind of rate limiting, set either value to 0. Note that the effective rate limit is multiplied by a factor derived from the available free disk space for the journal. Currently, this factor is calculated using the base 2 logarithm.

Table 1. Example RateLimitBurst= rate modifications by the available disk space

Available Disk Space

Burst Multiplier

<= 1MB

1

<= 16MB

2

<= 256MB

3

<= 4GB

4

<= 64GB

5

<= 1TB

6

If a service provides rate limits for itself through

LogRateLimitIntervalSec= and/or LogRateLimitBurst= in systemd.exec(5), those values will override the settings specified here.

SystemMaxUse=, SystemKeepFree=, SystemMaxFileSize=, SystemMaxFiles=, RuntimeMaxUse=, RuntimeKeepFree=, RuntimeMaxFileSize=, RuntimeMaxFiles=

Enforce size limits on the journal files stored. The options prefixed with "System" apply to the journal files when stored on a persistent file system, more specifically /var/log/journal. The options prefixed with "Runtime" apply to the journal files when stored on a volatile in-memory file system, more specifically /run/log/journal. The former is used only when /var/ is mounted, writable, and the directory /var/log/journal exists. Otherwise, only the latter applies. Note that this means that during early boot and if the administrator disabled persistent logging, only the latter options apply, while the former apply if persistent logging is enabled and the system is fully booted up. journalctl and systemd-journald ignore all files with names not ending with ".journal" or ".journal~", so only such files, located in the appropriate directories, are taken into account when calculating current disk usage. SystemMaxUse= and RuntimeMaxUse= control how much disk space the journal may use up at most. SystemKeepFree= and RuntimeKeepFree= control how much disk space systemd-journald shall leave free for other uses. systemd-journald will respect both limits and use the smaller of the two values.

The first pair defaults to 10% and the second to 15% of the size of the respective file system, but each of the calculated default values is capped to 4G. If the file system is nearly full and either SystemKeepFree= or RuntimeKeepFree= are violated when systemd-journald is started, the limit will be raised to the percentage that is actually free. This means that if there was enough free space before and journal files were created, and subsequently something else causes the file system to fill up, journald will stop using more space, but it will not be removing existing files to reduce the footprint again, either. Also note that only archived files are deleted to reduce the space occupied by journal files. This means that, in effect, there might still be more space used than SystemMaxUse= or RuntimeMaxUse= limit after a vacuuming operation is complete.

SystemMaxFileSize= and RuntimeMaxFileSize= control how large individual journal files may grow at most. This influences the granularity in which disk space is made available through rotation, i.e. deletion of historic data. Defaults to one eighth of the values configured with SystemMaxUse= and RuntimeMaxUse= capped to 128M, so that usually seven rotated journal files are kept as history. If the journal compact mode is enabled (enabled by default), the maximum file size is capped to 4G.

Specify values in bytes or use K, M, G, T, P, E as units for the specified sizes (equal to 1024, 1024², ... bytes). Note that size limits are enforced synchronously when journal files are extended, and no explicit rotation step triggered by time is needed.

SystemMaxFiles= and RuntimeMaxFiles= control how many individual journal files to keep at most. Note that only archived files are deleted to reduce the number of files until this limit is reached; active files will stay around. This means that, in effect, there might still be more journal files around in total than this limit after a vacuuming operation is complete. This setting defaults to 100.

MaxFileSec=

The maximum time to store entries in a single journal file before rotating to the next one. Normally, time-based rotation should not be required as size-based rotation with options such as SystemMaxFileSize= should be sufficient to ensure that journal files do not grow without bounds. However, to ensure that not too much data is lost at once when old journal files are deleted, it might make sense to change this value from the default of one month. Set to 0 to turn off this feature. This setting takes time values which may be suffixed with the units "year", "month", "week", "day", "h" or "m" to override the default time unit of seconds. Added in version 195.

MaxRetentionSec=

The maximum time to store journal entries. This controls whether journal files containing entries older than the specified time span are deleted. Normally, time-based deletion of old journal files should not be required as size-based deletion with options such as SystemMaxUse= should be sufficient to ensure that journal files do not grow without bounds. However, to enforce data retention policies, it might make sense to change this value from the default of 0 (which turns off this feature). This setting also takes time values which may be suffixed with the units "year", "month", "week", "day", "h" or " m" to override the default time unit of seconds. Added in version 195.

SyncIntervalSec=

The timeout before synchronizing journal files to disk. After syncing, journal files are placed in the OFFLINE state. Note that syncing is unconditionally done immediately after a log message of priority CRIT, ALERT or EMERG has been logged. This setting hence applies only to messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The default timeout is 5 minutes. Added in version 199.

ForwardToSyslog=, ForwardToKMsg=, ForwardToConsole=, ForwardToWall=, ForwardToSocket=

Control whether log messages received by the journal daemon shall be forwarded to a traditional syslog daemon, to the kernel log buffer (kmsg), to the system console, sent as wall messages to all logged-in users or sent over a socket. These options take boolean arguments except for "ForwardToSocket=" which takes an address instead. If forwarding to syslog is enabled but nothing reads messages from the socket, forwarding to syslog has no effect. By default, only forwarding to wall is enabled. These settings may be overridden at boot time with the kernel command line options "systemd.journald.forward_to_syslog", "systemd.journald.forward_to_kmsg", "systemd.journald.forward_to_console", and "systemd.journald.forward_to_wall". If the option name is specified without "=" and the following argument, true is assumed. Otherwise, the argument is parsed as a boolean. The socket forwarding address can be specified with the credential "journal.forward_to_socket". The following socket types are supported:

AF_INET (e.g. "192.168.0.11:4444"), AF_INET6 (e.g. "[2001:db8::ff00:42:8329]:4444"), AF_UNIX (e.g. "/run/host/journal/socket"), AF_VSOCK (e.g. "vsock:2:1234")

When forwarding to the console, the TTY to log to can be changed with TTYPath=, described below.

When forwarding to the kernel log buffer (kmsg), make sure to select a suitably large size for the log buffer, for example by adding "log_buf_len=8M" to the kernel command line. systemd will automatically disable kernel's rate-limiting applied to userspace processes (equivalent to setting "printk.devkmsg=on").

When forwarding over a socket the Journal Export Format[4] is used when sending over the wire. Notably this includes the metadata field __REALTIME_TIMESTAMP so that systemd-journal-remote (see systemd-journal-remote.service(8)) can be used to receive the forwarded journal entries.

Note: Forwarding is performed synchronously within journald, and may significantly affect its performance. This is particularly relevant when using ForwardToConsole=yes in cloud environments, where the console is often a slow, virtual serial port. Since journald is implemented as a conventional single-process daemon, forwarding to a completely hung console will block journald. This can have a cascading effect resulting in any services synchronously logging to the blocked journal also becoming blocked. Unless actively debugging/developing something, it is generally preferable to setup a journalctl --follow style service redirected to the console, instead of ForwardToConsole=yes, for production use.

Note: Using ForwardToSocket= over IPv4/IPv6 links can be very slow due to the synchronous nature of the sockets. Take care to ensure your link is a low-latency local link if possible. Typically IP networking is not available everywhere journald runs, e.g. in the initrd during boot. Consider using AF_VSOCK/AF_UNIX sockets for this if possible.

MaxLevelStore=, MaxLevelSyslog=, MaxLevelKMsg=, MaxLevelConsole=, MaxLevelWall=, MaxLevelSocket=

Controls the maximum log level of messages that are stored in the journal, forwarded to syslog, kmsg, the console, the wall, or a socket (if that is enabled, see above). As argument, takes one of "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug", or integer values in the range of 0–7 (corresponding to the same levels). Messages equal or below the log level specified are stored/forwarded, messages above are dropped. Defaults to "debug" for MaxLevelStore=, MaxLevelSyslog= and MaxLevelSocket=, to ensure that the all messages are stored in the journal, forwarded to syslog and the socket if one exists. Defaults to "notice" for MaxLevelKMsg=, "info" for MaxLevelConsole=, and "emerg" for MaxLevelWall=. These settings may be overridden at boot time with the kernel command line options "systemd.journald.max_level_store=", "systemd.journald.max_level_syslog=", "systemd.journald.max_level_kmsg=", "systemd.journald.max_level_console=", "systemd.journald.max_level_wall=", "systemd.journald.max_level_socket=". Added in version 185.

ReadKMsg=

Takes a boolean value. If enabled systemd-journal processes /dev/kmsg messages generated by the kernel. In the default journal namespace this option is enabled by default, it is disabled in all others. Added in version 235.

Audit=

Takes a boolean value or special value "keep". If enabled systemd-journald will turn on kernel auditing on start-up. If disabled it will turn it off. When "keep" it will neither enable nor disable it, leaving the previous state unchanged. This means if another tool turns on auditing even if systemd-journald left it off, it will still collect the generated messages. Defaults to yes in the default journal namespace, and "keep" otherwise. Note that this option does not control whether systemd-journald collects generated audit records, it just controls whether it tells the kernel to generate them. If you need to prevent systemd-journald from collecting the generated messages, the socket unit "systemd-journald-audit.socket" can be disabled and, in this case, this setting is without effect.

Added in version 246.

TTYPath=

Change the console TTY to use if ForwardToConsole=yes is used. Defaults to /dev/console. Added in version 185.

LineMax=

The maximum line length to permit when converting stream logs into record logs. When a systemd unit's standard output/error are connected to the journal via a stream socket, the data read is split into individual log records at newline ("\n", ASCII 10) and NUL characters. If no such delimiter is read for the specified number of bytes a hard log record boundary is artificially inserted, breaking up overly long lines into multiple log records. Selecting overly large values increases the possible memory usage of the Journal daemon for each stream client, as in the worst case the journal daemon needs to buffer the specified number of bytes in memory before it can flush a new log record to disk. Also note that permitting overly large line maximum line lengths affects compatibility with traditional log protocols as log records might not fit anymore into a single AF_UNIX or AF_INET datagram. Takes a size in bytes. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Defaults to 48K, which is relatively large but still small enough so that log records likely fit into network datagrams along with extra room for metadata. Note that values below 79 are not accepted and will be bumped to 79. Added in version 235.

## FORWARDING TO TRADITIONAL SYSLOG DAEMONS
Journal events can be transferred to a different logging daemon in two different ways. With the first method, messages are immediately forwarded to a socket (/run/systemd/journal/syslog), where the traditional syslog daemon can read them. This method is controlled by the ForwardToSyslog= option. With a second method, a syslog daemon behaves like a normal journal client, and reads messages from the journal files, similarly to journalctl(1). With this, messages do not have to be read immediately, which allows a logging daemon which is only started late in boot to access all messages since the start of the system. In addition, full structured meta-data is available to it. This method of course is available only if the messages are stored in a journal file at all. So it will not work if Storage=none is set. It should be noted that usually the second method is used by syslog daemons, so the Storage= option, and not the ForwardToSyslog= option, is relevant for them.

## SEE ALSO
systemd(1), systemd-journald.service(8), journalctl(1), systemd.journal-fields(7), systemd-system.conf(5)

## 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.

Seekable Sequential Key Generators

https://eprint.iacr.org/2013/397

3.

Users, Groups, UIDs and GIDs on systemd systems

https://systemd.io/UIDS-GIDS

4.

Journal Export Format

https://systemd.io/JOURNAL_EXPORT_FORMATS/#journal-export-format


locale.conf

package: systemd

title: locale.conf(5)

summary: Configuration file for locale settings

text:
# locale.conf(5)

## NAME
locale.conf - Configuration file for locale settings

## SYNOPSIS
/etc/locale.conf

## DESCRIPTION
The /etc/locale.conf file configures system-wide locale settings. It is read at early boot by systemd(1).

The format of locale.conf is a newline-separated list of environment-like shell-compatible variable assignments, ignoring comments and empty lines. It is possible to source the configuration from shell scripts, however, beyond mere variable assignments, no shell features are supported, allowing applications to read the file without implementing a shell compatible execution engine. See os-release(5) for a detailed description of the format.

Note that the kernel command line options locale.LANG=, locale.LANGUAGE=, locale.LC_CTYPE=, locale.LC_NUMERIC=, locale.LC_TIME=, locale.LC_COLLATE=, locale.LC_MONETARY=, locale.LC_MESSAGES=, locale.LC_PAPER=, locale.LC_NAME=, locale.LC_ADDRESS=, locale.LC_TELEPHONE=, locale.LC_MEASUREMENT=, locale.LC_IDENTIFICATION= may be used to override the locale settings at boot.

The locale settings configured in /etc/locale.conf are system-wide and are inherited by every service or user, unless overridden or unset by individual programs or users.

Depending on the operating system, other configuration files might be checked for locale configuration as well, however only as fallback.

/etc/locale.conf can be updated using systemd-localed.service(8). localectl(1) may be used to alter the settings in this file during runtime from the command line. Use systemd-firstboot(1) to customize them on mounted (but not booted) system images.

## OPTIONS
The following locale settings may be set using /etc/locale.conf: LANG=, LANGUAGE=, LC_CTYPE=, LC_NUMERIC=, LC_TIME=, LC_COLLATE=, LC_MONETARY=, LC_MESSAGES=, LC_PAPER=, LC_NAME=, LC_ADDRESS=, LC_TELEPHONE=, LC_MEASUREMENT=, LC_IDENTIFICATION=. Note that LC_ALL may not be configured in this file. For details about the meaning and semantics of these settings, refer to locale(7).

## EXAMPLE
Example 1. German locale with English messages

/etc/locale.conf:

```
# Custom settings
LANG=de_DE.UTF-8
LC_MESSAGES=en_US.UTF-8
```

## SEE ALSO
systemd(1), locale(7), localectl(1), systemd-localed.service(8), systemd-firstboot(1)

branch: sisyphus


localtime

title: localtime(5)

summary: Local timezone configuration file

text:
# localtime(5)

## NAME
localtime - Local timezone configuration file

## SYNOPSIS
/etc/localtime -> ../usr/share/zoneinfo/...

## DESCRIPTION
The /etc/localtime file configures the system-wide timezone of the local system that is used by applications for presentation to the user. It should be an absolute or relative symbolic link pointing to /usr/share/zoneinfo/, followed by a timezone identifier such as "Europe/Berlin" or "Etc/UTC". The resulting link should lead to the corresponding binary tzfile(5) timezone data for the configured timezone.

Because the timezone identifier is extracted from the symlink target name of /etc/localtime, this file may not be a normal file or hardlink.

If /etc/localtime is missing, the default "UTC" timezone is used.

The timezone may be overridden for individual programs by using the $TZ environment variable. See environ(7).

You may use timedatectl(1) to change the settings of this file from the command line during runtime. Use systemd-firstboot(1) to initialize the time zone on mounted (but not booted) system images.

## SEE ALSO
systemd(1), tzset(3), localtime(3), timedatectl(1), systemd-timedated.service(8), systemd-firstboot(1)


logind.conf

title: logind.conf(5)

summary: Login manager configuration files

text:
# logind.conf(5)

## NAME
logind.conf, logind.conf.d - Login manager configuration files

## SYNOPSIS
/etc/systemd/logind.conf

/run/systemd/logind.conf

/usr/local/lib/systemd/logind.conf

/usr/lib/systemd/logind.conf

/etc/systemd/logind.conf.d/*.conf

/run/systemd/logind.conf.d/*.conf

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

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

## DESCRIPTION
These files configure various parameters of the systemd login manager, systemd-logind.service(8). 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
All options are configured in the [Login] section:

NAutoVTs=

Takes a positive integer. Configures how many virtual terminals (VTs) to allocate by default that, when switched to and are previously unused, "autovt" services are automatically spawned on. These services are instantiated from the template unit autovt@.service for the respective VT TTY name, for example, autovt@tty4.service. By default, autovt@.service is linked to getty@.service. In other words, login prompts are started dynamically as the user switches to unused virtual terminals. Hence, this parameter controls how many login "gettys" are available on the VTs. If a VT is already used by some other subsystem (for example, a graphical login), this kind of activation will not be attempted. Note that the VT configured in ReserveVT= is always subject to this kind of activation, even if it is not one of the VTs configured with the NAutoVTs= directive. Defaults to 6. When set to 0, automatic spawning of "autovt" services is disabled.

ReserveVT=

Takes a positive integer. Identifies one virtual terminal that shall unconditionally be reserved for autovt@.service activation (see above). The VT selected with this option will be marked busy unconditionally, so that no other subsystem will allocate it. This functionality is useful to ensure that, regardless of how many VTs are allocated by other subsystems, one login "getty" is always available. Defaults to 6 (in other words, there will always be a "getty" available on Alt-F6.). When set to 0, VT reservation is disabled. Added in version 190.

KillUserProcesses=

Takes a boolean argument. Configures whether the processes of a user should be killed when the user logs out. If true, the scope unit corresponding to the session and all processes inside that scope will be terminated. If false, the scope is "abandoned", see systemd.scope(5), and processes are not killed. Defaults to "yes", but see the options KillOnlyUsers= and KillExcludeUsers= below. In addition to session processes, user process may run under the user manager unit user@.service. Depending on the linger settings, this may allow users to run processes independent of their login sessions. See the description of enable-linger in loginctl(1).

Note that setting KillUserProcesses=yes will break tools like screen(1) and tmux(1), unless they are moved out of the session scope. See example in systemd-run(1).

KillOnlyUsers=, KillExcludeUsers=

These settings take space-separated lists of usernames that override the KillUserProcesses= setting. A user name may be added to KillExcludeUsers= to exclude the processes in the session scopes of that user from being killed even if KillUserProcesses=yes is set. If KillExcludeUsers= is not set, the "root" user is excluded by default. KillExcludeUsers= may be set to an empty value to override this default. If a user is not excluded, KillOnlyUsers= is checked next. If this setting is specified, only the processes in the session scopes of those users will be killed. Otherwise, users are subject to the KillUserProcesses=yes setting.

IdleAction=

Configures the action to take when the system is idle. Takes one of "ignore", "poweroff", "reboot", "halt", "kexec", "suspend", "hibernate", "hybrid-sleep", "suspend-then-hibernate", "sleep", and "lock". Defaults to "ignore". Note that this requires that user sessions correctly report the idle status to the system. The system will execute the action after all sessions report that they are idle, no idle inhibitor lock is active, and subsequently, the time configured with IdleActionSec= (see below) has expired.

Added in version 198.

IdleActionSec=

Configures the delay after which the action configured in IdleAction= (see above) is taken after the system is idle. Added in version 198.

InhibitDelayMaxSec=

Specifies the maximum time a system shutdown or sleep request is delayed due to an inhibitor lock of type "delay" being active before the inhibitor is ignored and the operation executes anyway. Defaults to 5.

UserStopDelaySec=

Specifies how long to keep the user record and per-user service user@.service around for a user after they logged out fully. If set to zero, the per-user service is terminated immediately when the last session of the user has ended. If this option is configured to non-zero rapid logout/login cycles are sped up, as the user's service manager is not constantly restarted. If set to "infinity" the per-user service for a user is never terminated again after first login, and continues to run until system shutdown. Defaults to 10s. Added in version 240.

SleepOperation=

Takes a list of sleep operations. Possible values are "suspend", "hibernate", "hybrid-sleep", and "suspend-then-hibernate". Controls the candidate sleep operations for the "sleep" action. When "sleep" action is performed, the specified sleep operations are checked in a fixed order ("suspend-then-hibernate" → "hybrid-sleep" → "suspend" → "hibernate"), and the first one supported by the machine is used to put the system into sleep. Defaults to "suspend-then-hibernate suspend hibernate". Added in version 256.

HandlePowerKey=, HandlePowerKeyLongPress=, HandleRebootKey=, HandleRebootKeyLongPress=, HandleSuspendKey=, HandleSuspendKeyLongPress=, HandleHibernateKey=, HandleHibernateKeyLongPress=, HandleLidSwitch=, HandleLidSwitchExternalPower=, HandleLidSwitchDocked=, HandleSecureAttentionKey=

Controls how logind shall handle the system power, reboot and sleep keys and the lid switch to trigger actions such as system power-off, reboot or suspend. Can be one of "ignore", "poweroff", "reboot", "halt", "kexec", "suspend", "hibernate", "hybrid-sleep", "suspend-then-hibernate", "sleep", "lock", "factory-reset", and "secure-attention-key". If "ignore", systemd-logind will never handle these keys. If "lock", all running sessions will be screen-locked; otherwise, the specified action will be taken in the respective event. Only input devices with the "power-switch" udev tag will be watched for key/lid switch events. HandlePowerKey= defaults to "poweroff", HandleRebootKey= defaults to "reboot", HandleSuspendKey= defaults to "suspend", HandleHibernateKey= defaults to "hibernate", HandlePowerKeyLongPress= defaults to "ignore", HandleRebootKeyLongPress= defaults to "poweroff", HandleSuspendKeyLongPress= defaults to "hibernate", HandleHibernateKeyLongPress= defaults to "ignore". HandleLidSwitch= defaults to "suspend". HandleLidSwitchExternalPower= is completely ignored by default (for backwards compatibility) — an explicit value must be set before it will be used to determine behaviour. HandleLidSwitchDocked= defaults to "ignore". If the system is inserted in a docking station, or if more than one display is connected, the action specified by HandleLidSwitchDocked= occurs; if the system is on external power the action (if any) specified by HandleLidSwitchExternalPower= occurs; otherwise the HandleLidSwitch= action occurs. HandleSecureAttentionKey= defaults to "secure-attention-key"

A different application may disable logind's handling of system power and sleep keys and the lid switch by taking a low-level inhibitor lock ("handle-power-key", "handle-suspend-key", "handle-hibernate-key", "handle-lid-switch", "handle-reboot-key"). This is most commonly used by graphical desktop environments to take over suspend and hibernation handling, and to use their own configuration mechanisms. If a low-level inhibitor lock is taken, logind will not take any action when that key or switch is triggered and the Handle*= settings are irrelevant, except for HandleSecureAttentionKey=, which is always handled since its addition in v257.

Added in version 184.

PowerKeyIgnoreInhibited=, SuspendKeyIgnoreInhibited=, HibernateKeyIgnoreInhibited=, LidSwitchIgnoreInhibited=, RebootKeyIgnoreInhibited=

Controls whether actions that systemd-logind takes when the power, reboot and sleep keys and the lid switch are triggered are subject to high-level inhibitor locks ("shutdown", "reboot", "sleep", "idle"). Low level inhibitor locks ("handle-power-key", "handle-suspend-key", "handle-hibernate-key", "handle-lid-switch", "handle-reboot-key"), are always honored, irrespective of this setting. These settings take boolean arguments. If "no", the inhibitor locks taken by applications are respected. If "yes", "shutdown", "reboot" "sleep", and "idle" inhibitor locks are ignored. PowerKeyIgnoreInhibited=, SuspendKeyIgnoreInhibited=, HibernateKeyIgnoreInhibited= and RebootKeyIgnoreInhibited= default to "no". LidSwitchIgnoreInhibited= defaults to "yes". This means that when systemd-logind is handling events by itself (no low level inhibitor locks are taken by another application), the lid switch does not respect suspend blockers by default, but the power and sleep keys do.

Added in version 190.

HoldoffTimeoutSec=

Specifies a period of time after system startup or system resume in which systemd will hold off on reacting to lid events. This is required for the system to properly detect any hotplugged devices so systemd can ignore lid events if external monitors, or docks, are connected. If set to 0, systemd will always react immediately, possibly before the kernel fully probed all hotplugged devices. This is safe, as long as you do not care for systemd to account for devices that have been plugged or unplugged while the system was off. Defaults to 30s. Added in version 220.

RuntimeDirectorySize=

Sets the size limit on the $XDG_RUNTIME_DIR runtime directory for each user who logs in. Takes a size in bytes, optionally suffixed with the usual K, G, M, and T suffixes, to the base 1024 (IEC). Alternatively, a numerical percentage suffixed by "%" may be specified, which sets the size limit relative to the amount of physical RAM. Defaults to 10%. Note that this size is a safety limit only. As each runtime directory is a tmpfs file system, it will only consume as much memory as is needed. Added in version 211.

RuntimeDirectoryInodesMax=

Sets the limit on number of inodes for the $XDG_RUNTIME_DIR runtime directory for each user who logs in. Takes a number, optionally suffixed with the usual K, G, M, and T suffixes, to the base 1024 (IEC). Defaults to RuntimeDirectorySize= divided by 4096. Note that this size is a safety limit only. As each runtime directory is a tmpfs file system, it will only consume as much memory as is needed. Added in version 246.

InhibitorsMax=

Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 (8K). Added in version 230.

SessionsMax=

Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 (8K). Depending on how the pam_systemd.so module is included in the PAM stack configuration, further login sessions will either be refused, or permitted but not tracked by systemd-logind. Added in version 230.

RemoveIPC=

Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users are excluded from the effect of this setting. Defaults to "yes". Added in version 212.

StopIdleSessionSec=

Specifies a timeout in seconds, or a time span value after which systemd-logind checks the idle state of all sessions. Every session that is idle for longer than the timeout will be stopped. Note that this option does not apply to "greeter" or "lock-screen" sessions. Defaults to "infinity" (systemd-logind is not checking the idle state of sessions). For details about the syntax of time spans, see systemd.time(7). Added in version 252.

DesignatedMaintenanceTime=

Specifies a default calendar event for scheduled shutdowns. So when using e.g. the command shutdown -r to reboot the system without specifying a timeout, logind would use the configured calendar event instead. For details about the syntax of calendar events, see systemd.time(7). Added in version 257.

WallMessages=

Controls whether wall(1) messages should be sent to the terminals of all currently logged in users upon shutdown or reboot. Defaults to "yes", and can be changed at runtime via the DBus "EnableWallMessages" and "WallMessagePrefix" properties. Added in version 258.

## SEE ALSO
systemd(1), systemd-logind.service(8), loginctl(1), systemd-system.conf(5)

## 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.


modules-load.d

title: modules-load.d(5)

text:
# modules-load.d(5)

## NAME
modules-load.d - Configure kernel modules to load at boot

## SYNOPSIS
/etc/modules-load.d/*.conf

/run/modules-load.d/*.conf

/usr/local/lib/modules-load.d/*.conf

/usr/lib/modules-load.d/*.conf

## DESCRIPTION
systemd-modules-load.service(8) reads files from the above directories which contain kernel modules to load during boot in a static list. Each configuration file is named in the style of /etc/modules-load.d/program.conf. Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar triggers encoded in the kernel modules themselves instead of static configuration like this. In fact, most modern kernel modules are prepared for automatic loading already.

## CONFIGURATION FORMAT
The configuration files should simply contain a list of kernel module names to load, separated by newlines. Empty lines and lines whose first non-whitespace character is # or ; are ignored.

## 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.

## EXAMPLE
Example 1. /etc/modules-load.d/virtio-net.conf example:

```
# Load virtio-net.ko at boot
virtio-net
```

## SEE ALSO
systemd(1), systemd-modules-load.service(8), systemd-delta(1), 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.


oomd.conf

title: oomd.conf(5)

summary: Global systemd\-oomd configuration files

text:
# oomd.conf(5)

## NAME
oomd.conf, oomd.conf.d - Global systemd-oomd configuration files

## SYNOPSIS
/etc/systemd/oomd.conf

/run/systemd/oomd.conf

/usr/local/lib/systemd/oomd.conf

/usr/lib/systemd/oomd.conf

/etc/systemd/oomd.conf.d/*.conf

/run/systemd/oomd.conf.d/*.conf

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

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

## DESCRIPTION
These files configure the various parameters of the systemd(1) userspace out-of-memory (OOM) killer, systemd-oomd.service(8). 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.

## [OOM] SECTION OPTIONS
The following options are available in the [OOM] section:

SwapUsedLimit=

Sets the limit for memory and swap usage on the system before systemd-oomd will take action. If the fraction of memory used and the fraction of swap used on the system are both more than what is defined here, systemd-oomd will act on eligible descendant control groups with swap usage greater than 5% of total swap, starting from the ones with the highest swap usage. Which control groups are monitored and what action gets taken depends on what the unit has configured for ManagedOOMSwap=. Takes a value specified in percent (when suffixed with "%"), permille ("‰") or permyriad ("‱"), between 0% and 100%, inclusive. Defaults to 90%. Added in version 247.

DefaultMemoryPressureLimit=

Sets the limit for memory pressure on the unit's control group before systemd-oomd will take action. A unit can override this value with ManagedOOMMemoryPressureLimit=. The memory pressure for this property represents the fraction of time in a 10 second window in which all tasks in the control group were delayed. For each monitored control group, if the memory pressure on that control group exceeds the limit set for longer than the duration set by DefaultMemoryPressureDurationSec=, systemd-oomd will act on eligible descendant control groups, starting from the ones with the most reclaim activity to the least reclaim activity. Which control groups are monitored and what action gets taken depends on what the unit has configured for ManagedOOMMemoryPressure=. Takes a fraction specified in the same way as SwapUsedLimit= above. Defaults to 60%. Added in version 247.

DefaultMemoryPressureDurationSec=

Sets the amount of time a unit's control group needs to have exceeded memory pressure limits before systemd-oomd will take action. A unit can override this value with ManagedOOMMemoryPressureDurationSec=. Memory pressure limits are defined by DefaultMemoryPressureLimit= and ManagedOOMMemoryPressureLimit=. Must be set to 0, or at least 1 second. Defaults to 30 seconds when unset or 0. Added in version 248.

## SEE ALSO
systemd(1), systemd.resource-control(5), systemd-oomd.service(8), oomctl(1)

## 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.


title: org.freedesktop.LogControl1(5)

summary: D\-Bus interface to query and set logging configuration

text:
# org.freedesktop.LogControl1(5)

## NAME
org.freedesktop.LogControl1 - D-Bus interface to query and set logging configuration

## INTRODUCTION
org.freedesktop.LogControl1 is a generic interface that is intended to be used by any daemon which allows the log level and target to be set over D-Bus. It is implemented by various daemons that are part of the systemd(1) suite.

It is assumed that those settings are global for the whole program, so a fixed object path is used. The interface should always be available under the path /org/freedesktop/LogControl1.

## DESCRIPTION
The following interface is exposed:

```
node /org/freedesktop/LogControl1 {

  interface org.freedesktop.LogControl1 {

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      @org.freedesktop.systemd1.Privileged("true")

      readwrite s LogLevel = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      @org.freedesktop.systemd1.Privileged("true")

      readwrite s LogTarget = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s SyslogIdentifier = '...';

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Properties
LogLevel describes the syslog(3)-style log-level, and should be one of "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug", in order of increasing verbosity.

LogTarget describes the log target (mechanism). It should be one of "console" (log to the console or standard output), "kmsg" (log to the kernel ring buffer), "journal" (log to the journal natively, see systemd-journald.service(8)), "syslog" (log using the syslog(3) call).

Write Access

The LogLevel and LogTarget properties are supposed to be writable. Care should be taken to ensure that only appropriately privileged clients can modify them.

SyslogIdentifier is a read-only property that shows the "syslog identifier". It is a short string that identifies the program that is the source of log messages that is passed to the syslog(3) call.

## TOOLS
journalctl option -p/--priority= may be used to filter log messages by log level, option -t/--identifier= may be used to by the syslog identifier, and filters like "_TRANSPORT=syslog", "_TRANSPORT=journal", and "_TRANSPORT=kernel" may be used to filter messages by the mechanism through which they reached systemd-journald.

systemctl log-level and systemctl log-target verbs may be used to query and set the LogLevel and LogTarget properties of the service manager. systemctl service-log-level and systemctl service-log-target may similarly be used for individual services. (Services must have the BusName= property set and must implement the interface described here. See systemd.service(5) for details about BusName=.)

## EXAMPLE
Example 1. Create a simple listener on the bus that implements LogControl1

```
/* SPDX-License-Identifier: MIT-0 */
/* Implements the LogControl1 interface as per specification:

 * https://www.freedesktop.org/software/systemd/man/org.freedesktop.LogControl1.html

 *

 * Compile with 'cc logcontrol-example.c $(pkg-config --libs --cflags libsystemd)'

 *

 * To get and set properties via busctl:

 *

 * $ busctl --user get-property org.freedesktop.Example \

 *                              /org/freedesktop/LogControl1 \

 *                              org.freedesktop.LogControl1 \

 *                              SyslogIdentifier

 *   s "example"

 * $ busctl --user get-property org.freedesktop.Example \

 *                              /org/freedesktop/LogControl1 \

 *                              org.freedesktop.LogControl1 \

 *                              LogTarget

 *   s "journal"

 * $ busctl --user get-property org.freedesktop.Example \

 *                              /org/freedesktop/LogControl1 \

 *                              org.freedesktop.LogControl1 \

 *                              LogLevel

 *   s "info"

 * $ busctl --user set-property org.freedesktop.Example \

 *                              /org/freedesktop/LogControl1 \

 *                              org.freedesktop.LogControl1 \

 *                              LogLevel \

 *                              "s" debug

 * $ busctl --user get-property org.freedesktop.Example \

 *                              /org/freedesktop/LogControl1 \

 *                              org.freedesktop.LogControl1 \

 *                              LogLevel

 *   s "debug"

 */
#include <errno.h>
#include <stdlib.h>
#include <stdio.h>
#include <syslog.h>
#include <systemd/sd-bus.h>
#include <systemd/sd-journal.h>
#define _cleanup_(f) __attribute__((cleanup(f)))
static int log_error(int log_level, int error, const char *str) {

  sd_journal_print(log_level, "%s failed: %s", str, strerror(-error));

  return error;
}
typedef enum LogTarget {

  LOG_TARGET_JOURNAL,

  LOG_TARGET_KMSG,

  LOG_TARGET_SYSLOG,

  LOG_TARGET_CONSOLE,

  _LOG_TARGET_MAX,
} LogTarget;
static const char* const log_target_table[_LOG_TARGET_MAX] = {

  [LOG_TARGET_JOURNAL] = "journal",

  [LOG_TARGET_KMSG]    = "kmsg",

  [LOG_TARGET_SYSLOG]  = "syslog",

  [LOG_TARGET_CONSOLE] = "console",
};
static const char* const log_level_table[LOG_DEBUG + 1] = {

  [LOG_EMERG]   = "emerg",

  [LOG_ALERT]   = "alert",

  [LOG_CRIT]    = "crit",

  [LOG_ERR]     = "err",

  [LOG_WARNING] = "warning",

  [LOG_NOTICE]  = "notice",

  [LOG_INFO]    = "info",

  [LOG_DEBUG]   = "debug",
};
typedef struct object {

  const char *syslog_identifier;

  LogTarget log_target;

  int log_level;
} object;
static int property_get(

                sd_bus *bus,

                const char *path,

                const char *interface,

                const char *property,

                sd_bus_message *reply,

                void *userdata,

                sd_bus_error *error) {

  object *o = userdata;

  if (strcmp(property, "LogLevel") == 0)

    return sd_bus_message_append(reply, "s", log_level_table[o->log_level]);

  if (strcmp(property, "LogTarget") == 0)

    return sd_bus_message_append(reply, "s", log_target_table[o->log_target]);

  if (strcmp(property, "SyslogIdentifier") == 0)

    return sd_bus_message_append(reply, "s", o->syslog_identifier);

  return sd_bus_error_setf(error,

                           SD_BUS_ERROR_UNKNOWN_PROPERTY,

                           "Unknown property '%s'",

                           property);
}
static int property_set(

                sd_bus *bus,

                const char *path,

                const char *interface,

                const char *property,

                sd_bus_message *message,

                void *userdata,

                sd_bus_error *error) {

  object *o = userdata;

  const char *value;

  int r;

  r = sd_bus_message_read(message, "s", &value);

  if (r < 0)

    return r;

  if (strcmp(property, "LogLevel") == 0) {

    int i;

    for (i = 0; i < LOG_DEBUG + 1; i++)

      if (strcmp(value, log_level_table[i]) == 0) {

        o->log_level = i;

        setlogmask(LOG_UPTO(i));

        return 0;

      }

    return sd_bus_error_setf(error,

                             SD_BUS_ERROR_INVALID_ARGS,

                             "Invalid value for LogLevel: '%s'",

                             value);

  }

  if (strcmp(property, "LogTarget") == 0) {

    LogTarget i;

    for (i = 0; i < _LOG_TARGET_MAX; i++)

      if (strcmp(value, log_target_table[i]) == 0) {

        o->log_target = i;

        return 0;

      }

    return sd_bus_error_setf(error,

                             SD_BUS_ERROR_INVALID_ARGS,

                             "Invalid value for LogTarget: '%s'",

                             value);

  }

  return sd_bus_error_setf(error,

                           SD_BUS_ERROR_UNKNOWN_PROPERTY,

                           "Unknown property '%s'",

                           property);
}
/* https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html

 */
static const sd_bus_vtable vtable[] = {

  SD_BUS_VTABLE_START(0),

  SD_BUS_WRITABLE_PROPERTY(

    "LogLevel", "s",

    property_get, property_set,

    0,

    0),

  SD_BUS_WRITABLE_PROPERTY(

    "LogTarget", "s",

    property_get, property_set,

    0,

    0),

  SD_BUS_PROPERTY(

    "SyslogIdentifier", "s",

    property_get,

    0,

    SD_BUS_VTABLE_PROPERTY_CONST),

  SD_BUS_VTABLE_END
};
int main(int argc, char **argv) {

  /* The bus should be relinquished before the program terminates. The cleanup

   * attribute allows us to do it nicely and cleanly whenever we exit the

   * block.

   */

  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;

  object o = {

    .log_level = LOG_INFO,

    .log_target = LOG_TARGET_JOURNAL,

    .syslog_identifier = "example",

  };

  int r;

  /* https://man7.org/linux/man-pages/man3/setlogmask.3.html

   * Programs using syslog() instead of sd_journal can use this API to cut logs

   * emission at the source.

   */

  setlogmask(LOG_UPTO(o.log_level));

  /* Acquire a connection to the bus, letting the library work out the details.

   * https://www.freedesktop.org/software/systemd/man/sd_bus_default.html

   */

  r = sd_bus_default(&bus);

  if (r < 0)

    return log_error(o.log_level, r, "sd_bus_default()");

  /* Publish an interface on the bus, specifying our well-known object access

   * path and public interface name.

   * https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html

   * https://dbus.freedesktop.org/doc/dbus-tutorial.html

   */

  r = sd_bus_add_object_vtable(bus, NULL,

                               "/org/freedesktop/LogControl1",

                               "org.freedesktop.LogControl1",

                               vtable,

                               &o);

  if (r < 0)

    return log_error(o.log_level, r, "sd_bus_add_object_vtable()");

  /* By default, the service is assigned an ephemeral name. Also add a fixed

   * one, so that clients know whom to call.

   * https://www.freedesktop.org/software/systemd/man/sd_bus_request_name.html

   */

  r = sd_bus_request_name(bus, "org.freedesktop.Example", 0);

  if (r < 0)

    return log_error(o.log_level, r, "sd_bus_request_name()");

  for (;;) {

    /* https://www.freedesktop.org/software/systemd/man/sd_bus_wait.html

     */

    r = sd_bus_wait(bus, UINT64_MAX);

    if (r < 0)

      return log_error(o.log_level, r, "sd_bus_wait()");

    /* https://www.freedesktop.org/software/systemd/man/sd_bus_process.html

     */

    r = sd_bus_process(bus, NULL);

    if (r < 0)

      return log_error(o.log_level, r, "sd_bus_process()");

  }

  /* https://www.freedesktop.org/software/systemd/man/sd_bus_release_name.html

   */

  r = sd_bus_release_name(bus, "org.freedesktop.Example");

  if (r < 0)

    return log_error(o.log_level, r, "sd_bus_release_name()");

  return 0;
}
```

This creates a simple server on the bus. It implements the LogControl1 interface by providing the required properties and allowing to set the writable ones. It logs at the configured log level using sd_journal_print(3).

Note that when porting this example to other D-Bus libraries it might be necessary to add manual client privilege checks, as they typically do not default to the restrictive defaults of sd-bus, where unprivileged access to properties is controlled via the SD_BUS_VTABLE_UNPRIVILEGED flag that is opt-in rather than opt-out.

## SEE ALSO
systemd(1), journalctl(1), systemctl(1), systemd.service(5), syslog(3)


title: org.freedesktop.hostname1(5)

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

text:
# org.freedesktop.hostname1(5)

## NAME
org.freedesktop.hostname1 - The D-Bus interface of systemd-hostnamed

## INTRODUCTION
systemd-hostnamed.service(8) is a system service that can be used to control the hostname and related machine metadata from user programs. This page describes the hostname semantics and the D-Bus interface.

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

```
node /org/freedesktop/hostname1 {

  interface org.freedesktop.hostname1 {

    methods:

      SetHostname(in  s hostname,

                  in  b interactive);

      SetStaticHostname(in  s hostname,

                        in  b interactive);

      SetPrettyHostname(in  s hostname,

                        in  b interactive);

      SetIconName(in  s icon,

                  in  b interactive);

      SetChassis(in  s chassis,

                 in  b interactive);

      SetDeployment(in  s deployment,

                    in  b interactive);

      SetLocation(in  s location,

                  in  b interactive);

      GetProductUUID(in  b interactive,

                     out ay uuid);

      GetHardwareSerial(out s serial);

      Describe(out s json);

    properties:

      readonly s Hostname = '...';

      readonly s StaticHostname = '...';

      readonly s PrettyHostname = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s DefaultHostname = '...';

      readonly s HostnameSource = '...';

      readonly s IconName = '...';

      readonly s Chassis = '...';

      readonly s Deployment = '...';

      readonly s Location = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s KernelName = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s KernelRelease = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s KernelVersion = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s OperatingSystemPrettyName = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s OperatingSystemCPEName = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t OperatingSystemSupportEnd = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s HomeURL = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s OperatingSystemImageID = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s OperatingSystemImageVersion = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s HardwareVendor = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s HardwareModel = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s HardwareSKU = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s HardwareVersion = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s FirmwareVersion = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s FirmwareVendor = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t FirmwareDate = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly ay MachineID = [...];

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly ay BootID = [...];

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly u VSockCID = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s ChassisAssetTag = '...';

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

Whenever the hostname or other metadata is changed via the daemon, PropertyChanged signals are sent out to subscribed clients. Changing a hostname using this interface is authenticated via polkit[1].

## SEMANTICS
The StaticHostname property exposes the "static" hostname configured in /etc/hostname. It is not always in sync with the current hostname as returned by the gethostname(3) system call. If no static hostname is configured this property will be the empty string.

When systemd(1) or systemd-hostnamed.service(8) set the hostname, this static hostname has the highest priority.

The Hostname property exposes the actual hostname configured in the kernel via sethostname(2). It can be different from the static hostname. This property is never empty.

The PrettyHostname property exposes the pretty hostname which is a free-form UTF-8 hostname for presentation to the user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. E.g. when the former is "Lennart’s Computer" the latter should be "lennarts-computer". If no pretty hostname is set this setting will be the empty string. Applications should then find a suitable fallback, such as the dynamic hostname.

The DefaultHostname property exposes the default hostname (configured through os-release(5), or a fallback set at compilation time).

The HostnameSource property exposes the origin of the currently configured hostname. One of "static" (set from /etc/hostname), "transient" (a non-permanent hostname from an external source), "default" (the value from os-release or the compiled-in fallback).

The IconName property exposes the icon name following the XDG icon naming spec. If not set, information such as the chassis type (see below) is used to find a suitable fallback icon name (i.e. "computer-laptop" vs. "computer-desktop" is picked based on the chassis information). If no such data is available, the empty string is returned. In that case an application should fall back to a replacement icon, for example "computer". If this property is set to the empty string, the automatic fallback name selection is enabled again.

The Chassis property exposes a chassis type, one of the currently defined chassis types: "desktop", "laptop", "server", "tablet", "handset", as well as the special chassis types "vm" and "container" for virtualized systems. Note that in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of the chassis type from firmware information.

Note that systemd-hostnamed starts only on request and terminates after a short idle period. This effectively means that PropertyChanged messages are not sent out for changes made directly on the files (as in: administrator edits the files with vi). This is the intended behavior: manual configuration changes should require manual reloading.

The transient (dynamic) hostname exposed by the Hostname property maps directly to the kernel hostname. This hostname should be assumed to be highly dynamic, and hence should be watched directly, without depending on PropertyChanged messages from systemd-hostnamed. To accomplish this, open /proc/sys/kernel/hostname and poll(3) for SIGHUP which is triggered by the kernel every time the hostname changes. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname.

Applications may read the hostname data directly if hostname change notifications are not necessary. Use gethostname(2), /etc/hostname (possibly with per-distribution fallbacks), and machine-info(5) for that. For more information on these files and syscalls see the respective man pages.

KernelName, KernelRelease, and KernelVersion expose the kernel name (e.g. "Linux"), release (e.g. "5.0.0-11"), and version (i.e. the build number, e.g. "#11") as reported by uname(2). OperatingSystemPrettyName, OperatingSystemCPEName, and HomeURL expose the PRETTY_NAME=, CPE_NAME= and HOME_URL= fields from os-release(5). The purpose of those properties is to allow remote clients to access this information over D-Bus. Local clients can access the information directly.

MachineID expose the 128bit machine ID, see machine-id(5) for details.

BootID expose the 128bit boot ID, as per /proc/sys/kernel/random/boot_id.

VSockCID exposes the system's local AF_VSOCK CID (Context Identifier, i.e. address) for the system, if one is available in the virtual machine environment. Set to UINT32_MAX otherwise. See vsock(7) for details.

OperatingSystemSupportEnd exposes when the OS' vendor support ends, if this information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If this information is not known carries the value 2^64-1, i.e. UINT64_MAX.

OperatingSystemImageID and OperatingSystemImageVersion expose the OS image name and version if available, or contain empty strings otherwise. This mostly corresponds to the IMAGE_ID= and IMAGE_VERSION= fields of the os-release file.

HardwareVendor, HardwareModel, HardwareSKU, and HardwareVersion expose vendor information about the hardware of the system. The stock keeping unit (SKU) describes a distinct type of hardware for sale, purchase or inventory management. The SKU and version are only available if they deviate from the model and among each other. Thereby the version is more specific and only available if it differs from the model and SKU. If no such information can be determined these properties are set to empty strings.

FirmwareVersion and FirmwareVendor expose information about the system's firmware, i.e. a version string and a vendor name. If no such information can be determined these properties are set to empty strings.

FirmwareDate exposes the firmware build date, if that information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If not known UNIT64_MAX.

ChassisAssetTag exposes an unique identifier of the system chassis. If this information is not known this property is set to an empty string.

### Methods
SetHostname() sets the transient (dynamic) hostname, which is used if no static hostname is set. This value must be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. An empty string will unset the transient hostname.

SetStaticHostname() sets the static hostname which is exposed by the StaticHostname property. When called with an empty argument, the static configuration in /etc/hostname is removed. Since the static hostname has the highest priority, calling this function usually affects also the Hostname property and the effective hostname configured in the kernel.

SetPrettyHostname() sets the pretty hostname which is exposed by the PrettyHostname property.

SetIconName(), SetChassis(), SetDeployment(), and SetLocation() set the properties IconName (the name of the icon representing for the machine), Chassis (the machine form factor), Deployment (the system deployment environment), and Location (physical system location), respectively.

PrettyHostname, IconName, Chassis, Deployment, and Location are stored in /etc/machine-info. See machine-info(5) for the semantics of those settings.

GetProductUUID() returns the "product UUID" as exposed by the kernel based on DMI information in /sys/class/dmi/id/product_uuid. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework.

GetHardwareSerial() returns the "hardware serial" as exposed by the kernel based on DMI information. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework.

Describe() returns a JSON representation of all properties in one.

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

The polkit action for SetHostname() is org.freedesktop.hostname1.set-hostname. For SetStaticHostname() and SetPrettyHostname() it is org.freedesktop.hostname1.set-static-hostname. For SetIconName(), SetChassis(), SetDeployment() and SetLocation() it is org.freedesktop.hostname1.set-machine-info.

## RECOMMENDATIONS
Here are three examples that show how the pretty hostname and the icon name should be used:

•When registering DNS-SD services: use the pretty hostname in the service name, and pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon on each service. This is especially useful for WebDAV applications or UPnP media sharing.

•Set the bluetooth name to the pretty hostname.

•When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set.

To properly handle name lookups with changing local hostnames without having to edit /etc/hosts, we recommend using systemd-hostnamed in combination with nss-myhostname(8).

Here are some recommendations to follow when generating a static (internet) hostname from a pretty name:

•Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, or replace them with "-".

•It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way these days. In fact, restrict your charset to "a-zA-Z0-9" and "-". Strip other chars, or try to replace them in some smart way with chars from this set, for example "ä" → "ae", and use "-" as the replacement for all punctuation characters and whitespace.

•Try to avoid creating repeated "-", as well as "-" as the first or last char.

•Limit the hostname to 63 chars, which is the length of a DNS label.

•If after stripping special chars the empty string is the result, you can pass this as-is to systemd-hostnamed in which case it will automatically use a suitable fallback.

•Uppercase characters should be replaced with their lowercase equivalents.

Note that while systemd-hostnamed applies some checks to the hostname you pass they are much looser than the recommendations above. For example, systemd-hostnamed will also accept "_" in the hostname, but we recommend not using this to avoid clashes with DNS-SD service types. Also systemd-hostnamed allows longer hostnames, but because of the DNS label limitations, we recommend not making use of this.

Here are a couple of example conversions:

•"Lennart's PC" → "lennarts-pc"

•"Müllers Computer" → "muellers-computer"

•"Voran!" → "voran"

•"Es war einmal ein Männlein" → "es-war-einmal-ein-maennlein"

•"Jawoll. Ist doch wahr!" → "jawoll-ist-doch-wahr"

•"レナート" → "localhost"

•"...zack!!! zack!..." → "zack-zack"

Of course, an already valid internet hostname label you enter and pass through this conversion should stay unmodified, so that users have direct control of it, if they want — by simply ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet name.

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

```
$ gdbus introspect --system \

  --dest org.freedesktop.hostname1 \

  --object-path /org/freedesktop/hostname1
```

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

## HISTORY

### The D-Bus API
FirmwareVersion and GetHardwareSerial() were added in version 251.

OperatingSystemSupportEnd, FirmwareVendor, and FirmwareDate were added in version 253.

MachineID, BootID and VSockCID were added in version 256.

ChassisAssetTag, OperatingSystemImageID, OperatingSystemImageVersion, HardwareSKU, and HardwareVersion were added in version 258.

## SEE ALSO
systemd(1), systemd-hostnamed.service(8), hostnamectl(1), David Zeuthen's original Fedora Feature page about xdg-hostname[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.

Feature page about xdg-hostname

https://fedoraproject.org/wiki/Features/BetterHostname


title: org.freedesktop.locale1(5)

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

text:
# org.freedesktop.locale1(5)

## NAME
org.freedesktop.locale1 - The D-Bus interface of systemd-localed

## INTRODUCTION
systemd-localed.service(8) is a system service that can be used to control the system locale and keyboard mapping from user programs. This page describes the D-Bus interface.

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

```
node /org/freedesktop/locale1 {

  interface org.freedesktop.locale1 {

    methods:

      SetLocale(in  as locale,

                in  b interactive);

      SetVConsoleKeyboard(in  s keymap,

                          in  s keymap_toggle,

                          in  b convert,

                          in  b interactive);

      SetX11Keyboard(in  s layout,

                     in  s model,

                     in  s variant,

                     in  s options,

                     in  b convert,

                     in  b interactive);

    properties:

      readonly as Locale = ['...', ...];

      readonly s X11Layout = '...';

      readonly s X11Model = '...';

      readonly s X11Variant = '...';

      readonly s X11Options = '...';

      readonly s VConsoleKeymap = '...';

      readonly s VConsoleKeymapToggle = '...';

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
If you set a new system locale all old system locale settings will be dropped and the new settings will be saved to disk. The locale will also be passed to the system manager, and subsequently started daemons will inherit the new system locale. Note that already running daemons will not learn about the new value.

The SetVConsoleKeyboard() method may be used to set the key mapping for the virtual console. Similarly, SetX11Keyboard() may be used to set the default key mapping of any X11 servers.

Note that SetVConsoleKeyboard() instantly applies the new key mapping to the console, while SetX11Keyboard() simply sets a default that may be used by later sessions.

The boolean argument convert may be set to optionally convert the console keyboard configuration to X11 keyboard mappings and vice versa. If true and SetVConsoleKeyboard() is used, the nearest X11 keyboard setting for the chosen console setting is set. If true and SetX11Keyboard() is used, the nearest console keyboard setting for the chosen X11 setting is set. Hence, it is usually sufficient to call only one of the two functions.

For graphical UIs that need to set the system keyboard mapping simply invoke SetX11Keyboard(), set convert=true and ignore SetVConsoleKeyboard().

Use the empty string for the keymap parameters you wish not to set.

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

### Signals
Whenever the system locale or keymap is changed via the daemon, PropertyChanged signals are sent out to clients which have subscribed.

### Properties
The system locale is shown in the Locale property. It is an array containing environment-variable-assignment-like strings. The following strings are known: LANG=, LC_CTYPE=, LC_NUMERIC=, LC_TIME=, LC_COLLATE=, LC_MONETARY=, LC_MESSAGES=, LC_PAPER=, LC_NAME=, LC_ADDRESS=, LC_TELEPHONE=, LC_MEASUREMENT=, LC_IDENTIFICATION=.

The X11Layout, X11Model, X11Variant, and X11Options properties show values configurable with SetX11Keyboard() described above (or SetVConsoleKeyboard() with convert=true). The VConsoleKeymap and VConsoleKeymapToggle properties show values configurable with SetVConsoleKeyboard() (or SetX11Keyboard() with convert=true).

### Security
Changing the system locale or keymap using this interface is authenticated via polkit. The polkit action for SetLocale() is org.freedesktop.locale1.set-locale. The polkit action for SetX11Keyboard() and SetVConsoleKeyboard() is org.freedesktop.locale1.set-keyboard.

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

```
$ gdbus introspect --system \

  --dest org.freedesktop.locale1 \

  --object-path /org/freedesktop/locale1
```

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

## SEE ALSO
systemd(1), systemd-localed.service(8), localectl(1)

## 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