systemd.nspawn

title: systemd.nspawn(5)

summary: Container settings

text:
# systemd.nspawn(5)

## NAME
systemd.nspawn - Container settings

## SYNOPSIS
/etc/systemd/nspawn/machine.nspawn

/run/systemd/nspawn/machine.nspawn

/var/lib/machines/machine.nspawn

## DESCRIPTION
An nspawn container settings file (suffix .nspawn) contains runtime configuration for a local container, and is used used by systemd-nspawn(1). Files of this type are named after the containers they define settings for. They are optional, and only required for containers whose execution environment shall differ from the defaults. Files of this type mostly contain settings that may also be set on the systemd-nspawn command line, and make it easier to persistently attach specific settings to specific containers. The syntax of these files is inspired by .desktop files, similarly to other configuration files supported by the systemd project. See systemd.syntax(7) for an overview.

## .NSPAWN FILE DISCOVERY
Files are searched for by appending the .nspawn suffix to the machine name of the container, as specified with the --machine= switch of systemd-nspawn, or derived from the directory or image file name. This file is first searched for in /etc/systemd/nspawn/ and /run/systemd/nspawn/. If found there, the settings are read and all of them take full effect (but may still be overridden by corresponding command line arguments). Otherwise, the file will then be searched for next to the image file or in the immediate parent of the root directory of the container. If the file is found there, only a subset of the settings will take effect however. All settings that possibly elevate privileges or grant additional access to resources of the host (such as files or directories) are ignored. To which options this applies is documented below.

Persistent settings files created and maintained by the administrator (and thus trusted) should be placed in /etc/systemd/nspawn/, while automatically downloaded (and thus potentially untrusted) settings files are placed in /var/lib/machines/ instead (next to the container images), where their security impact is limited. In order to add privileged settings to .nspawn files acquired from the image vendor, it is recommended to copy the settings files into /etc/systemd/nspawn/ and edit them there, so that the privileged options become available. The precise algorithm for how the files are searched and interpreted may be configured with systemd-nspawn's --settings= switch, see systemd-nspawn(1) for details.

## [EXEC] SECTION OPTIONS
Settings files may include an [Exec] section, which carries various execution parameters:

Boot=

Takes a boolean argument, which defaults to off. If enabled, systemd-nspawn will automatically search for an init executable and invoke it. In this case, the specified parameters using Parameters= are passed as additional arguments to the init process. This setting corresponds to the --boot switch on the systemd-nspawn command line. This option may not be combined with ProcessTwo=yes. This option is specified by default in the systemd-nspawn@.service template unit.

Ephemeral=

Takes a boolean argument, which defaults to off, If enabled, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates. This is equivalent to the --ephemeral command line switch. See systemd-nspawn(1) for details about the specific options supported.

ProcessTwo=

Takes a boolean argument, which defaults to off. If enabled, the specified program is run as PID 2. A stub init process is run as PID 1. This setting corresponds to the --as-pid2 switch on the systemd-nspawn command line. This option may not be combined with Boot=yes.

Parameters=

Takes a whitespace-separated list of arguments. Single ("'") and double (""") quotes may be used around arguments with whitespace. This is either a command line, beginning with the binary name to execute, or – if Boot= is enabled – the list of arguments to pass to the init process. This setting corresponds to the command line parameters passed on the systemd-nspawn command line. Note: Boot=no, Parameters=a b "c c" is the same as systemd-nspawn a b "c c", and Boot=yes, Parameters=b 'c c' is the same as systemd-nspawn --boot b 'c c'.

Environment=

Takes an environment variable assignment consisting of key and value, separated by "=". Sets an environment variable for the main process invoked in the container. This setting may be used multiple times to set multiple environment variables. It corresponds to the --setenv= command line switch.

User=

Takes a UNIX user name. Specifies the user name to invoke the main process of the container as. This user must be known in the container's user database. This corresponds to the --user= command line switch.

WorkingDirectory=

Selects the working directory for the process invoked in the container. Expects an absolute path in the container's file system namespace. This corresponds to the --chdir= command line switch.

PivotRoot=

Selects a directory to pivot to / inside the container when starting up. Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved in the container's file system namespace. This corresponds to the --pivot-root= command line switch.

Capability=, DropCapability=

Takes a space-separated list of Linux process capabilities (see capabilities(7) for details). The Capability= setting specifies additional capabilities to pass on top of the default set of capabilities. The DropCapability= setting specifies capabilities to drop from the default set. These settings correspond to the --capability= and --drop-capability= command line switches. Note that Capability= is a privileged setting, and only takes effect in .nspawn files in /etc/systemd/nspawn/ and /run/system/nspawn/ (see above). On the other hand, DropCapability= takes effect in all cases. If the special value "all" is passed, all capabilities are retained (or dropped). These settings change the bounding set of capabilities which also limits the ambient capabilities as given with the AmbientCapability=.

AmbientCapability=

Takes a space-separated list of Linux process capabilities (see capabilities(7) for details). The AmbientCapability= setting specifies capability which will be passed to the started program in the inheritable and ambient capability sets. This will grant these capabilities to this process. This setting correspond to the --ambient-capability= command line switch. The value "all" is not supported for this setting.

The setting of AmbientCapability= must be covered by the bounding set settings which were established by Capability= and DropCapability=.

Note that AmbientCapability= is a privileged setting (see above).

NoNewPrivileges=

Takes a boolean argument that controls the PR_SET_NO_NEW_PRIVS flag for the container payload. This is equivalent to the --no-new-privileges= command line switch. See systemd-nspawn(1) for details.

KillSignal=

Specify the process signal to send to the container's PID 1 when nspawn itself receives SIGTERM, in order to trigger an orderly shutdown of the container. Defaults to SIGRTMIN+3 if Boot= is used (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly shutdown). For a list of valid signals, see signal(7).

Personality=

Configures the kernel personality for the container. This is equivalent to the --personality= switch.

MachineID=

Configures the 128-bit machine ID (UUID) to pass to the container. This is equivalent to the --uuid= command line switch. This option is privileged (see above).

PrivateUsers=

Configures support for usernamespacing. This is equivalent to the --private-users= command line switch, and takes the same options. This option is privileged (see above). This option is the default if the systemd-nspawn@.service template unit file is used.

NotifyReady=

Configures support for notifications from the container's init process. This is equivalent to the --notify-ready= command line switch, and takes the same parameters. See systemd-nspawn(1) for details about the specific options supported.

SystemCallFilter=

Configures the system call filter applied to containers. This is equivalent to the --system-call-filter= command line switch, and takes the same list parameter. See systemd-nspawn(1) for details.

LimitCPU=, LimitFSIZE=, LimitDATA=, LimitSTACK=, LimitCORE=, LimitRSS=, LimitNOFILE=, LimitAS=, LimitNPROC=, LimitMEMLOCK=, LimitLOCKS=, LimitSIGPENDING=, LimitMSGQUEUE=, LimitNICE=, LimitRTPRIO=, LimitRTTIME=

Configures various types of resource limits applied to containers. This is equivalent to the --rlimit= command line switch, and takes the same arguments. See systemd-nspawn(1) for details.

OOMScoreAdjust=

Configures the OOM score adjustment value. This is equivalent to the --oom-score-adjust= command line switch, and takes the same argument. See systemd-nspawn(1) for details.

CPUAffinity=

Configures the CPU affinity. This is equivalent to the --cpu-affinity= command line switch, and takes the same argument. See systemd-nspawn(1) for details.

Hostname=

Configures the kernel hostname set for the container. This is equivalent to the --hostname= command line switch, and takes the same argument. See systemd-nspawn(1) for details.

ResolvConf=

Configures how /etc/resolv.conf in the container shall be handled. This is equivalent to the --resolv-conf= command line switch, and takes the same argument. See systemd-nspawn(1) for details.

Timezone=

Configures how /etc/localtime in the container shall be handled. This is equivalent to the --timezone= command line switch, and takes the same argument. See systemd-nspawn(1) for details.

LinkJournal=

Configures how to link host and container journal setups. This is equivalent to the --link-journal= command line switch, and takes the same parameter. See systemd-nspawn(1) for details.

## [FILES] SECTION OPTIONS
Settings files may include a [Files] section, which carries various parameters configuring the file system of the container:

ReadOnly=

Takes a boolean argument, which defaults to off. If specified, the container will be run with a read-only file system. This setting corresponds to the --read-only command line switch.

Volatile=

Takes a boolean argument, or the special value "state". This configures whether to run the container with volatile state and/or configuration. This option is equivalent to --volatile=, see systemd-nspawn(1) for details about the specific options supported.

Bind=, BindReadOnly=

Adds a bind mount from the host into the container. Takes a single path, a pair of two paths separated by a colon, or a triplet of two paths plus an option string separated by colons. This option may be used multiple times to configure multiple bind mounts. This option is equivalent to the command line switches --bind= and --bind-ro=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above).

BindUser=

Binds a user from the host into the container. This option is equivalent to the command line switch --bind-user=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above).

TemporaryFileSystem=

Adds a "tmpfs" mount to the container. Takes a path or a pair of path and option string, separated by a colon. This option may be used multiple times to configure multiple "tmpfs" mounts. This option is equivalent to the command line switch --tmpfs=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above).

Inaccessible=

Masks the specified file or directory in the container, by over-mounting it with an empty file node of the same type with the most restrictive access mode. Takes a file system path as argument. This option may be used multiple times to mask multiple files or directories. This option is equivalent to the command line switch --inaccessible=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above).

Overlay=, OverlayReadOnly=

Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches --overlay= and --overlay-ro=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above).

PrivateUsersOwnership=

Configures whether the ownership of the files and directories in the container tree shall be adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the --private-users-ownership= command line switch. This option is privileged (see above).

## [NETWORK] SECTION OPTIONS
Settings files may include a [Network] section, which carries various parameters configuring the network connectivity of the container:

Private=

Takes a boolean argument, which defaults to off. If enabled, the container will run in its own network namespace and not share network interfaces and configuration with the host. This setting corresponds to the --private-network command line switch.

VirtualEthernet=

Takes a boolean argument. Configures whether to create a virtual Ethernet connection ("veth") between host and the container. This setting implies Private=yes. This setting corresponds to the --network-veth command line switch. This option is privileged (see above). This option is the default if the systemd-nspawn@.service template unit file is used.

VirtualEthernetExtra=

Takes a colon-separated pair of interface names. Configures an additional virtual Ethernet connection ("veth") between host and the container. The first specified name is the interface name on the host, the second the interface name in the container. The latter may be omitted in which case it is set to the same name as the host side interface. This setting implies Private=yes. This setting corresponds to the --network-veth-extra= command line switch, and maybe be used multiple times. It is independent of VirtualEthernet=. Note that this option is unrelated to the Bridge= setting below, and thus any connections created this way are not automatically added to any bridge device on the host side. This option is privileged (see above).

Interface=

Takes a space-separated list of interfaces to add to the container. This option corresponds to the --network-interface= command line switch and implies Private=yes. This option is privileged (see above).

MACVLAN=, IPVLAN=

Takes a space-separated list of interfaces to add MACLVAN or IPVLAN interfaces to, which are then added to the container. These options correspond to the --network-macvlan= and --network-ipvlan= command line switches and imply Private=yes. These options are privileged (see above).

Bridge=

Takes an interface name. This setting implies VirtualEthernet=yes and Private=yes and has the effect that the host side of the created virtual Ethernet link is connected to the specified bridge interface. This option corresponds to the --network-bridge= command line switch. This option is privileged (see above).

Zone=

Takes a network zone name. This setting implies VirtualEthernet=yes and Private=yes and has the effect that the host side of the created virtual Ethernet link is connected to an automatically managed bridge interface named after the passed argument, prefixed with "vz-". This option corresponds to the --network-zone= command line switch. This option is privileged (see above).

Port=

Exposes a TCP or UDP port of the container on the host. This option corresponds to the --port= command line switch, see systemd-nspawn(1) for the precise syntax of the argument this option takes. This option is privileged (see above).

## SEE ALSO
systemd(1), systemd-nspawn(1), systemd.directives(7)


coredump.conf

package: systemd-coredump

title: coredump.conf(5)

summary: Core dump storage configuration files

text:
# coredump.conf(5)

## NAME
coredump.conf, coredump.conf.d - Core dump storage configuration files

## SYNOPSIS
/etc/systemd/coredump.conf

/etc/systemd/coredump.conf.d/*.conf

/run/systemd/coredump.conf.d/*.conf

/lib/systemd/coredump.conf.d/*.conf

## DESCRIPTION
These files configure the behavior of systemd-coredump(8), a handler for core dumps invoked by the kernel. Whether systemd-coredump is used is determined by the kernel's kernel.core_pattern sysctl(8) setting. See systemd-coredump(8) and core(5) pages for the details.

## 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 [Coredump] section:

Storage=

Controls where to store cores. One of "none", "external", and "journal". When "none", the core dumps may be logged (including the backtrace if possible), but not stored permanently. When "external" (the default), cores will be stored in /var/lib/systemd/coredump/. When "journal", cores will be stored in the journal and rotated following normal journal rotation patterns. When cores are stored in the journal, they might be compressed following journal compression settings, see journald.conf(5). When cores are stored externally, they will be compressed by default, see below.

Compress=

Controls compression for external storage. Takes a boolean argument, which defaults to "yes".

ProcessSizeMax=

The maximum size in bytes of a core which will be processed. Core dumps exceeding this size may be stored, but the backtrace will not be generated. Like other sizes in this same config file, the usual suffixes to the base of 1024 are allowed (B, K, M, G, T, P, and E). Setting Storage=none and ProcessSizeMax=0 disables all coredump handling except for a log entry.

ExternalSizeMax=, JournalSizeMax=

The maximum (compressed or uncompressed) size in bytes of a core to be saved. Unit suffixes are allowed just as in ProcessSizeMax=.

MaxUse=, KeepFree=

Enforce limits on the disk space, specified in bytes, taken up by externally stored core dumps. Unit suffixes are allowed just as in ProcessSizeMax=. MaxUse= makes sure that old core dumps are removed as soon as the total disk space taken up by core dumps grows beyond this limit (defaults to 10% of the total disk size). KeepFree= controls how much disk space to keep free at least (defaults to 15% of the total disk size). Note that the disk space used by core dumps might temporarily exceed these limits while core dumps are processed. Note that old core dumps are also removed based on time via systemd-tmpfiles(8). Set either value to 0 to turn off size-based cleanup.

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

## SEE ALSO
systemd-journald.service(8), coredumpctl(1), systemd-tmpfiles(8)


homed.conf

package: systemd-homed

title: homed.conf(5)

text:
# homed.conf(5)

## NAME
homed.conf, homed.conf.d - Home area/user account manager configuration files

## SYNOPSIS
/etc/systemd/homed.conf

/etc/systemd/homed.conf.d/*.conf

/run/systemd/homed.conf.d/*.conf

/lib/systemd/homed.conf.d/*.conf

## DESCRIPTION
These configuration files control default parameters for home areas/user accounts created and managed by systemd-homed.service(8).

## 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
The following options are available in the [Home] section:

DefaultStorage=

The default storage to use for home areas. Takes one of "luks", "fscrypt", "directory", "subvolume", "cifs". For details about these options, see homectl(1). If not configured or assigned the empty string, the default storage is automatically determined: if not running in a container environment and /home/ is not itself encrypted, defaults to "luks". Otherwise defaults to "subvolume" if /home/ is on a btrfs file system, and "directory" otherwise. Note that the storage selected on the homectl command line always takes precedence.

DefaultFileSystemType=

When using "luks" as storage (see above), selects the default file system to use inside the user's LUKS volume. Takes one of "btrfs", "ext4" or "xfs". If not specified defaults to "btrfs". This setting has no effect if a different storage mechanism is used. The file system type selected on the homectl command line always takes precedence.

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


title: org.freedesktop.home1(5)

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

text:
# org.freedesktop.home1(5)

## NAME
org.freedesktop.home1 - The D-Bus interface of systemd-homed

## INTRODUCTION
systemd-homed.service(8) is a system service which may be used to create, remove, change or inspect home areas. This page describes the D-Bus interface.

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/home1 {

  interface org.freedesktop.home1.Manager {

    methods:

      GetHomeByName(in  s user_name,

                    out u uid,

                    out s home_state,

                    out u gid,

                    out s real_name,

                    out s home_directory,

                    out s shell,

                    out o bus_path);

      GetHomeByUID(in  u uid,

                   out s user_name,

                   out s home_state,

                   out u gid,

                   out s real_name,

                   out s home_directory,

                   out s shell,

                   out o bus_path);

      GetUserRecordByName(in  s user_name,

                          out s user_record,

                          out b incomplete,

                          out o bus_path);

      GetUserRecordByUID(in  u uid,

                         out s user_record,

                         out b incomplete,

                         out o bus_path);

      ListHomes(out a(susussso) home_areas);

      ActivateHome(in  s user_name,

                   in  s secret);

      DeactivateHome(in  s user_name);

      RegisterHome(in  s user_record);

      UnregisterHome(in  s user_name);

      CreateHome(in  s user_record);

      RealizeHome(in  s user_name,

                  in  s secret);

      RemoveHome(in  s user_name);

      FixateHome(in  s user_name,

                 in  s secret);

      AuthenticateHome(in  s user_name,

                       in  s secret);

      UpdateHome(in  s user_record);

      ResizeHome(in  s user_name,

                 in  t size,

                 in  s secret);

      ChangePasswordHome(in  s user_name,

                         in  s new_secret,

                         in  s old_secret);

      LockHome(in  s user_name);

      UnlockHome(in  s user_name,

                 in  s secret);

      AcquireHome(in  s user_name,

                  in  s secret,

                  in  b please_suspend,

                  out h send_fd);

      RefHome(in  s user_name,

              in  b please_suspend,

              out h send_fd);

      ReleaseHome(in  s user_name);

      LockAllHomes();

      DeactivateAllHomes();

    properties:

      readonly a(sso) AutoLogin = [...];

  };

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

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

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

```

### Methods
GetHomeByName() returns basic user information (a minimal subset of the full user record), provided a user name. The information supplied more or less matches what getpwnam(3) returns: the numeric UID and GID, the real name, home directory and shell. In addition it returns a state identifier describing the state the user's home directory is in, as well as a bus path referring to the bus object encapsulating the user record and home directory. This object implements the org.freedesktop.home1.Home interface documented below.

GetHomeByUID() is similar to GetHomeByName() but acquires the information based on the numeric UID of the user.

GetUserRecordByName() is also similar to GetHomeByName() but returns the full JSON user record data instead of the broken down records. An additional returned boolean indicates whether the record is complete or not. A record is considered complete when its "privileged" section is included, and incomplete if it was removed (see JSON User Records[1] for details about the various sections of a user record). Generally, only privileged clients and clients running under the identity of the user itself get access to the "privileged" section and will thus see complete records.

GetUserRecordByUID() is similar to GetUserRecordByName() but returns the user record matching the specified numeric UID.

ListHomes() returns an array of all locally managed users. The array contains the same fields GetHomeByName() returns: user name, numeric UID, state, numeric GID, real name, home directory, shell and bus path of the matching bus object.

ActivateHome() activates (i.e. mounts) the home directory of the specified user. The second argument shall contain a user record consisting only of a "secret" section (all other sections should be stripped, see JSON User Records[1] for details), and should contain only the secret credentials necessary for unlocking the home directory. Typically a client would invoke this function first with an entirely empty record (which is possibly sufficient if single-factor authentication with a plugged-in security token is configured), and would then retry with a record populated with more information, depending on the returned error code, in case more credentials are necessary. This function is synchronous and returns only after the home directory was fully activated (or the operation failed), which might take some time. Clients must be prepared for that, and typically should extend the D-Bus method call timeout accordingly. This method is equivalent to the Activate() method on the org.freedesktop.home1.Home interface documented below, but may be called on the manager object and takes a user name as additional argument, instead.

DeactivateHome() deactivates (i.e. unmounts) the home directory of the specified user. It is equivalent to the Deactivate() method on the org.freedesktop.home1.Home interface documented below.

RegisterHome() registers a new home directory locally. It receives the JSON user record as only argument (which typically excludes the "secret" section). Registering a home directory just makes the user record known to the system, it does not create a home directory or such (which is expected to exist already, or created later). This operation is useful to register home directories locally that are not located where systemd-homed.service would find them automatically.

UnregisterHome() unregisters an existing home directory. It takes a user name as argument and undoes what RegisterHome() does. It does not attempt to remove the home directory itself, it just unregisters it with the local system. Note that if the home directory is placed where systemd-homed.service looks for home directories anyway this call will only undo fixation (see below), but the record will remain known to systemd-homed.service and be listed among known records. Since the user record is embedded into the home directory this operation generally does not discard data belonging to the user or their record. This method is equivalent to Unregister() on the org.freedesktop.home1.Home interface.

CreateHome() registers and creates a new home directory. This takes a fully specified JSON user record as argument (including the "secret" section). This registers the user record locally and creates a home directory matching it, depending on the settings specified in the record in combination with local configuration.

RealizeHome() creates a home directory whose user record is already registered locally. This takes a user name plus a user record consisting only of the "secret" section. Invoking RegisterHome() followed by RealizeHome() is mostly equivalent to calling CreateHome(), except that the latter combines the two in atomic fashion. This method is equivalent to Realize() on the org.freedesktop.home1.Home interface.

RemoveHome() unregisters a user record locally, and removes the home directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to Remove() on the org.freedesktop.home1.Home interface.

FixateHome() "fixates" an automatically discovered home directory. systemd-homed.service automatically discovers home directories dropped in our plugged in and adds them to the runtime list of user records it manages. A user record discovered that way may be "fixated", in which case it is copied out of the home directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract additional (typically previously encrypted) user record data from the home directory. A home directory mus be fixated before it can be logged into. This method call takes a user name and a JSON user record consisting only of the "secret" section as argument. This method is equivalent to Fixate() on the org.freedesktop.home1.Home interface.

AuthenticateHome() checks passwords or other authentication credentials associated with the home directory. It takes a user name and a JSON user record consisting only of the "secret" section as argument. Note that many of the other method calls authenticate the user first, in order to execute some other operation. This method call only authenticates and executes no further operation. Like ActivateHome() it is usually first invoked with an empty JSON user record, which is then populated for subsequent tries with additional authentication data supplied. This method is equivalent to Authenticate() on the org.freedesktop.home1.Home interface.

UpdateHome() updates a locally registered user record. Takes a fully specified JSON user record as argument (including the "secret" section). A user with a matching name and realm must be registered locally already, and the last change timestamp of the newly supplied record must be newer than the previously existing user record. Note this operation updates the user record only, it does not propagate passwords/authentication tokens from the user record to the storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then the password of the underlying storage updated using ChangePasswordHome() as well as the storage resized using ResizeHome(). This method is equivalent to Update() on the org.freedesktop.home1.Home interface.

ResizeHome() resizes the storage associated with a user record. Takes a user name, a disk size in bytes and a user record consisting only of the "secret" section as argument. If the size is specified as UINT64_MAX the storage is resized to the size already specified in the user record. Typically, if the user record is updated using UpdateHome() above this is used to propagate the size configured there-in down to the underlying storage back-end. This method is equivalent to Resize() on the org.freedesktop.home1.Home interface.

ChangePasswordHome() changes the passwords/authentication tokens of a home directory. Takes a user name, and two JSON user record objects, each consisting only of the "secret" section, for the old and for the new passwords/authentication tokens. If the user record with the new passwords/authentication token data is specified as empty the existing user record's settings are propagated down to the home directory storage. This is typically used after a user record is updated using UpdateHome() in order to propagate the secrets/authentication tokens down to the storage. This method is equivalent to ChangePassword() on the org.freedesktop.home1.Home interface.

LockHome() temporarily suspends access to a home directory, flushing out any cryptographic keys from memory. This is only supported on some back-ends, and usually done during system suspend, in order to effectively secure home directories while the system is sleeping. Takes a user name as single argument. If an application attempts to access a home directory while it is locked it will typically freeze until the home directory is unlocked again. This method is equivalent to Lock() on the org.freedesktop.home1.Home interface.

UnlockHome() undoes the effect of LockHome(). Takes a user name and a user record consisting only of the "secret" section as arguments. This method is equivalent to Unlock() on the org.freedesktop.home1.Home interface.

AcquireHome() activates or unlocks a home directory in a reference counted mode of operation. Takes a user name and user record consisting only of "secret" section as argument. If the home directory is not active yet, it is activated. If it is currently locked it is unlocked. After completion a reference to the activation/unlocking of the home directory is returned via a file descriptor. When the last client which acquired such a file descriptor closes it the home directory is automatically deactivated again. This method is typically invoked when a user logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home directory can be unmounted automatically again in a robust fashion, when the user logs out. The third argument is a boolean which indicates whether the client invoking the call is able to automatically re-authenticate when the system comes back from suspending. It should be set by all clients that implement a secure lock screen running outside of the user's context, that is brought up when the system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home directory. If a home directory has at least one client with an open reference to the home directory that does not support this it is not suspended automatically at system suspend, otherwise it is. This method is equivalent to Acquire() on the org.freedesktop.home1.Home interface.

RefHome() is similar to AcquireHome() but takes no user record with "secret" section, i.e. will take an additional reference to an already activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the home directory is not already activated. This method is equivalent to Ref() on the org.freedesktop.home1.Home interface.

ReleaseHome() releases a home directory again, if all file descriptors referencing it are already closed, that where acquired through AcquireHome() or RefHome(). Note that this call does not actually cause the deactivation of the home directory (which happens automatically when the last referencing file descriptor is closed), but is simply a synchronization mechanism that allows delaying of the user session's termination until any triggered deactivation is completed. This method is equivalent to Release() on the org.freedesktop.home1.Home interface.

LockAllHomes() locks all active home directories that only have references that opted into automatic suspending during system suspend. This is usually invoked automatically shortly before system suspend.

DeactivateAllHomes() deactivates all home areas that are currently active. This is usually invoked automatically shortly before system shutdown.

### Properties
AutoLogin exposes an array of structures consisting of user name, seat name and object path of an home directory object. All locally managed users that have the "autoLogin" field set are listed here, with the seat name they are associated with. A display manager may watch this property and pre-fill the login screen with the users exposed this way.

## THE HOME OBJECT

```
node /org/freedesktop/home1/home {

  interface org.freedesktop.home1.Home {

    methods:

      Activate(in  s secret);

      Deactivate();

      Unregister();

      Realize(in  s secret);

      Remove();

      Fixate(in  s secret);

      Authenticate(in  s secret);

      Update(in  s user_record);

      Resize(in  t size,

             in  s secret);

      ChangePassword(in  s new_secret,

                     in  s old_secret);

      Lock();

      Unlock(in  s secret);

      Acquire(in  s secret,

              in  b please_suspend,

              out h send_fd);

      Ref(in  b please_suspend,

          out h send_fd);

      Release();

    properties:

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

      readonly s UserName = '...';

      readonly u UID = ...;

      readonly (suusss) UnixRecord = ...;

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

      readonly s State = '...';

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

      readonly (sb) UserRecord = ...;

  };

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

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

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

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

```

### Methods
Activate(), Deactivate(), Unregister(), Realize(), Remove(), Fixate(), Authenticate(), Update(), Resize(), ChangePassword(), Lock(), Unlock(), Acquire(), Ref(), Release() operate like their matching counterparts on the org.freedesktop.home1.Manager interface (see above). The main difference is that they are methods of the home directory objects, and hence carry no additional user name parameter. Which of the two flavors of methods to call depends on the handles to the user known on the client side: if only the user name is known, it's preferable to use the methods on the manager object since they operate with user names only. If however the home object path was already acquired some way it is preferable to operate on the org.freedesktop.home1.Home objects instead.

### Properties
UserName contains the user name of the user account/home directory.

UID contains the numeric UNIX UID of the user account.

UnixRecord contains a structure encapsulating the six fields a struct passwd typically contains (the password field is suppressed).

State exposes the current state home the home directory.

UserRecord contains the full JSON user record string of the user account.

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

## SEE ALSO
systemd(1), systemd-homed.service(8), homectl(1)

## NOTES
1.

JSON User Records

https://systemd.io/USER_RECORD

2.

the usual interface versioning guidelines

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


journal-remote.conf

package: systemd-journal-remote

title: journal-remote.conf(5)

text:
# journal-remote.conf(5)

## NAME
journal-remote.conf, journal-remote.conf.d - Configuration files for the service accepting remote journal uploads

## SYNOPSIS
/etc/systemd/journal-remote.conf

/etc/systemd/journal-remote.conf.d/*.conf

/run/systemd/journal-remote.conf.d/*.conf

/lib/systemd/journal-remote.conf.d/*.conf

## DESCRIPTION
These files configure various parameters of systemd-journal-remote.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 [Remote] section:

Seal=

Periodically sign the data in the journal using Forward Secure Sealing.

SplitMode=

One of "host" or "none".

ServerKeyFile=

SSL key in PEM format.

ServerCertificateFile=

SSL certificate in PEM format.

TrustedCertificateFile=

SSL CA certificate.

## SEE ALSO
systemd-journal-remote.service(8), systemd(1), systemd-journald.service(8)


journal-upload.conf

title: journal-upload.conf(5)

text:
# journal-upload.conf(5)

## NAME
journal-upload.conf, journal-upload.conf.d - Configuration files for the journal upload service

## SYNOPSIS
/etc/systemd/journal-upload.conf

/etc/systemd/journal-upload.conf.d/*.conf

/run/systemd/journal-upload.conf.d/*.conf

/lib/systemd/journal-upload.conf.d/*.conf

## DESCRIPTION
These files configure various parameters of systemd-journal-upload.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 [Upload] section:

URL=

The URL to upload the journal entries to. See the description of --url= option in systemd-journal-upload(8) for the description of possible values. There is no default value, so either this option or the command-line option must be always present to make an upload.

ServerKeyFile=

SSL key in PEM format.

ServerCertificateFile=

SSL CA certificate in PEM format.

TrustedCertificateFile=

SSL CA certificate.

NetworkTimeoutSec=

When network connectivity to the server is lost, this option configures the time to wait for the connectivity to get restored. If the server is not reachable over the network for the configured time, systemd-journal-upload exits. Takes a value in seconds (or in other time units if suffixed with "ms", "min", "h", etc). For details, see systemd.time(5).

## SEE ALSO
systemd-journal-upload.service(8), systemd(1), systemd-journald.service(8)


dnssec-trust-anchors.d

package: systemd-networkd

title: dnssec-trust-anchors.d(5)

summary: DNSSEC trust anchor configuration files

text:
# dnssec-trust-anchors.d(5)

## NAME
dnssec-trust-anchors.d, systemd.positive, systemd.negative - DNSSEC trust anchor configuration files

## SYNOPSIS
/etc/dnssec-trust-anchors.d/*.positive

/run/dnssec-trust-anchors.d/*.positive

/lib/dnssec-trust-anchors.d/*.positive

/etc/dnssec-trust-anchors.d/*.negative

/run/dnssec-trust-anchors.d/*.negative

/lib/dnssec-trust-anchors.d/*.negative

## DESCRIPTION
The DNSSEC trust anchor configuration files define positive and negative trust anchors systemd-resolved.service(8) bases DNSSEC integrity proofs on.

## POSITIVE TRUST ANCHORS
Positive trust anchor configuration files contain DNSKEY and DS resource record definitions to use as base for DNSSEC integrity proofs. See RFC 4035, Section 4.4[1] for more information about DNSSEC trust anchors.

Positive trust anchors are read from files with the suffix .positive located in /etc/dnssec-trust-anchors.d/, /run/dnssec-trust-anchors.d/ and /lib/dnssec-trust-anchors.d/. These directories are searched in the specified order, and a trust anchor file of the same name in an earlier path overrides a trust anchor files in a later path. To disable a trust anchor file shipped in /lib/dnssec-trust-anchors.d/ it is sufficient to provide an identically-named file in /etc/dnssec-trust-anchors.d/ or /run/dnssec-trust-anchors.d/ that is either empty or a symlink to /dev/null ("masked").

Positive trust anchor files are simple text files resembling DNS zone files, as documented in RFC 1035, Section 5[2]. One DS or DNSKEY resource record may be listed per line. Empty lines and lines starting with "#" or ";" are ignored, which may be used for commenting. A <consant>DS</consant> resource record is specified like in the following example:

```
. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5
```

The first word specifies the domain, use "." for the root domain. The domain may be specified with or without trailing dot, which is considered equivalent. The second word must be "IN" the third word "DS". The following words specify the key tag, signature algorithm, digest algorithm, followed by the hex-encoded key fingerprint. See RFC 4034, Section 5[3] for details about the precise syntax and meaning of these fields.

Alternatively, DNSKEY resource records may be used to define trust anchors, like in the following example:

```
. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=
```

The first word specifies the domain again, the second word must be "IN", followed by "DNSKEY". The subsequent words encode the DNSKEY flags, protocol and algorithm fields, followed by the key data encoded in Base64. See RFC 4034, Section 2[4] for details about the precise syntax and meaning of these fields.

If multiple DS or DNSKEY records are defined for the same domain (possibly even in different trust anchor files), all keys are used and are considered equivalent as base for DNSSEC proofs.

Note that systemd-resolved will automatically use a built-in trust anchor key for the Internet root domain if no positive trust anchors are defined for the root domain. In most cases it is hence unnecessary to define an explicit key with trust anchor files. The built-in key is disabled as soon as at least one trust anchor key for the root domain is defined in trust anchor files.

It is generally recommended to encode trust anchors in DS resource records, rather than DNSKEY resource records.

If a trust anchor specified via a DS record is found revoked it is automatically removed from the trust anchor database for the runtime. See RFC 5011[5] for details about revoked trust anchors. Note that systemd-resolved will not update its trust anchor database from DNS servers automatically. Instead, it is recommended to update the resolver software or update the new trust anchor via adding in new trust anchor files.

The current DNSSEC trust anchor for the Internet's root domain is available at the IANA Trust Anchor and Keys[6] page.

## NEGATIVE TRUST ANCHORS
Negative trust anchors define domains where DNSSEC validation shall be turned off. Negative trust anchor files are found at the same location as positive trust anchor files, and follow the same overriding rules. They are text files with the .negative suffix. Empty lines and lines whose first character is ";" are ignored. Each line specifies one domain name which is the root of a DNS subtree where validation shall be disabled. For example:

```
# Reverse IPv4 mappings
10.in-addr.arpa
16.172.in-addr.arpa
168.192.in-addr.arpa
...
# Some custom domains
prod
stag
```

Negative trust anchors are useful to support private DNS subtrees that are not referenced from the Internet DNS hierarchy, and not signed.

RFC 7646[7] for details on negative trust anchors.

If no negative trust anchor files are configured a built-in set of well-known private DNS zone domains is used as negative trust anchors.

It is also possibly to define per-interface negative trust anchors using the DNSSECNegativeTrustAnchors= setting in systemd.network(5) files.

## SEE ALSO
systemd(1), systemd-resolved.service(8), resolved.conf(5), systemd.network(5)

## NOTES
1.

RFC 4035, Section 4.4

https://tools.ietf.org/html/rfc4035#section-4.4

2.

RFC 1035, Section 5

https://tools.ietf.org/html/rfc1035#section-5

3.

RFC 4034, Section 5

https://tools.ietf.org/html/rfc4034#section-5

4.

RFC 4034, Section 2

https://tools.ietf.org/html/rfc4034#section-2

5.

RFC 5011

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

6.

IANA Trust Anchor and Keys

https://data.iana.org/root-anchors/root-anchors.xml

7.

RFC 7646

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


networkd.conf

title: networkd.conf(5)

summary: Global Network configuration files

text:
# networkd.conf(5)

## NAME
networkd.conf, networkd.conf.d - Global Network configuration files

## SYNOPSIS
/etc/systemd/networkd.conf

/etc/systemd/networkd.conf.d/*.conf

/lib/systemd/networkd.conf.d/*.conf

## DESCRIPTION
These configuration files control global network parameters. Currently the DHCP Unique Identifier (DUID).

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

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

SpeedMeter=

Takes a boolean. If set to yes, then systemd-networkd measures the traffic of each interface, and networkctl status INTERFACE shows the measured speed. Defaults to no.

SpeedMeterIntervalSec=

Specifies the time interval to calculate the traffic speed of each interface. If SpeedMeter=no, the value is ignored. Defaults to 10sec.

ManageForeignRoutingPolicyRules=

A boolean. When true, systemd-networkd will remove rules that are not configured in .network files (except for rules with protocol "kernel"). When false, it will not remove any foreign rules, keeping them even if they are not configured in a .network file. Defaults to yes.

ManageForeignRoutes=

A boolean. When true, systemd-networkd will remove routes that are not configured in .network files (except for routes with protocol "kernel", "dhcp" when KeepConfiguration= is true or "dhcp", and "static" when KeepConfiguration= is true or "static"). When false, it will not remove any foreign routes, keeping them even if they are not configured in a .network file. Defaults to yes.

RouteTable=

Defines the route table name. Takes a whitespace-separated list of the pairs of route table name and number. The route table name and number in each pair are separated with a colon, i.e., "name:number". The route table name must not be "default", "main", or "local", as these route table names are predefined with route table number 253, 254, and 255, respectively. The route table number must be an integer in the range 1...4294967295. This setting can be specified multiple times. If an empty string is specified, then the list specified earlier are cleared. Defaults to unset.

## [DHCPV4] SECTION OPTIONS
This section configures the DHCP Unique Identifier (DUID) value used by DHCP protocol. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring a dynamic IPv4 address if ClientIdentifier=duid. IAID and DUID allows a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP address. To configure IAID and ClientIdentifier, see systemd.network(5).

The following options are understood:

DUIDType=

Specifies how the DUID should be generated. See RFC 3315[1] for a description of all the options. The following values are understood:

vendor

If "DUIDType=vendor", then the DUID value will be generated using "43793" as the vendor identifier (systemd) and hashed contents of machine-id(5). This is the default if DUIDType= is not specified.

uuid

If "DUIDType=uuid", and DUIDRawData= is not set, then the product UUID is used as a DUID value. If a system does not have valid product UUID, then an application-specific machine-id(5) is used as a DUID value. About the application-specific machine ID, see sd_id128_get_machine_app_specific(3).

link-layer-time[:TIME], link-layer

If "link-layer-time" or "link-layer" is specified, then the MAC address of the interface is used as a DUID value. The value "link-layer-time" can take additional time value after a colon, e.g. "link-layer-time:2018-01-23 12:34:56 UTC". The default time value is "2000-01-01 00:00:00 UTC".

In all cases, DUIDRawData= can be used to override the actual DUID value that is used.

DUIDRawData=

Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each byte separated by ":". The DUID that is sent is composed of the DUID type specified by DUIDType= and the value configured here. The DUID value specified here overrides the DUID that systemd-networkd.service(8) generates from the machine ID. To configure DUID per-network, see systemd.network(5). The configured DHCP DUID should conform to the specification in RFC 3315[2], RFC 6355[3]. To configure IAID, see systemd.network(5).

Example 1. A DUIDType=vendor with a custom value

```
DUIDType=vendor
DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00
```

This specifies a 14 byte DUID, with the type DUID-EN ("00:02"), enterprise number 43793 ("00:00:ab:11"), and identifier value "f9:2a:c2:77:29:f9:5c:00".

## [DHCPV6] SECTION OPTIONS
This section configures the DHCP Unique Identifier (DUID) value used by DHCPv6 protocol. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface Identity Association Identifier (IAID) to a DHCPv6 server when acquiring a dynamic IPv6 address. IAID and DUID allows a DHCPv6 server to uniquely identify the machine and the interface requesting a DHCP IP address. To configure IAID, see systemd.network(5).

The following options are understood:

DUIDType=, DUIDRawData=

As in the [DHCPv4] section.

## SEE ALSO
systemd(1), systemd.network(5), systemd-networkd.service(8), machine-id(5), sd_id128_get_machine_app_specific(3)

## NOTES
1.

RFC 3315

https://tools.ietf.org/html/rfc3315#section-9

2.

RFC 3315

http://tools.ietf.org/html/rfc3315#section-9

3.

RFC 6355

http://tools.ietf.org/html/rfc6355


title: org.freedesktop.resolve1(5)

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

text:
# org.freedesktop.resolve1(5)

## NAME
org.freedesktop.resolve1 - The D-Bus interface of systemd-resolved

## INTRODUCTION
systemd-resolved.service(8) is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS. It also does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface.

This page contains an API reference only. If you are looking for a longer explanation how to use this API, please consult Writing Network Configuration Managers[1] and Writing Resolver Clients[2].

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/resolve1 {

  interface org.freedesktop.resolve1.Manager {

    methods:

      ResolveHostname(in  i ifindex,

                      in  s name,

                      in  i family,

                      in  t flags,

                      out a(iiay) addresses,

                      out s canonical,

                      out t flags);

      ResolveAddress(in  i ifindex,

                     in  i family,

                     in  ay address,

                     in  t flags,

                     out a(is) names,

                     out t flags);

      ResolveRecord(in  i ifindex,

                    in  s name,

                    in  q class,

                    in  q type,

                    in  t flags,

                    out a(iqqay) records,

                    out t flags);

      ResolveService(in  i ifindex,

                     in  s name,

                     in  s type,

                     in  s domain,

                     in  i family,

                     in  t flags,

                     out a(qqqsa(iiay)s) srv_data,

                     out aay txt_data,

                     out s canonical_name,

                     out s canonical_type,

                     out s canonical_domain,

                     out t flags);

      GetLink(in  i ifindex,

              out o path);

      SetLinkDNS(in  i ifindex,

                 in  a(iay) addresses);

      SetLinkDNSEx(in  i ifindex,

                   in  a(iayqs) addresses);

      SetLinkDomains(in  i ifindex,

                     in  a(sb) domains);

      SetLinkDefaultRoute(in  i ifindex,

                          in  b enable);

      SetLinkLLMNR(in  i ifindex,

                   in  s mode);

      SetLinkMulticastDNS(in  i ifindex,

                          in  s mode);

      SetLinkDNSOverTLS(in  i ifindex,

                        in  s mode);

      SetLinkDNSSEC(in  i ifindex,

                    in  s mode);

      SetLinkDNSSECNegativeTrustAnchors(in  i ifindex,

                                        in  as names);

      RevertLink(in  i ifindex);

      RegisterService(in  s name,

                      in  s name_template,

                      in  s type,

                      in  q service_port,

                      in  q service_priority,

                      in  q service_weight,

                      in  aa{say} txt_datas,

                      out o service_path);

      UnregisterService(in  o service_path);

      ResetStatistics();

      FlushCaches();

      ResetServerFeatures();

    properties:

      readonly s LLMNRHostname = '...';

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

      readonly s LLMNR = '...';

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

      readonly s MulticastDNS = '...';

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

      readonly s DNSOverTLS = '...';

      readonly a(iiay) DNS = [...];

      readonly a(iiayqs) DNSEx = [...];

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

      readonly a(iiay) FallbackDNS = [...];

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

      readonly a(iiayqs) FallbackDNSEx = [...];

      readonly (iiay) CurrentDNSServer = ...;

      readonly (iiayqs) CurrentDNSServerEx = ...;

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

      readonly a(isb) Domains = [...];

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

      readonly (tt) TransactionStatistics = ...;

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

      readonly (ttt) CacheStatistics = ...;

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

      readonly s DNSSEC = '...';

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

      readonly (tttt) DNSSECStatistics = ...;

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

      readonly b DNSSECSupported = ...;

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

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

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

      readonly s DNSStubListener = '...';

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

      readonly s ResolvConfMode = '...';

  };

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

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

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

```

### Methods
ResolveHostname() takes a hostname and resolves it to one or more IP addresses. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be done on any suitable interface. The name parameter specifies the hostname to resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The family parameter limits the results to a specific address family. It may be AF_INET, AF_INET6 or AF_UNSPEC. If AF_UNSPEC is specified (recommended), both kinds are retrieved, subject to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is retrieved; and similarly for IPv4). A 64-bit flags field may be used to alter the behaviour of the resolver operation (see below). The method returns an array of address records. Each address record consists of the interface index the address belongs to, an address family as well as a byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address family). The returned address family will be one of AF_INET or AF_INET6. For IPv6, the returned address interface index should be used to initialize the .sin6_scope_id field of a struct sockaddr_in6 instance to permit support for resolution to link-local IP addresses. The address array is followed by the canonical name of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit flags field is returned that is defined similarly to the flags field that was passed in, but contains information about the resolved data (see below). If the hostname passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In this case, no network communication is done.

ResolveAddress() executes the reverse operation: it takes an IP address and acquires one or more hostnames for it. As parameters it takes the interface index to execute the query on, or 0 if all suitable interfaces are OK. The family parameter indicates the address family of the IP address to resolve. It may be either AF_INET or AF_INET6. The address parameter takes the raw IP address data (as either a 4 or 16 byte array). The flags input parameter may be used to alter the resolver operation (see below). The method returns an array of name records, each consisting of an interface index and a hostname. The flags output field contains additional information about the resolver operation (see below).

ResolveRecord() takes a DNS resource record (RR) type, class and name, and retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the Linux network interface index to execute the query on, or 0 if it may be done on any suitable interface. The name parameter specifies the RR domain name to look up (no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be ANY). Finally, a flags field may be passed in to alter behaviour of the look-up (see below). On completion, an array of RR items is returned. Each array entry consists of the network interface index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed by the RR type, class, TTL and RDATA, in the binary format documented in RFC 1035[3]. For RRs that support name compression in the payload (such as MX or PTR), the compression is expanded in the returned data.

Note that currently, the class field has to be specified as IN or ANY. Specifying a different class will return an error indicating that look-ups of this kind are unsupported. Similarly, some special types are not supported either (AXFR, OPT, ...). While systemd-resolved parses and validates resource records of many types, it is crucial that clients using this API understand that the RR data originates from the network and should be thoroughly validated before use.

ResolveService() may be used to resolve a DNS SRV service record, as well as the hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional service metadata. The primary benefit of using this method over ResolveRecord() specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced in the SRV in a single operation. As parameters it takes a Linux network interface index, a service name, a service type and a service domain. This method may be invoked in three different modes:

1.To resolve a DNS-SD service, specify the service name (e.g. "Lennart's Files"), the service type (e.g. "_webdav._tcp") and the domain to search in (e.g. "local") as the three service parameters. The service name must be in UTF-8 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD specifications). However, if necessary, IDNA conversion is applied to the domain parameter.

2.To resolve a plain SRV record, set the service name parameter to the empty string and set the service type and domain properly. (IDNA conversion is applied to the domain, if necessary.)

3.Alternatively, leave both the service name and type empty and specify the full domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA conversion is applied in this mode.)

The family parameter of the ResolveService() method encodes the desired family of the addresses to resolve (use AF_INET, AF_INET6, or AF_UNSPEC). If this is enabled (Use the NO_ADDRESS flag to turn address resolution off, see below). The flags parameter takes a couple of flags that may be used to alter the resolver operation.

On completion, ResolveService() returns an array of SRV record structures. Each items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV record. Immediately following is an array of the addresses of this hostname, with each item consisting of the interface index, the address family and the address data in a byte array. This address array is followed by the canonicalized hostname. After this array of SRV record structures an array of byte arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters are the canonical service name, type and domain. This may or may not be identical to the parameters passed in. Finally, a flags field is returned that contains information about the resolver operation performed.

The ResetStatistics() method resets the various statistics counters that systemd-resolved maintains to zero. (For details, see the statistics properties below.)

The GetLink() method takes a network interface index and returns the object path to the org.freedesktop.resolve1.Link object corresponding to it.

The SetLinkDNS() method sets the DNS servers to use on a specific interface. This method (and the following ones) may be used by network management software to configure per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP address records. Each array item consists of an address family (either AF_INET or AF_INET6), followed by a 4-byte or 16-byte array with the raw address data. This method is a one-step shortcut for retrieving the Link object for a network interface using GetLink() (see above) and then invoking the SetDNS() method (see below) on it.

SetLinkDNSEx() is similar to SetLinkDNS(), but allows an IP port (instead of the default 53) and DNS name to be specified for each DNS server. The server name is used for Server Name Indication (SNI), which is useful when DNS-over-TLS is used. C.f. DNS= in resolved.conf(5).

SetLinkDefaultRoute() specifies whether the link shall be used as the default route for name queries. See the description of name routing in systemd-resolved.service(8) for details.

The SetLinkDomains() method sets the search and routing domains to use on a specific network interface for DNS look-ups. It takes a network interface index and an array of domains, each with a boolean parameter indicating whether the specified domain shall be used as a search domain (false), or just as a routing domain (true). Search domains are used for qualifying single-label names into FQDN when looking up hostnames, as well as for making routing decisions on which interface to send queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label name qualification. Pass the search domains in the order they should be used.

The SetLinkLLMNR() method enables or disables LLMNR support on a specific network interface. It takes a network interface index as well as a string that may either be empty or one of "yes", "no" or "resolve". If empty, the systemd-wide default LLMNR setting is used. If "yes", LLMNR is used for resolution of single-label names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If "no", LLMNR is turned off fully on this interface. If "resolve", LLMNR is only enabled for resolving names, but the local hostname is not registered for other peers to use.

Similarly, the SetLinkMulticastDNS() method enables or disables MulticastDNS support on a specific interface. It takes the same parameters as SetLinkLLMNR() described above.

The SetLinkDNSSEC() method enables or disables DNSSEC validation on a specific network interface. It takes a network interface index as well as a string that may either be empty or one of "yes", "no", or "allow-downgrade". When empty, the system-wide default DNSSEC setting is used. If "yes", full DNSSEC validation is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this mode is used. If "no", DNSSEC validation is fully disabled. If "allow-downgrade", DNSSEC validation is enabled, but is turned off automatically if the selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC only applies to traditional DNS, not to LLMNR or MulticastDNS.

The SetLinkDNSSECNegativeTrustAnchors() method may be used to configure DNSSEC Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a list of domains as arguments.

The SetLinkDNSOverTLS() method enables or disables DNS-over-TLS. C.f. DNSOverTLS= in systemd-resolved.service(8) for details.

Network management software integrating with systemd-resolved should call SetLinkDNS() or SetLinkDNSEx(), SetLinkDefaultRoute(), SetLinkDomains() and others after the interface appeared in the kernel (and thus after a network interface index has been assigned), but before the network interfaces is activated (IFF_UP set) so that all settings take effect during the full time the network interface is up. It is safe to alter settings while the interface is up, however. Use RevertLink() (described below) to reset all per-interface settings.

The RevertLink() method may be used to revert all per-link settings described above to the defaults.

The Flags Parameter

The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient and recommended. However, the following flags are defined to alter the look-up:

```
#define SD_RESOLVED_DNS               (UINT64_C(1) <<  0)
#define SD_RESOLVED_LLMNR_IPV4        (UINT64_C(1) <<  1)
#define SD_RESOLVED_LLMNR_IPV6        (UINT64_C(1) <<  2)
#define SD_RESOLVED_MDNS_IPV4         (UINT64_C(1) <<  3)
#define SD_RESOLVED_MDNS_IPV6         (UINT64_C(1) <<  4)
#define SD_RESOLVED_NO_CNAME          (UINT64_C(1) <<  5)
#define SD_RESOLVED_NO_TXT            (UINT64_C(1) <<  6)
#define SD_RESOLVED_NO_ADDRESS        (UINT64_C(1) <<  7)
#define SD_RESOLVED_NO_SEARCH         (UINT64_C(1) <<  8)
#define SD_RESOLVED_AUTHENTICATED     (UINT64_C(1) <<  9)
#define SD_RESOLVED_NO_VALIDATE       (UINT64_C(1) << 10)
#define SD_RESOLVED_NO_SYNTHESIZE     (UINT64_C(1) << 11)
#define SD_RESOLVED_NO_CACHE          (UINT64_C(1) << 12)
#define SD_RESOLVED_NO_ZONE           (UINT64_C(1) << 13)
#define SD_RESOLVED_NO_TRUST_ANCHOR   (UINT64_C(1) << 14)
#define SD_RESOLVED_NO_NETWORK        (UINT64_C(1) << 15)
#define SD_RESOLVED_REQUIRE_PRIMARY   (UINT64_C(1) << 16)
#define SD_RESOLVED_CLAMP_TTL         (UINT64_C(1) << 17)
#define SD_RESOLVED_CONFIDENTIAL      (UINT64_C(1) << 18)
#define SD_RESOLVED_SYNTHETIC         (UINT64_C(1) << 19)
#define SD_RESOLVED_FROM_CACHE        (UINT64_C(1) << 20)
#define SD_RESOLVED_FROM_ZONE         (UINT64_C(1) << 21)
#define SD_RESOLVED_FROM_TRUST_ANCHOR (UINT64_C(1) << 22)
#define SD_RESOLVED_FROM_NETWORK      (UINT64_C(1) << 23)

```

On input, the first five flags control the protocols to use for the look-up. They refer to classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the look-up will be done via all suitable protocols for the specific look-up. Note that these flags operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, systemd-resolved will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces suitable for multicast.

On output, these five flags indicate which protocol was used to execute the operation, and hence where the data was found.

The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was used to discover the first DNS result.

The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the look-up. This flag is only available at input, none of the functions will return it on output. If a CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default, when the flag is off, CNAME/DNAME RRs are followed.

The NO_TXT and NO_ADDRESS flags only influence operation of the ResolveService() method. They are only defined for input, not output. If NO_TXT is set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is set, the discovered hostnames are not implicitly translated to their addresses.

The NO_SEARCH flag turns off the search domain logic. It is only defined for input in ResolveHostname(). When specified, single-label hostnames are not qualified using defined search domains, if any are configured. Note that ResolveRecord() will never qualify single-label domain names using search domains. Also note that multi-label hostnames are never subject to search list expansion.

The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data for which a full trust chain may be established to a trusted domain anchor. It is also set for locally synthesized data, such as "localhost" or data from /etc/hosts. Moreover, it is set for all LLMNR or mDNS RRs which originate from the local host. Applications that require authenticated RR data for operation should check this flag before trusting the data. Note that systemd-resolved will never return invalidated data, hence this flag simply allows to discern the cases where data is known to be trusted, or where there is proof that the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server does not support authenticating data).

NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be used.

The next four flags allow disabling certain sources during resolution. NO_SYNTHESIZE disables synthetic records, e.g. the local host name, see section SYNTHETIC RECORDS in systemd-resolved.service(8) for more information. NO_CACHE disables the use of the cache of previously resolved records. NO_ZONE disables answers using locally registered public LLMNR/mDNS resource records. NO_TRUST_ANCHOR disables answers using locally configured trust anchors. NO_NETWORK requires all answers to be provided without using the network, i.e. either from local sources or the cache.

With REQUIRE_PRIMARY the request must be answered from a "primary" answer, i.e. not from resource records acquired as a side-effect of a previous transaction.

With CLAMP_TTL, if reply is answered from cache, the TTLs will be adjusted by age of cache entry.

The next six bits flags are used in output and provide information about the source of the answer. CONFIDENTIAL means the query was resolved via encrypted channels or never left this system. FROM_SYNTHETIC means the query was (at least partially) synthesized. FROM_CACHE means the query was answered (at least partially) using the cache. FROM_ZONE means the query was answered (at least partially) using LLMNR/mDNS. FROM_TRUST_ANCHOR means the query was answered (at least partially) using local trust anchors. FROM_NETWORK means the query was answered (at least partially) using the network.

### Properties
The LLMNR and MulticastDNS properties report whether LLMNR and MulticastDNS are (globally) enabled. Each may be one of "yes", "no", and "resolve". See SetLinkLLMNR() and SetLinkMulticastDNS() above.

LLMNRHostname contains the hostname currently exposed on the network via LLMNR. It usually follows the system hostname as may be queried via gethostname(3), but may differ if a conflict is detected on the network.

DNS and DNSEx contain arrays of all DNS servers currently used by systemd-resolved. DNS contains information similar to the DNS server data in /run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface index, an address family, and a byte array containing the DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6). DNSEx is similar, but additionally contains the IP port and server name (used for Server Name Indication, SNI). Both arrays contain DNS servers configured system-wide, including those possibly read from a foreign /etc/resolv.conf or the DNS= setting in /etc/systemd/resolved.conf, as well as per-interface DNS server information either retrieved from systemd-networkd(8), or configured by external software via SetLinkDNS() or SetLinkDNSEx() (see above). The network interface index will be 0 for the system-wide configured services and non-zero for the per-link servers.

FallbackDNS and FallbackDNSEx contain arrays of all DNS servers configured as fallback servers, if any, using the same format as DNS and DNSEx described above. See the description of FallbackDNS= in resolved.conf(5) for the description of when those servers are used.

CurrentDNSServer and CurrentDNSServerEx specify the server that is currently used for query resolution, in the same format as a single entry in the DNS and DNSEx arrays described above.

Similarly, the Domains property contains an array of all search and routing domains currently used by systemd-resolved. Each entry consists of a network interface index (again, 0 encodes system-wide entries), the actual domain name, and whether the entry is used only for routing (true) or for both routing and searching (false).

The TransactionStatistics property contains information about the number of transactions systemd-resolved has processed. It contains a pair of unsigned 64-bit counters, the first containing the number of currently ongoing transactions, the second the number of total transactions systemd-resolved is processing or has processed. The latter value may be reset using the ResetStatistics() method described above. Note that the number of transactions does not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC are in use.

The CacheStatistics property contains information about the executed cache operations so far. It exposes three 64-bit counters: the first being the total number of current cache entries (both positive and negative), the second the number of cache hits, and the third the number of cache misses. The latter counters may be reset using ResetStatistics() (see above).

The DNSSEC property specifies current status of DNSSEC validation. It is one of "yes" (validation is enforced), "no" (no validation is done), "allow-downgrade" (validation is done if the current DNS server supports it). See the description of DNSSEC= in resolved.conf(5).

The DNSSECStatistics property contains information about the DNSSEC validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus, and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and each non-existance proof. The secure counter is increased for each operation that successfully verified a signed reply, the insecure counter is increased for each operation that successfully verified that an unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the validation did not check out and the data is likely to have been tempered with. Finally the indeterminate counter is increased for each operation which did not complete because the necessary keys could not be acquired or the cryptographic algorithms were unknown.

The DNSSECSupported boolean property reports whether DNSSEC is enabled and the selected DNS servers support it. It combines information about system-wide and per-link DNS settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for which DNS is configured and for the system-wide settings if there are any. Note that systemd-resolved assumes DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported value may initially be true, until the first transactions are executed.

The DNSOverTLS boolean property reports whether DNS-over-TLS is enabled.

The ResolvConfMode property exposes how /etc/resolv.conf is managed on the host. Currently, the values "uplink", "stub", "static" (these three correspond to the three different files systemd-resolved.service provides), "foreign" (the file is managed by admin or another service, systemd-resolved.service just consumes it), "missing" (/etc/resolv.conf is missing).

The DNSStubListener property reports whether the stub listener on port 53 is enabled. Possible values are "yes" (enabled), "no" (disabled), "udp" (only the UDP listener is enabled), and "tcp" (only the TCP listener is enabled).

## LINK OBJECT

```
node /org/freedesktop/resolve1/link/_1 {

  interface org.freedesktop.resolve1.Link {

    methods:

      SetDNS(in  a(iay) addresses);

      SetDNSEx(in  a(iayqs) addresses);

      SetDomains(in  a(sb) domains);

      SetDefaultRoute(in  b enable);

      SetLLMNR(in  s mode);

      SetMulticastDNS(in  s mode);

      SetDNSOverTLS(in  s mode);

      SetDNSSEC(in  s mode);

      SetDNSSECNegativeTrustAnchors(in  as names);

      Revert();

    properties:

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

      readonly t ScopesMask = ...;

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

      readonly a(iay) DNS = [...];

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

      readonly a(iayqs) DNSEx = [...];

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

      readonly (iay) CurrentDNSServer = ...;

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

      readonly (iayqs) CurrentDNSServerEx = ...;

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

      readonly a(sb) Domains = [...];

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

      readonly b DefaultRoute = ...;

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

      readonly s LLMNR = '...';

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

      readonly s MulticastDNS = '...';

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

      readonly s DNSOverTLS = '...';

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

      readonly s DNSSEC = '...';

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

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

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

      readonly b DNSSECSupported = ...;

  };

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

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

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

```

For each Linux network interface a "Link" object is created which exposes per-link DNS configuration and state. Use GetLink() on the Manager interface to retrieve the object path for a link object given the network interface index (see above).

### Methods
The various methods exposed by the Link interface are equivalent to their similarly named counterparts on the Manager interface. e.g. SetDNS() on the Link object maps to SetLinkDNS() on the Manager object, the main difference being that the later expects an interface index to be specified. Invoking the methods on the Manager interface has the benefit of reducing roundtrips, as it is not necessary to first request the Link object path via GetLink() before invoking the methods. The same relationship holds for SetDNSEx(), SetDomains(), SetDefaultRoute(), SetLLMNR(), SetMulticastDNS(), SetDNSOverTLS(), SetDNSSEC(), SetDNSSECNegativeTrustAnchors(), and Revert(). For further details on these methods see the Manager documentation above.

### Properties
ScopesMask defines which resolver scopes are currently active on this interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured* to be used on the interface, the former expose what is actually used on the interface, taking into account the abilities of the interface.

DNSSECSupported exposes a boolean field that indicates whether DNSSEC is currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is assumed available until it is detected that the configured server does not actually support it. Thus, this property may initially report that DNSSEC is supported on an interface.

DefaultRoute exposes a boolean field that indicates whether the interface will be used as default route for name queries. See SetLinkDefaultRoute() above.

The other properties reflect the state of the various configuration settings for the link which may be set with the various methods calls such as SetDNS() or SetLLMNR().

## COMMON ERRORS
Many bus methods systemd-resolved exposes (in particular the resolver methods such as ResolveHostname() on the Manager interface) may return some of the following errors:

org.freedesktop.resolve1.NoNameServers

No suitable DNS servers were found to resolve a request.

org.freedesktop.resolve1.InvalidReply

A response from the selected DNS server was not understood.

org.freedesktop.resolve1.NoSuchRR

The requested name exists, but there is no resource record of the requested type for it. (This is the DNS NODATA case).

org.freedesktop.resolve1.CNameLoop

The look-up failed because a CNAME or DNAME loop was detected.

org.freedesktop.resolve1.Aborted

The look-up was aborted because the selected protocol became unavailable while the operation was ongoing.

org.freedesktop.resolve1.NoSuchService

A service look-up was successful, but the SRV record reported that the service is not available.

org.freedesktop.resolve1.DnssecFailed

The acquired response did not pass DNSSEC validation.

org.freedesktop.resolve1.NoTrustAnchor

No chain of trust could be established for the response to a configured DNSSEC trust anchor.

org.freedesktop.resolve1.ResourceRecordTypeUnsupported

The requested resource record type is not supported on the selected DNS servers. This error is generated for example when an RRSIG record is requested from a DNS server that does not support DNSSEC.

org.freedesktop.resolve1.NoSuchLink

No network interface with the specified network interface index exists.

org.freedesktop.resolve1.LinkBusy

The requested configuration change could not be made because systemd-networkd(8), already took possession of the interface and supplied configuration data for it.

org.freedesktop.resolve1.NetworkDown

The requested look-up failed because the system is currently not connected to any suitable network.

org.freedesktop.resolve1.DnsError.NXDOMAIN, org.freedesktop.resolve1.DnsError.REFUSED, ...

The look-up failed with a DNS return code reporting a failure. The error names used as suffixes here are defined in by IANA in DNS RCODEs[4].

## EXAMPLES
Example 1. Introspect org.freedesktop.resolve1.Manager on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.resolve1 \

  --object-path /org/freedesktop/resolve1

```

Example 2. Introspect org.freedesktop.resolve1.Link on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.resolve1 \

  --object-path /org/freedesktop/resolve1/link/_11

```

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

## NOTES
1.

Writing Network Configuration Managers

https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers

2.

Writing Resolver Clients

https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients

3.

RFC 1035

https://www.ietf.org/rfc/rfc1035.txt

4.

DNS RCODEs

https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6

5.

the usual interface versioning guidelines

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