binfmt.d

package: systemd

title: binfmt.d(5)

text:
# binfmt.d(5)

## NAME
binfmt.d - Configure additional binary formats for executables at boot

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

/run/binfmt.d/*.conf

/lib/binfmt.d/*.conf

## DESCRIPTION
At boot, systemd-binfmt.service(8) reads configuration files from the above directories to register in the kernel additional binary formats for executables.

## CONFIGURATION FORMAT
Each file contains a list of binfmt_misc kernel binary format rules. Consult the kernel's binfmt-misc.rst[1] documentation file for more information on registration of additional binary formats and how to write rules.

Empty lines and lines beginning with ; and # are ignored. Note that this means you may not use ; and # as delimiter in binary format rules.

## CONFIGURATION DIRECTORIES AND PRECEDENCE
Configuration files are read from directories in /etc/, /run/, /usr/local/lib/, and /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 /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). 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 of the files.

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/binfmt.d/wine.conf example:

```
# Start WINE on Windows executables
:DOSWin:M::MZ::/usr/bin/wine:
```

## SEE ALSO
systemd(1), systemd-binfmt.service(8), systemd-delta(1), wine(8)

## NOTES
1.

binfmt-misc.rst

https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html


crypttab

title: crypttab(5)

text:
# crypttab(5)

## NAME
crypttab - Configuration for encrypted block devices

## SYNOPSIS
/etc/crypttab

## DESCRIPTION
The /etc/crypttab file describes encrypted block devices that are set up during system boot.

Empty lines and lines starting with the "#" character are ignored. Each of the remaining lines describes one encrypted block device. Fields are delimited by white space.

Each line is in the form

```
volume-name encrypted-device key-file options
```

The first two fields are mandatory, the remaining two are optional.

Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt, BitLocker and plain. See cryptsetup(8) for more information about each mode. When no mode is specified in the options field and the block device contains a LUKS signature, it is opened as a LUKS device; otherwise, it is assumed to be in raw dm-crypt (plain mode) format.

The four fields of /etc/crypttab are defined as follows:

1.The first field contains the name of the resulting volume with decrypted data; its block device is set up below /dev/mapper/.

2.The second field contains a path to the underlying block device or file, or a specification of a block device via "UUID=" followed by the UUID.

3.The third field specifies an absolute path to a file with the encryption key. Optionally, the path may be followed by ":" and an /etc/fstab style device specification (e.g. starting with "LABEL=" or similar); in which case the path is taken relative to the specified device's file system root. If the field is not present or is "none" or "-", a key file named after the volume to unlock (i.e. the first column of the line), suffixed with .key is automatically loaded from the /etc/cryptsetup-keys.d/ and /run/cryptsetup-keys.d/ directories, if present. Otherwise, the password has to be manually entered during system boot. For swap encryption, /dev/urandom may be used as key file, resulting in a randomized key. If the specified key file path refers to an AF_UNIX stream socket in the file system, the key is acquired by connecting to the socket and reading it from the connection. This allows the implementation of a service to provide key information dynamically, at the moment when it is needed. For details see below.

4.The fourth field, if present, is a comma-delimited list of options. The supported options are listed below.

## KEY ACQUISITION
Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted volume are supported. Specifically:

1.Most prominently, the user may be queried interactively during volume activation (i.e. typically at boot), asking them to type in the necessary passphrase(s).

2.The (unencrypted) key may be read from a file on disk, possibly on removable media. The third field of each line encodes the location, for details see above.

3.The (unencrypted) key may be requested from another service, by specifying an AF_UNIX file system socket in place of a key file in the third field. For details see above and below.

4.The key may be acquired via a PKCS#11 compatible hardware security token or smartcard. In this case an encrypted key is stored on disk/removable media, acquired via AF_UNIX, or stored in the LUKS2 JSON token metadata header. The encrypted key is then decrypted by the PKCS#11 token with an RSA key stored on it, and then used to unlock the encrypted volume. Use the pkcs11-uri= option described below to use this mechanism.

5.Similar, the key may be acquired via a FIDO2 compatible hardware security token (which must implement the "hmac-secret" extension). In this case a (during enrollment) randomly generated key is stored on disk/removable media, acquired via AF_UNIX, or stored in the LUKS2 JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the FIDO2 token, using a secret key stored on the token that never leaves it. The resulting hash value is then used as key to unlock the encrypted volume. Use the fido2-device= option described below to use this mechanism.

6.Similar, the key may be acquired via a TPM2 security chip. In this case a (during enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed key — is stored on disk/removable media, acquired via AF_UNIX, or stored in the LUKS2 JSON token metadata header. Use the tpm2-device= option described below to use this mechanism.

For the latter five mechanisms the source for the key material used for unlocking the volume is primarily configured in the third field of each /etc/crypttab line, but may also configured in /etc/cryptsetup-keys.d/ and /run/cryptsetup-keys.d/ (see above) or in the LUKS2 JSON token header (in case of the latter three). Use the systemd-cryptenroll(1) tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes.

## SUPPORTED OPTIONS
The following options may be used in the fourth field of each line:

cipher=

Specifies the cipher to use. See cryptsetup(8) for possible values and the default value of this option. A cipher with unpredictable IV values, such as "aes-cbc-essiv:sha256", is recommended. Embedded commas in the cipher specification need to be escaped by preceding them with a backslash, see example below.

discard

Allow discard requests to be passed through the encrypted block device. This improves performance on SSD storage but has security implications.

hash=

Specifies the hash to use for password hashing. See cryptsetup(8) for possible values and the default value of this option.

header=

Use a detached (separated) metadata device or file where the LUKS header is stored. This option is only relevant for LUKS devices. See cryptsetup(8) for possible values and the default value of this option. Optionally, the path may be followed by ":" and an /etc/fstab device specification (e.g. starting with "UUID=" or similar); in which case, the path is relative to the device file system root. The device gets mounted automatically for LUKS device activation duration only.

keyfile-offset=

Specifies the number of bytes to skip at the start of the key file. See cryptsetup(8) for possible values and the default value of this option.

keyfile-size=

Specifies the maximum number of bytes to read from the key file. See cryptsetup(8) for possible values and the default value of this option. This option is ignored in plain encryption mode, as the key file size is then given by the key size.

keyfile-erase

If enabled, the specified key file is erased after the volume is activated or when activation fails. This is in particular useful when the key file is only acquired transiently before activation (e.g. via a file in /run/, generated by a service running before activation), and shall be removed after use. Defaults to off.

key-slot=

Specifies the key slot to compare the passphrase or key against. If the key slot does not match the given passphrase or key, but another would, the setup of the device will fail regardless. This option implies luks. See cryptsetup(8) for possible values. The default is to try all key slots in sequential order.

keyfile-timeout=

Specifies the timeout for the device on which the key file resides and falls back to a password if it could not be mounted. See systemd-cryptsetup-generator(8) for key files on external devices.

luks

Force LUKS mode. When this mode is used, the following options are ignored since they are provided by the LUKS header on the device: cipher=, hash=, size=.

bitlk

Decrypt BitLocker drive. Encryption parameters are deduced by cryptsetup from BitLocker header.

_netdev

Marks this cryptsetup device as requiring network. It will be started after the network is available, similarly to systemd.mount(5) units marked with _netdev. The service unit to set up this device will be ordered between remote-fs-pre.target and remote-cryptsetup.target, instead of cryptsetup-pre.target and cryptsetup.target. Hint: if this device is used for a mount point that is specified in fstab(5), the _netdev option should also be used for the mount point. Otherwise, a dependency loop might be created where the mount point will be pulled in by local-fs.target, while the service to configure the network is usually only started after the local file system has been mounted.

noauto

This device will not be added to cryptsetup.target. This means that it will not be automatically unlocked on boot, unless something else pulls it in. In particular, if the device is used for a mount point, it'll be unlocked automatically during boot, unless the mount point itself is also disabled with noauto.

nofail

This device will not be a hard dependency of cryptsetup.target. It'll still be pulled in and started, but the system will not wait for the device to show up and be unlocked, and boot will not fail if this is unsuccessful. Note that other units that depend on the unlocked device may still fail. In particular, if the device is used for a mount point, the mount point itself also needs to have the nofail option, or the boot will fail if the device is not unlocked successfully.

offset=

Start offset in the backend device, in 512-byte sectors. This option is only relevant for plain devices.

plain

Force plain encryption mode.

read-only, readonly

Set up the encrypted block device in read-only mode.

same-cpu-crypt

Perform encryption using the same CPU that IO was submitted on. The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs. This requires kernel 4.0 or newer.

submit-from-crypt-cpus

Disable offloading writes to a separate thread after encryption. There are some situations where offloading write requests from the encryption threads to a dedicated thread degrades performance significantly. The default is to offload write requests to a dedicated thread because it benefits the CFQ scheduler to have writes submitted using the same context. This requires kernel 4.0 or newer.

no-read-workqueue

Bypass dm-crypt internal workqueue and process read requests synchronously. The default is to queue these requests and process them asynchronously. This requires kernel 5.9 or newer.

no-write-workqueue

Bypass dm-crypt internal workqueue and process write requests synchronously. The default is to queue these requests and process them asynchronously. This requires kernel 5.9 or newer.

skip=

How many 512-byte sectors of the encrypted data to skip at the beginning. This is different from the offset= option with respect to the sector numbers used in initialization vector (IV) calculation. Using offset= will shift the IV calculation by the same negative amount. Hence, if offset=n is given, sector n will get a sector number of 0 for the IV calculation. Using skip= causes sector n to also be the first sector of the mapped device, but with its number for IV generation being n. This option is only relevant for plain devices.

size=

Specifies the key size in bits. See cryptsetup(8) for possible values and the default value of this option.

sector-size=

Specifies the sector size in bytes. See cryptsetup(8) for possible values and the default value of this option.

swap

The encrypted block device will be used as a swap device, and will be formatted accordingly after setting up the encrypted block device, with mkswap(8). This option implies plain. WARNING: Using the swap option will destroy the contents of the named partition during every boot, so make sure the underlying block device is specified correctly.

tcrypt

Use TrueCrypt encryption mode. When this mode is used, the following options are ignored since they are provided by the TrueCrypt header on the device or do not apply: cipher=, hash=, keyfile-offset=, keyfile-size=, size=. When this mode is used, the passphrase is read from the key file given in the third field. Only the first line of this file is read, excluding the new line character.

Note that the TrueCrypt format uses both passphrase and key files to derive a password for the volume. Therefore, the passphrase and all key files need to be provided. Use tcrypt-keyfile= to provide the absolute path to all key files. When using an empty passphrase in combination with one or more key files, use "/dev/null" as the password file in the third field.

tcrypt-hidden

Use the hidden TrueCrypt volume. This option implies tcrypt. This will map the hidden volume that is inside of the volume provided in the second field. Please note that there is no protection for the hidden volume if the outer volume is mounted instead. See cryptsetup(8) for more information on this limitation.

tcrypt-keyfile=

Specifies the absolute path to a key file to use for a TrueCrypt volume. This implies tcrypt and can be used more than once to provide several key files. See the entry for tcrypt on the behavior of the passphrase and key files when using TrueCrypt encryption mode.

tcrypt-system

Use TrueCrypt in system encryption mode. This option implies tcrypt.

tcrypt-veracrypt

Check for a VeraCrypt volume. VeraCrypt is a fork of TrueCrypt that is mostly compatible, but uses different, stronger key derivation algorithms that cannot be detected without this flag. Enabling this option could substantially slow down unlocking, because VeraCrypt's key derivation takes much longer than TrueCrypt's. This option implies tcrypt.

timeout=

Specifies the timeout for querying for a password. If no unit is specified, seconds is used. Supported units are s, ms, us, min, h, d. A timeout of 0 waits indefinitely (which is the default).

tmp=

The encrypted block device will be prepared for using it as /tmp/; it will be formatted using mkfs(8). Takes a file system type as argument, such as "ext4", "xfs" or "btrfs". If no argument is specified defaults to "ext4". This option implies plain. WARNING: Using the tmp option will destroy the contents of the named partition during every boot, so make sure the underlying block device is specified correctly.

tries=

Specifies the maximum number of times the user is queried for a password. The default is 3. If set to 0, the user is queried for a password indefinitely.

headless=

Takes a boolean argument, defaults to false. If true, never query interactively for the password/PIN. Useful for headless systems.

verify

If the encryption password is read from console, it has to be entered twice to prevent typos.

password-echo=yes|no|masked

Controls whether to echo passwords or security token PINs that are read from console. Takes a boolean or the special string "masked". The default is password-echo=masked. If enabled, the typed characters are echoed literally. If disabled, the typed characters are not echoed in any form, the user will not get feedback on their input. If set to "masked", an asterisk ("*") is echoed for each character typed. Regardless of which mode is chosen, if the user hits the tabulator key ("↹") at any time, or the backspace key ("⌫") before any other data has been entered, then echo is turned off.

pkcs11-uri=

Takes either the special value "auto" or an RFC7512 PKCS#11 URI[1] pointing to a private RSA key which is used to decrypt the encrypted key specified in the third column of the line. This is useful for unlocking encrypted volumes through PKCS#11 compatible security tokens or smartcards. See below for an example how to set up this mechanism for unlocking a LUKS2 volume with a YubiKey security token. If specified as "auto" the volume must be of type LUKS2 and must carry PKCS#11 security token metadata in its LUKS2 JSON token section. In this mode the URI and the encrypted key are automatically read from the LUKS2 JSON token header. Use systemd-cryptenroll(1) as simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with "auto". In this mode the third column of the line should remain empty (that is, specified as "-").

The specified URI can refer directly to a private RSA key stored on a token or alternatively just to a slot or token, in which case a search for a suitable private RSA key will be performed. In this case if multiple suitable objects are found the token is refused. The encrypted key configured in the third column of the line is passed as is (i.e. in binary form, unprocessed) to RSA decryption. The resulting decrypted key is then Base64 encoded before it is used to unlock the LUKS volume.

Use systemd-cryptenroll --pkcs11-token-uri=list to list all suitable PKCS#11 security tokens currently plugged in, along with their URIs.

Note that many newer security tokens that may be used as PKCS#11 security token typically also implement the newer and simpler FIDO2 standard. Consider using fido2-device= (described below) to enroll it via FIDO2 instead. Note that a security token enrolled via PKCS#11 cannot be used to unlock the volume via FIDO2, unless also enrolled via FIDO2, and vice versa.

fido2-device=

Takes either the special value "auto" or the path to a "hidraw" device node (e.g. /dev/hidraw1) referring to a FIDO2 security token that implements the "hmac-secret" extension (most current hardware security tokens do). See below for an example how to set up this mechanism for unlocking an encrypted volume with a FIDO2 security token. If specified as "auto" the FIDO2 token device is automatically discovered, as it is plugged in.

FIDO2 volume unlocking requires a client ID hash (CID) to be configured via fido2-cid= (see below) and a key to pass to the security token's HMAC functionality (configured in the line's third column) to operate. If not configured and the volume is of type LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead. Use systemd-cryptenroll(1) as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is only available for LUKS2 volumes.

Use systemd-cryptenroll --fido2-device=list to list all suitable FIDO2 security tokens currently plugged in, along with their device nodes.

This option implements the following mechanism: the configured key is hashed via they HMAC keyed hash function the FIDO2 device implements, keyed by a secret key embedded on the device. The resulting hash value is Base64 encoded and used to unlock the LUKS2 volume. As it should not be possible to extract the secret from the hardware token, it should not be possible to retrieve the hashed key given the configured key — without possessing the hardware token.

Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for unlocking volumes via the pkcs11-uri= option described above. Typically the newer, simpler FIDO2 standard is preferable.

fido2-cid=

Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation. If specified, but fido2-device= is not, fido2-device=auto is implied. If fido2-device= is used but fido2-cid= is not, the volume must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header. Use systemd-cryptenroll(1) for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic mode.

fido2-rp=

Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock operation. If not specified "io.systemd.cryptsetup" is used, except if the LUKS2 JSON token header contains a different value. It should normally not be necessary to override this.

tpm2-device=

Takes either the special value "auto" or the path to a device node (e.g. /dev/tpmrm0) referring to a TPM2 security chip. See below for an example how to set up this mechanism for unlocking an encrypted volume with a TPM2 chip. Use tpm2-pcrs= (see below) to configure the set of TPM2 PCRs to bind the volume unlocking to. Use systemd-cryptenroll(1) as simple tool for enrolling TPM2 security chips in LUKS2 volumes.

If specified as "auto" the TPM2 device is automatically discovered. Use systemd-cryptenroll --tpm2-device=list to list all suitable TPM2 devices currently available, along with their device nodes.

This option implements the following mechanism: when enrolling a TPM2 device via systemd-cryptenroll on a LUKS2 volume, a randomized key unlocking the volume is generated on the host and loaded into the TPM2 chip where it is encrypted with an asymmetric "primary" key pair derived from the TPM2's internal "seed" key. Neither the seed key nor the primary key are permitted to ever leave the TPM2 chip — however, the now encrypted randomized key may. It is saved in the LUKS2 volume JSON token header. When unlocking the encrypted volume, the primary key pair is generated on the TPM2 chip again (which works as long as the chip's seed key is correctly maintained by the TPM2 chip), which is then used to decrypt (on the TPM2 chip) the encrypted key from the LUKS2 volume JSON token header saved there during enrollment. The resulting decrypted key is then used to unlock the volume. When the randomized key is encrypted the current values of the selected PCRs (see below) are included in the operation, so that different PCR state results in different encrypted keys and the decrypted key can only be recovered if the same PCR state is reproduced.

tpm2-pcrs=

Takes a "+" separated list of numeric TPM2 PCR (i.e. "Platform Configuration Register") indexes to bind the TPM2 volume unlocking to. This option is only useful when TPM2 enrollment metadata is not available in the LUKS2 JSON token header already, the way systemd-cryptenroll writes it there. If not used (and no metadata in the LUKS2 JSON token header defines it), defaults to a list of a single entry: PCR 7. Assign an empty string to encode a policy that binds the key to no PCRs, making the key accessible to local programs regardless of the current PCR state.

try-empty-password=

Takes a boolean argument. If enabled, right before asking the user for a password it is first attempted to unlock the volume with an empty password. This is useful for systems that are initialized with an encrypted volume with only an empty password set, which shall be replaced with a suitable password during first boot, but after activation.

x-systemd.device-timeout=

Specifies how long systemd should wait for a device to show up before giving up on the entry. The argument is a time in seconds or explicitly specified units of "s", "min", "h", "ms".

x-initrd.attach

Setup this encrypted block device in the initramfs, similarly to systemd.mount(5) units marked with x-initrd.mount. Although it's not necessary to mark the mount entry for the root file system with x-initrd.mount, x-initrd.attach is still recommended with the encrypted block device containing the root file system as otherwise systemd will attempt to detach the device during the regular system shutdown while it's still in use. With this option the device will still be detached but later after the root file system is unmounted.

All other encrypted block devices that contain file systems mounted in the initramfs should use this option.

At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by systemd-cryptsetup-generator(8).

## AF_UNIX KEY FILES
If the key file path (as specified in the third column of /etc/crypttab entries, see above) refers to an AF_UNIX stream socket in the file system, the key is acquired by connecting to the socket and reading the key from the connection. The connection is made from an AF_UNIX socket name in the abstract namespace, see unix(7) for details. The source socket name is chosen according the following format:

```
NUL RANDOM "/cryptsetup/" VOLUME
```

In other words: a NUL byte (as required for abstract namespace sockets), followed by a random string (consisting of alphanumeric characters only), followed by the literal string "/cryptsetup/", followed by the name of the volume to acquire they key for. Example (for a volume "myvol"):

Example 1.

```
\0d7067f78d9827418/cryptsetup/myvol
```

Services listening on the AF_UNIX stream socket may query the source socket name with getpeername(2), and use it to determine which key to send, allowing a single listening socket to serve keys for a multitude of volumes. If the PKCS#11 logic is used (see above) the socket source name is picked in identical fashion, except that the literal string "/cryptsetup-pkcs11/" is used (similar for FIDO2: "/cryptsetup-fido2/" and TPM2: "/cryptsetup-tpm2/"). This is done so that services providing key material know that not a secret key is requested but an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key.

## EXAMPLES
Example 2. /etc/crypttab example

Set up four encrypted block devices. One using LUKS for normal storage, another one for usage as a swap device and two TrueCrypt volumes. For the fourth device, the option string is interpreted as two options "cipher=xchacha12,aes-adiantum-plain64", "keyfile-timeout=10s".

```
luks       UUID=2505567a-9e27-4efe-a4d5-15ad146c258b
swap       /dev/sda7       /dev/urandom       swap
truecrypt  /dev/sda2       /etc/container_password  tcrypt
hidden     /mnt/tc_hidden  /dev/null    tcrypt-hidden,tcrypt-keyfile=/etc/keyfile
external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchacha12\,aes-adiantum-plain64
```

Example 3. Yubikey-based PKCS#11 Volume Unlocking Example

The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA decryption keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey security token for this purpose on a LUKS2 volume, using ykmap(1) from the yubikey-manager project to initialize the token and systemd-cryptenroll(1) to add it in the LUKS2 volume:

```
# Destroy any old key on the Yubikey (careful!)
ykman piv reset
# Generate a new private/public key pair on the device, store the public key in
# 'pubkey.pem'.
ykman piv generate-key -a RSA2048 9d pubkey.pem
# Create a self-signed certificate from this public key, and store it on the
# device. The "subject" should be an arbitrary user-chosen string to identify
# the token with.
ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
# We don't need the public key anymore, let's remove it. Since it is not
# security sensitive we just do a regular "rm" here.
rm pubkey.pem
# Enroll the freshly initialized security token in the LUKS2 volume. Replace
# /dev/sdXn by the partition to use (e.g. /dev/sda1).
sudo systemd-cryptenroll --pkcs11-token-uri=auto /dev/sdXn
# Test: Let's run systemd-cryptsetup to test if this all worked.
sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - pkcs11-uri=auto
# If that worked, let's now add the same line persistently to /etc/crypttab,
# for the future.
sudo bash -c 'echo "mytest /dev/sdXn - pkcs11-uri=auto" >> /etc/crypttab'
```

A few notes on the above:

•We use RSA2048, which is the longest key size current Yubikeys support

•We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, see documentation[2].

Example 4. FIDO2 Volume Unlocking Example

The FIDO2 logic allows using any compatible FIDO2 security token that implements the "hmac-secret" extension for unlocking an encrypted volume. Here's an example how to set up a FIDO2 security token for this purpose for a LUKS2 volume, using systemd-cryptenroll(1):

```
# Enroll the security token in the LUKS2 volume. Replace /dev/sdXn by the
# partition to use (e.g. /dev/sda1).
sudo systemd-cryptenroll --fido2-device=auto /dev/sdXn
# Test: Let's run systemd-cryptsetup to test if this worked.
sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - fido2-device=auto
# If that worked, let's now add the same line persistently to /etc/crypttab,
# for the future.
sudo bash -c 'echo "mytest /dev/sdXn - fido2-device=auto" >> /etc/crypttab'
```

Example 5. TPM2 Volume Unlocking Example

The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume, using systemd-cryptenroll(1):

```
# Enroll the TPM2 security chip in the LUKS2 volume, and bind it to PCR 7
# only. Replace /dev/sdXn by the partition to use (e.g. /dev/sda1).
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/sdXn
# Test: Let's run systemd-cryptsetup to test if this worked.
sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - tpm2-device=auto
# If that worked, let's now add the same line persistently to /etc/crypttab,
# for the future.
sudo bash -c 'echo "mytest /dev/sdXn - tpm2-device=auto" >> /etc/crypttab'
```

## SEE ALSO
systemd(1), systemd-cryptsetup@.service(8), systemd-cryptsetup-generator(8), systemd-cryptenroll(1), fstab(5), cryptsetup(8), mkswap(8), mke2fs(8)

## NOTES
1.

RFC7512 PKCS#11 URI

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

2.

see documentation

https://developers.yubico.com/PIV/Introduction/Certificate_slots.html


environment.d

title: environment.d(5)

summary: Definition of user service environment

text:
# environment.d(5)

## NAME
environment.d - Definition of user service environment

## SYNOPSIS
~/.config/environment.d/*.conf

/etc/environment.d/*.conf

/run/environment.d/*.conf

/usr/lib/environment.d/*.conf

/lib/environment.d/*.conf

/etc/environment

## DESCRIPTION
Configuration files in the environment.d/ directories contain lists of environment variable assignments for services started by the systemd user instance. systemd-environment-d-generator(8) parses them and updates the environment exported by the systemd user instance. See below for an discussion of which processes inherit those variables.

It is recommended to use numerical prefixes for file names to simplify ordering.

For backwards compatibility, a symlink to /etc/environment is installed, so this file is also parsed.

## CONFIGURATION DIRECTORIES AND PRECEDENCE
Configuration files are read from directories in /etc/, /run/, /usr/local/lib/, and /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 /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). 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 of the files.

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.

## CONFIGURATION FORMAT
The configuration files contain a list of "KEY=VALUE" environment variable assignments, separated by newlines. The right hand side of these assignments may reference previously defined environment variables, using the "${OTHER_KEY}" and "$OTHER_KEY" format. It is also possible to use "${FOO:-DEFAULT_VALUE}" to expand in the same way as "${FOO}" unless the expansion would be empty, in which case it expands to DEFAULT_VALUE, and use "${FOO:+ALTERNATE_VALUE}" to expand to ALTERNATE_VALUE as long as "${FOO}" would have expanded to a non-empty value. No other elements of shell syntax are supported.

Each KEY must be a valid variable name. Empty lines and lines beginning with the comment character "#" are ignored.

### Example
Example 1. Setup environment to allow access to a program installed in /opt/foo

/etc/environment.d/60-foo.conf:

```
        FOO_DEBUG=force-software-gl,log-verbose

        PATH=/opt/foo/bin:$PATH

        LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

        XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/}

```

## APPLICABILITY
Environment variables exported by the user manager (systemd --user instance started in the user@uid.service system service) apply to any services started by that manager. In particular, this may include services which run user shells. For example in the GNOME environment, the graphical terminal emulator runs as the gnome-terminal-server.service user unit, which in turn runs the user shell, so that shell will inherit environment variables exported by the user manager. For other instances of the shell, not launched by the user manager, the environment they inherit is defined by the program that starts them. Hint: in general, systemd.service(5) units contain programs launched by systemd, and systemd.scope(5) units contain programs launched by something else.

Specifically, for ssh logins, the sshd(8) service builds an environment that is a combination of variables forwarded from the remote system and defined by sshd, see the discussion in ssh(1). A graphical display session will have an analogous mechanism to define the environment. Note that some managers query the systemd user instance for the exported environment and inject this configuration into programs they start, using systemctl show-environment or the underlying D-Bus call.

## SEE ALSO
systemd(1), systemd-environment-d-generator(8), systemd.environment-generator(7)


hostname

title: hostname(5)

summary: Local hostname configuration file

text:
# hostname(5)

## NAME
hostname - Local hostname configuration file

## SYNOPSIS
/etc/hostname

## DESCRIPTION
The /etc/hostname file configures the name of the local system. Unless overridden as described in the next section, systemd(1) will set this hostname during boot using the sethostname(2) system call.

The file should contain a single newline-terminated hostname string. Comments (lines starting with a "#") are ignored. The hostname should be composed of up to 64 7-bit ASCII lower-case alphanumeric characters or hyphens forming a valid DNS domain name. It is recommended that this name contains only a single label, i.e. without any dots. Invalid characters will be filtered out in an attempt to make the name valid, but obviously it is recommended to use a valid name and not rely on this filtering.

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

## HOSTNAME SEMANTICS
systemd(1) and the associated tools will obtain the hostname in the following ways:

•If the kernel commandline parameter systemd.hostname= specifies a valid hostname, systemd(1) will use it to set the hostname during early boot, see kernel-command-line(7),

•Otherwise, the "static" hostname specified by /etc/hostname as described above will be used.

•Otherwise, a transient hostname may be set during runtime, for example based on information in a DHCP lease, see systemd-hostnamed.service(8). Both NetworkManager[1] and systemd-networkd.service(8) allow this. Note that systemd-hostnamed.service(8) gives higher priority to the static hostname, so the transient hostname will only be used if the static hostname is not configured.

•Otherwise, a fallback hostname configured at compilation time will be used ("localhost").

Effectively, the static hostname has higher priority than a transient hostname, which has higher priority than the fallback hostname. Transient hostnames are equivalent, so setting a new transient hostname causes the previous transient hostname to be forgotten. The hostname specified on the kernel command line is like a transient hostname, with the exception that it has higher priority when the machine boots. Also note that those are the semantics implemented by systemd tools, but other programs may also set the hostname.

## HISTORY
The simple configuration file format of /etc/hostname originates from Debian GNU/Linux.

## SEE ALSO
systemd(1), sethostname(2), hostname(1), hostname(7), machine-id(5), machine-info(5), hostnamectl(1), systemd-hostnamed.service(8), systemd-firstboot(8)

## NOTES
1.

NetworkManager

https://developer.gnome.org/NetworkManager/stable/


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

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

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

/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/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. Initially, the main configuration file in /etc/systemd/ contains commented out entries showing the defaults as a guide to the administrator. Local overrides can be created by editing this file or by creating drop-ins, as described below. 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 /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 of the files.

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.

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[1] 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.

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[2] 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".

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 value 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=, so that usually seven rotated journal files are kept as history.

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.

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.

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.

ForwardToSyslog=, ForwardToKMsg=, ForwardToConsole=, ForwardToWall=

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, or sent as wall messages to all logged-in users. These options take boolean arguments. 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. 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").

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

Controls the maximum log level of messages that are stored in the journal, forwarded to syslog, kmsg, the console or wall (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= and MaxLevelSyslog=, to ensure that the all messages are stored in the journal and forwarded to syslog. 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=".

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.

Audit=

Takes a boolean value. If enabled systemd-journal will turn on kernel auditing on start-up. If disabled it will turn it off. If unset it will neither enable nor disable it, leaving the previous state unchanged. 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. This means if another tool turns on auditing even if systemd-journald left it off, it will still collect the generated messages. Defaults to off.

TTYPath=

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

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.

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

Seekable Sequential Key Generators

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

2.

Users, Groups, UIDs and GIDs on systemd systems

https://systemd.io/UIDS-GIDS


locale.conf

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 basic file format of locale.conf is a newline-separated list of environment-like shell-compatible variable assignments. 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.

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 individual users.

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

/etc/locale.conf is usually created and 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(8) to initialize 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:

```
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(8)


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(8) 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(8)


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

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

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

/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. Initially, the main configuration file in /etc/systemd/ contains commented out entries showing the defaults as a guide to the administrator. Local overrides can be created by editing this file or by creating drop-ins, as described below. 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 /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 of the files.

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.

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", 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.

IdleActionSec=

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

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.

HandlePowerKey=, HandleSuspendKey=, HandleHibernateKey=, HandleLidSwitch=, HandleLidSwitchExternalPower=, HandleLidSwitchDocked=, HandleRebootKey=

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", and "lock". If "ignore", 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= and HandleLidSwitch= default 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". HandleHibernateKey= defaults to "hibernate". 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. 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-switch"). 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.

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.

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.

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.

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.

InhibitorsMax=

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

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.

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

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


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

/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 /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 /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). 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 of the files.

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)


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

/etc/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. Initially, the main configuration file in /etc/systemd/ contains commented out entries showing the defaults as a guide to the administrator. Local overrides can be created by editing this file or by creating drop-ins, as described below. 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 /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 of the files.

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

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

DefaultMemoryPressureDurationSec=

Sets the amount of time a unit's control group needs to have exceeded memory pressure limits before systemd-oomd will take action. 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.

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


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

Those two properties are writable, so they may be set by sufficiently privileged users.

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=.)

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

      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 s HomeURL = '...';

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

      readonly s HardwareVendor = '...';

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

      readonly s HardwareModel = '...';

  };

  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(3). 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(3), /etc/hostname (possibly with per-distribution fallbacks), and machine-info(3) 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.

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

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(3).

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

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

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

```
$ gdbus introspect --system \

  --dest org.freedesktop.hostname1 \

  --object-path /org/freedesktop/hostname1

```

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

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

3.

Feature page about xdg-hostname

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