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

/run/systemd/journal-upload.conf

/usr/lib/systemd/journal-upload.conf

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

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

/usr/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. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [1], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

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

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

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

## OPTIONS
All options are configured in the [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. Added in version 232.

ServerKeyFile=

SSL key in PEM format. Added in version 232.

ServerCertificateFile=

SSL CA certificate in PEM format. Added in version 232.

TrustedCertificateFile=

SSL CA certificate. Added in version 232.

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(7). Added in version 249.

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

## NOTES
1.

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


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

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

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

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

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

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

/usr/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 /usr/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 /usr/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 DS 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

/run/systemd/networkd.conf

/usr/local/lib/systemd/networkd.conf

/usr/lib/systemd/networkd.conf

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

/run/systemd/networkd.conf.d/*.conf

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

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

## DESCRIPTION
These configuration files control global network parameters.

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

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

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

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

## [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. Added in version 244.

SpeedMeterIntervalSec=

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

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. Added in version 249.

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. Added in version 246.

ManageForeignNextHops=

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

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, except for predefined numbers 253, 254, and 255. This setting can be specified multiple times. If an empty string is specified, then the list specified earlier are cleared. Defaults to unset. Added in version 248.

IPv4Forwarding=

Configures IPv4 packet forwarding for the system. Takes a boolean value. This controls the net.ipv4.conf.default.forwarding and net.ipv4.conf.all.forwarding sysctl options. See IP Sysctl[2] for more details about the sysctl options. Defaults to unset and the sysctl options will not be changed. If an interface is configured with a .network file that enables IPMasquerade= for IPv4 (that is, "ipv4" or "both"), this setting is implied unless explicitly specified. See IPMasquerade= in systemd.network(5) for more details.

Added in version 256.

IPv6Forwarding=

Configures IPv6 packet forwarding for the system. Takes a boolean value. This controls the net.ipv6.conf.default.forwarding and net.ipv6.conf.all.forwarding sysctl options. See IP Sysctl[2] for more details about the sysctl options. Defaults to unset and the sysctl options will not be changed. If an interface is configured with a .network file that enables IPMasquerade= for IPv6 (that is, "ipv6" or "both"), this setting is implied unless explicitly specified. See IPMasquerade= in systemd.network(5) for more details.

Added in version 256.

IPv6PrivacyExtensions=

Specifies the default value for per-network IPv6PrivacyExtensions=. Takes a boolean or the special values "prefer-public" and "kernel". See for details in systemd.network(5). Defaults to "no". Added in version 254.

UseDomains=

Specifies the network- and protocol-independent default value for the same settings in [IPv6AcceptRA], [DHCPv4], and [DHCPv6] sections below. Takes a boolean, or the special value route. See the same setting in systemd.network(5). Defaults to "no". Added in version 256.

## [IPV6ACCEPTRA] SECTION OPTIONS
This section configures the default setting of the Neighbor Discovery. The following options are available in the [IPv6AcceptRA] section:

UseDomains=

Specifies the network-independent default value for the same setting in the [IPv6AcceptRA] section in systemd.network(5). Takes a boolean, or the special value route. When unspecified, the value specified in the [Network] section in networkd.conf(5), which defaults to "no", will be used. Added in version 256.

## [IPV6ADDRESSLABEL] SECTION OPTIONS
An [IPv6AddressLabel] section accepts the following keys. Specify multiple [IPv6AddressLabel] sections to configure multiple address labels. IPv6 address labels are used for address selection. See RFC 3484[3]. Precedence is managed by userspace, and only the label itself is stored in the kernel.

Label=

The label for the prefix, an unsigned integer in the range 0...4294967294. 0xffffffff is reserved. This setting is mandatory. Added in version 257.

Prefix=

IPv6 prefix is an address with a prefix length, separated by a slash "/" character. This setting is mandatory. Added in version 257.

## [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[4] for a description of all the options. This takes an integer in the range 0...65535, or one of the following string values:

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. Added in version 230.

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). Added in version 230.

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". Added in version 240.

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

Added in version 230.

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[5], RFC 6355[6]. 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".

Added in version 230.

UseDomains=

Same as the one in the [IPv6AcceptRA] section, but applied for DHCPv4 protocol. Added in version 256.

## [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. Added in version 249.

UseDomains=

As in the [DHCPv4] section. Added in version 256.

## [DHCPSERVER] SECTION OPTIONS
This section configures the default setting of the DHCP server. The following options are available in the [DHCPServer] section:

PersistLeases=

Specifies the default value for per-network PersistLeases=. Takes a boolean. See for details in systemd.network(5). Defaults to "yes". Added in version 256.

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

## NOTES
1.

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

2.

IP Sysctl

https://docs.kernel.org/networking/ip-sysctl.html

3.

RFC 3484

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

4.

RFC 3315

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

5.

RFC 3315

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

6.

RFC 6355

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


title: org.freedesktop.network1(5)

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

text:
# org.freedesktop.network1(5)

## NAME
org.freedesktop.network1 - The D-Bus interface of systemd-networkd

## INTRODUCTION
systemd-networkd.service(8) is a system service that manages and configures network interfaces. 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/network1 {

  interface org.freedesktop.network1.Manager {

    methods:

      ListLinks(out a(iso) links);

      GetLinkByName(in  s name,

                    out i ifindex,

                    out o path);

      GetLinkByIndex(in  i ifindex,

                     out s name,

                     out o path);

      SetLinkNTP(in  i ifindex,

                 in  as servers);

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

      RevertLinkNTP(in  i ifindex);

      RevertLinkDNS(in  i ifindex);

      RenewLink(in  i ifindex);

      ForceRenewLink(in  i ifindex);

      ReconfigureLink(in  i ifindex);

      Reload();

      DescribeLink(in  i ifindex,

                   out s json);

      Describe(out s json);

    properties:

      readonly s OperationalState = '...';

      readonly s CarrierState = '...';

      readonly s AddressState = '...';

      readonly s IPv4AddressState = '...';

      readonly s IPv6AddressState = '...';

      readonly s OnlineState = '...';

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

      readonly t NamespaceId = ...;

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

      readonly u NamespaceNSID = ...;

  };

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

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

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

Provides information about the manager.

### Properties
NamespaceId contains the inode number of the network namespace that the network service runs in. A client may compare this with the inode number of its own network namespace to verify whether the service manages the same network namespace.

NamespaceNSID contains the "nsid" identifier the kernel maintains for the network namespace, if there's one assigned.

## LINK OBJECT

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

  interface org.freedesktop.network1.Link {

    methods:

      SetNTP(in  as servers);

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

      RevertNTP();

      RevertDNS();

      Renew();

      ForceRenew();

      Reconfigure();

      Describe(out s json);

    properties:

      readonly s OperationalState = '...';

      readonly s CarrierState = '...';

      readonly s AddressState = '...';

      readonly s IPv4AddressState = '...';

      readonly s IPv6AddressState = '...';

      readonly s OnlineState = '...';

      readonly s AdministrativeState = '...';

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

      readonly (tt) BitRates = ...;

  };

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

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

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

Provides information about interfaces.

## NETWORK OBJECT

```
node /org/freedesktop/network1/network/_1 {

  interface org.freedesktop.network1.Network {

    properties:

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

      readonly s Description = '...';

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

      readonly s SourcePath = '...';

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

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

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

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

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

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

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

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

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

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

  };

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

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

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

Provides information about .network files.

## DHCP SERVER OBJECT

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

  interface org.freedesktop.network1.DHCPServer {

    properties:

      readonly a(uayayayayt) Leases = [...];

  };

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

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

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

  interface org.freedesktop.network1.Link { ... };
};
```

Provides information about leases.

## DHCPV4 CLIENT OBJECT

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

  interface org.freedesktop.network1.DHCPv4Client {

    properties:

      readonly s State = '...';

  };

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

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

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

  interface org.freedesktop.network1.Link { ... };
};
```

Provides information about DHCPv4 client status.

## DHCPV6 CLIENT OBJECT

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

  interface org.freedesktop.network1.DHCPv6Client {

    properties:

      readonly s State = '...';

  };

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

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

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

  interface org.freedesktop.network1.Link { ... };
};
```

Provides information about DHCPv6 client status.

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

```
$ gdbus introspect --system \

  --dest org.freedesktop.network1 \

  --object-path /org/freedesktop/network1
```

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

```
$ gdbus introspect --system \

  --dest org.freedesktop.network1 \

  --object-path /org/freedesktop/network1/link/_11
```

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

## HISTORY

### DHCPv4 Client Object
State was added in version 255.

### DHCPv6 Client Object
State was added in version 255.

### Manager Object
NamespaceNSID was added in version 256.

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

## NOTES
1.

the usual interface versioning guidelines

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


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 id,

                      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 FlushCaches() flushes all resource record caches maintained by the resolver, and ensures that any subsequent lookups re-request their responses from their sources.

The ResetServerFeatures() flushes any feature information learned about remote DNS servers. This ensures that subsequent lookups will be initially attempted at the highest DNS protocol feature level again, possibly requiring a (potentially slow) downgrade cycle to recognize the supported feature level again.

The RegisterService() method may be used to register a DNS-SD service on the host. This functionality is closely related to the functionality provided by systemd.dnssd(5) files. It takes a server identifier string as first parameter (this is just a local identifier, and should be chosen so that it neither collides with the basename of *.dnssd files nor with names chosen by other IPC clients). It also takes a name template string for the DNS-SD service name visible on the network. This string is subject to specifier expansation, as documented for the Name= setting in *.dnssd files. It also takes a service type string containing the DNS-SD service type, as well as an IP port, a priority/weight pair for the DNS-SD SRV record. Finally, it takes an array of TXT record data. It returns an object path which may be used as handle to the registered service.

The UnregisterService() method undoes the effect of RegisterService() and deletes a DNS-SD service previously created via IPC again.

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:

```
/* Input+Output: Protocol/scope */
#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)
/* Input: Restrictions */
#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_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_NO_STALE           (UINT64_C(1) << 24)
#define SD_RESOLVED_RELAX_SINGLE_LABEL (UINT64_C(1) << 25)
/* Output: Security */
#define SD_RESOLVED_AUTHENTICATED      (UINT64_C(1) <<  9)
#define SD_RESOLVED_CONFIDENTIAL       (UINT64_C(1) << 18)
/* Output: Origin */
#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.

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

The next six 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. NO_STALE flag can be set to disable answering request with stale records.

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

CONFIDENTIAL means the query was resolved via encrypted channels or never left this system.

The next five bits flags are used in output and provide information about the origin of the answer. FROM_SYNTHETIC means the query was (at least partially) synthesized locally. FROM_CACHE means the query was answered (at least partially) using the cache. FROM_ZONE means the query was answered (at least partially) based on public, locally registered records. 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-existence 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).

The DNSSECNegativeTrustAnchors property contains a list of recognized DNSSEC negative trust anchors and contains a list of domains.

## 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. Added in version 246.

org.freedesktop.resolve1.InvalidReply

A response from the selected DNS server was not understood. Added in version 246.

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). Added in version 246.

org.freedesktop.resolve1.CNameLoop

The look-up failed because a CNAME or DNAME loop was detected. Added in version 246.

org.freedesktop.resolve1.Aborted

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

org.freedesktop.resolve1.NoSuchService

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

org.freedesktop.resolve1.DnssecFailed

The acquired response did not pass DNSSEC validation. Added in version 246.

org.freedesktop.resolve1.NoTrustAnchor

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

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. Added in version 246.

org.freedesktop.resolve1.NoSuchLink

No network interface with the specified network interface index exists. Added in version 246.

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. Added in version 246.

org.freedesktop.resolve1.NetworkDown

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

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]. Added in version 246.

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

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

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

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


resolved.conf

title: resolved.conf(5)

text:
# resolved.conf(5)

## NAME
resolved.conf, resolved.conf.d - Network Name Resolution configuration files

## SYNOPSIS
/etc/systemd/resolved.conf

/run/systemd/resolved.conf

/usr/local/lib/systemd/resolved.conf

/usr/lib/systemd/resolved.conf

/etc/systemd/resolved.conf.d/*.conf

/run/systemd/resolved.conf.d/*.conf

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

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

## DESCRIPTION
These configuration files control local DNS and LLMNR name resolution.

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

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

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

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

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

DNS=

A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. Each address can optionally take a port number separated with ":", a network interface name or index separated with "%", and a Server Name Indication (SNI) separated with "#". When IPv6 address is specified with a port number, then the address must be in the square brackets. That is, the acceptable full formats are "111.222.333.444:9953%ifname#example.com" for IPv4 and "[1111:2222::3333]:9953%ifname#example.com" for IPv6. DNS requests are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from systemd-networkd.service(8) or set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS servers listed in /etc/resolv.conf are used instead, if that file exists and any servers are configured in it. This setting defaults to the empty list. Added in version 213.

FallbackDNS=

A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Please see DNS= for acceptable format of addresses. Any per-link DNS servers obtained from systemd-networkd.service(8) take precedence over this setting, as do any servers set via DNS= above or /etc/resolv.conf. This setting is hence only used if no other DNS server information is known. If this option is not given, a compiled-in list of DNS servers is used instead. Added in version 216.

Domains=

A space-separated list of domains, optionally prefixed with "~", used for two distinct purposes described below. Defaults to the empty list. Any domains not prefixed with "~" are used as search suffixes when resolving single-label hostnames (domain names which contain no dot), in order to qualify them into fully-qualified domain names (FQDNs). These "search domains" are strictly processed in the order they are specified in, until the name with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search domains listed in /etc/resolv.conf with the search keyword are used instead, if that file exists and any domains are configured in it.

The domains prefixed with "~" are called "route-only domains". All domains listed here (both search domains and route-only domains after removing the "~" prefix) define a search path that preferably directs DNS queries to this interface. This search path has an effect only when suitable per-link DNS servers are known. Such servers may be defined through the DNS= setting (see above) and dynamically at run time, for example from DHCP leases. If no per-link DNS servers are known, route-only domains have no effect.

Use the construct "~." (which is composed from "~" to indicate a route-only domain and "." to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the DNS servers defined for this link preferably for all domains.

See "Protocols and Routing" in systemd-resolved.service(8) for details of how search and route-only domains are used.

Note that configuring the MulticastDNS domain "local" as search or routing domain has the effect of routing lookups for this domain to classic unicast DNS. This may be used to provide compatibility with legacy installations that use this domain in a unicast DNS context, against the IANA assignment of this domain to pure MulticastDNS purposes. Search and routing domains are a unicast DNS concept, they cannot be used to resolve single-label lookups via MulticastDNS.

Added in version 229.

LLMNR=

Takes a boolean argument or "resolve". Controls Link-Local Multicast Name Resolution support (RFC 4795[2]) on the local host. If true, enables full LLMNR responder and resolver support. If false, disables both. If set to "resolve", only resolution support is enabled, but responding is disabled. Note that systemd-networkd.service(8) also maintains per-link LLMNR settings. LLMNR will be enabled on a link only if the per-link and the global setting is on. Added in version 216.

MulticastDNS=

Takes a boolean argument or "resolve". Controls Multicast DNS support (RFC 6762[3]) on the local host. If true, enables full Multicast DNS responder and resolver support. If false, disables both. If set to "resolve", only resolution support is enabled, but responding is disabled. Note that systemd-networkd.service(8) also maintains per-link Multicast DNS settings. Multicast DNS will be enabled on a link only if the per-link and the global setting is on. Added in version 234.

DNSSEC=

Takes a boolean argument or "allow-downgrade". If set to true, all DNS lookups are DNSSEC-validated locally (excluding LLMNR and Multicast DNS). If the response to a lookup request is detected to be invalid a lookup failure is returned to applications. Note that this mode requires a DNS server that supports DNSSEC. If the DNS server does not properly support DNSSEC all validations will fail.

If set to "allow-downgrade", DNSSEC validation is attempted, but if the server does not support DNSSEC properly, DNSSEC mode is automatically disabled. Note that this mode makes DNSSEC validation vulnerable to "downgrade" attacks, where an attacker might be able to trigger a downgrade to non-DNSSEC mode by synthesizing a DNS response that suggests DNSSEC was not supported.

If set to false, DNS lookups are not DNSSEC validated.

Note that DNSSEC validation requires retrieval of additional DNS data, and thus results in a small DNS lookup time penalty.

DNSSEC requires knowledge of "trust anchors" to prove data integrity. The trust anchor for the Internet root domain is built into the resolver, additional trust anchors may be defined with dnssec-trust-anchors.d(5). Trust anchors may change at regular intervals, and old trust anchors may be revoked. In such a case DNSSEC validation is not possible until new trust anchors are configured locally or the resolver software package is updated with the new root trust anchor. In effect, when the built-in trust anchor is revoked and DNSSEC= is true, all further lookups will fail, as it cannot be proved anymore whether lookups are correctly signed, or validly unsigned. If DNSSEC= is set to "allow-downgrade" the resolver will automatically turn off DNSSEC validation in such a case.

Client programs looking up DNS data will be informed whether lookups could be verified using DNSSEC, or whether the returned data could not be verified (either because the data was found unsigned in the DNS, or the DNS server did not support DNSSEC or no appropriate trust anchors were known). In the latter case, it is assumed that client programs employ a secondary scheme to validate the returned DNS data, should this be required.

It is recommended to set DNSSEC= to true on systems where it is known that the DNS server supports DNSSEC correctly, and where software or trust anchor updates happen regularly. On other systems it is recommended to set DNSSEC= to "allow-downgrade".

In addition to this global DNSSEC setting systemd-networkd.service(8) also maintains per-link DNSSEC settings. For system DNS servers (see above), only the global DNSSEC setting is in effect. For per-link DNS servers the per-link setting is in effect, unless it is unset in which case the global setting is used instead.

Site-private DNS zones generally conflict with DNSSEC operation, unless a negative (if the private zone is not signed) or positive (if the private zone is signed) trust anchor is configured for them. If "allow-downgrade" mode is selected, it is attempted to detect site-private DNS zones using top-level domains (TLDs) that are not known by the DNS root server. This logic does not work in all private zone setups.

Defaults to "no".

Added in version 229.

DNSOverTLS=

Takes a boolean argument or "opportunistic". If true all connections to the server will be encrypted. Note that this mode requires a DNS server that supports DNS-over-TLS and has a valid certificate. If the hostname was specified in DNS= by using the format "address#server_name" it is used to validate its certificate and also to enable Server Name Indication (SNI) when opening a TLS connection. Otherwise the certificate is checked against the server's IP. If the DNS server does not support DNS-over-TLS all DNS requests will fail. When set to "opportunistic" DNS request are attempted to send encrypted with DNS-over-TLS. If the DNS server does not support TLS, DNS-over-TLS is disabled. Note that this mode makes DNS-over-TLS vulnerable to "downgrade" attacks, where an attacker might be able to trigger a downgrade to non-encrypted mode by synthesizing a response that suggests DNS-over-TLS was not supported. If set to false, DNS lookups are send over UDP.

Note that DNS-over-TLS requires additional data to be send for setting up an encrypted connection, and thus results in a small DNS look-up time penalty.

Note that in "opportunistic" mode the resolver is not capable of authenticating the server, so it is vulnerable to "man-in-the-middle" attacks.

In addition to this global DNSOverTLS= setting systemd-networkd.service(8) also maintains per-link DNSOverTLS= settings. For system DNS servers (see above), only the global DNSOverTLS= setting is in effect. For per-link DNS servers the per-link setting is in effect, unless it is unset in which case the global setting is used instead.

Defaults to "no".

Added in version 239.

Cache=

Takes a boolean or "no-negative" as argument. If "yes" (the default), resolving a domain name which already got queried earlier will return the previous result as long as it is still valid, and thus does not result in a new network request. Be aware that turning off caching comes at a performance penalty, which is particularly high when DNSSEC is used. If "no-negative", only positive answers are cached. Note that caching is turned off by default for host-local DNS servers. See CacheFromLocalhost= for details.

Added in version 231.

CacheFromLocalhost=

Takes a boolean as argument. If "no" (the default), and response cames from host-local IP address (such as 127.0.0.1 or ::1), the result would not be cached in order to avoid potential duplicate local caching. Added in version 248.

DNSStubListener=

Takes a boolean argument or one of "udp" and "tcp". If "udp", a DNS stub resolver will listen for UDP requests on addresses 127.0.0.53 and 127.0.0.54, port 53. If "tcp", the stub will listen for TCP requests on the same addresses and port. If "yes" (the default), the stub listens for both UDP and TCP requests. If "no", the stub listener is disabled. The DNS stub resolver on 127.0.0.53 provides the full feature set of the local resolver, which includes offering LLMNR/MulticastDNS resolution. The DNS stub resolver on 127.0.0.54 provides a more limited resolver, that operates in "proxy" mode only, i.e. it will pass most DNS messages relatively unmodified to the current upstream DNS servers and back, but not try to process the messages locally, and hence does not validate DNSSEC, or offer up LLMNR/MulticastDNS. (It will translate to DNS-over-TLS communication if needed however.)

Note that the DNS stub listener is turned off implicitly when its listening address and port are already in use.

Added in version 232.

DNSStubListenerExtra=

Takes an IPv4 or IPv6 address to listen on. The address may be optionally prefixed with a protocol name ("udp" or "tcp") separated with ":". If the protocol is not specified, the service will listen on both UDP and TCP. It may be also optionally suffixed by a numeric port number with separator ":". When an IPv6 address is specified with a port number, then the address must be in the square brackets. If the port is not specified, then the service uses port 53. Note that this is independent of the primary DNS stub configured with DNSStubListener=, and only configures additional sockets to listen on. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. Defaults to unset. Examples:

```
DNSStubListenerExtra=192.168.10.10
DNSStubListenerExtra=2001:db8:0:f102::10
DNSStubListenerExtra=192.168.10.11:9953
DNSStubListenerExtra=[2001:db8:0:f102::11]:9953
DNSStubListenerExtra=tcp:192.168.10.12
DNSStubListenerExtra=udp:2001:db8:0:f102::12
DNSStubListenerExtra=tcp:192.168.10.13:9953
DNSStubListenerExtra=udp:[2001:db8:0:f102::13]:9953
```

Added in version 247.

ReadEtcHosts=

Takes a boolean argument. If "yes" (the default), systemd-resolved will read /etc/hosts, and try to resolve hosts or address by using the entries in the file before sending query to DNS servers. Added in version 240.

ResolveUnicastSingleLabel=

Takes a boolean argument. When false (the default), systemd-resolved will not resolve A and AAAA queries for single-label names over classic DNS. Note that such names may still be resolved if search domains are specified (see Domains= above), or using other mechanisms, in particular via LLMNR or from /etc/hosts. When true, queries for single-label names will be forwarded to global DNS servers even if no search domains are defined. This option is provided for compatibility with configurations where public DNS servers are not used. Forwarding single-label names to servers not under your control is not standard-conformant, see IAB Statement[4], and may create a privacy and security risk.

Added in version 246.

StaleRetentionSec=SECONDS

Takes a duration value, which determines the length of time DNS resource records can be retained in the cache beyond their Time To Live (TTL). This allows these records to be returned as stale records. By default, this value is set to zero, meaning that DNS resource records are not stored in the cache after their TTL expires. This is useful when a DNS server failure occurs or becomes unreachable. In such cases, systemd-resolved(8) continues to use the stale records to answer DNS queries, particularly when no valid response can be obtained from the upstream DNS servers. However, this does not apply to NXDOMAIN responses, as those are still perfectly valid responses. This feature enhances resilience against DNS infrastructure failures and outages.

systemd-resolved always attempts to reach the upstream DNS servers first, before providing the client application with any stale data. If this feature is enabled, cache will not be flushed when changing servers.

Added in version 254.

## SEE ALSO
systemd(1), systemd-resolved.service(8), systemd-networkd.service(8), dnssec-trust-anchors.d(5), resolv.conf(5)

## NOTES
1.

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

2.

RFC 4795

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

3.

RFC 6762

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

4.

IAB Statement

https://www.iab.org/documents/correspondence-reports-documents/2013-2/iab-statement-dotless-domains-considered-harmful/


systemd.dnssd

title: systemd.dnssd(5)

summary: DNS\-SD configuration

text:
# systemd.dnssd(5)

## NAME
systemd.dnssd - DNS-SD configuration

## SYNOPSIS
network_service.dnssd

## DESCRIPTION
DNS-SD setup is performed by systemd-resolved(8).

The main network service file must have the extension .dnssd; other extensions are ignored.

The .dnssd files are read from the files located in the system network directories /usr/lib/systemd/dnssd and /usr/local/lib/systemd/dnssd, the volatile runtime network directory /run/systemd/dnssd and the local administration network directory /etc/systemd/dnssd. All configuration files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc/ have the highest priority, files in /run/ take precedence over files with the same name in /usr/lib/. This can be used to override a system-supplied configuration file with a local file if needed.

Along with the network service file foo.dnssd, a "drop-in" directory foo.dnssd.d/ may exist. All files with the suffix ".conf" from this directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers.

In addition to /etc/systemd/dnssd, drop-in ".d" directories can be placed in /usr/lib/systemd/dnssd or /run/systemd/dnssd directories. Drop-in files in /etc/ take precedence over those in /run/ which in turn take precedence over those in /usr/lib/ or /usr/local/lib. Drop-in files under any of these directories take precedence over the main network service file wherever located.

## [SERVICE] SECTION OPTIONS
The network service file contains a [Service] section, which specifies a discoverable network service announced in a local network with Multicast DNS broadcasts.

Name=

An instance name of the network service as defined in the section 4.1.1 of RFC 6763[1], e.g. "webserver". The option supports simple specifier expansion. The following expansions are understood:

Table 1. Specifiers available

Specifier

Meaning

Details

"%a"

Architecture

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

"%A"

Operating system image version

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

"%b"

Boot ID

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

"%B"

Operating system build ID

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

"%H"

Host name

The hostname of the running system.

"%m"

Machine ID

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

"%M"

Operating system image identifier

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

"%o"

Operating system ID

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

"%v"

Kernel release

Identical to uname -r output.

"%w"

Operating system version ID

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

"%W"

Operating system variant ID

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

"%%"

Single percent sign

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

Added in version 236.

Type=

A type of the network service as defined in the section 4.1.2 of RFC 6763[1], e.g. "_http._tcp". Added in version 236.

SubType=

A subtype of the network service as defined in the section 7.1 of RFC 6763[1], e.g. "_printer". Added in version 256.

Port=

An IP port number of the network service. Added in version 236.

Priority=

A priority number set in SRV resource records corresponding to the network service. Added in version 236.

Weight=

A weight number set in SRV resource records corresponding to the network service. Added in version 236.

TxtText=

A whitespace-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record, e.g. "path=/portal/index.html". Keys and values can contain C-style escape sequences which get translated upon reading configuration files. This option together with TxtData= may be specified more than once, in which case multiple TXT resource records will be created for the service. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect.

Added in version 236.

TxtData=

A whitespace-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record where values are base64-encoded string representing any binary data, e.g. "data=YW55IGJpbmFyeSBkYXRhCg==". Keys can contain C-style escape sequences which get translated upon reading configuration files. This option together with TxtText= may be specified more than once, in which case multiple TXT resource records will be created for the service. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect.

Added in version 236.

## EXAMPLES
Example 1. HTTP service

```
# /etc/systemd/dnssd/http.dnssd
[Service]
Name=%H
Type=_http._tcp
Port=80
TxtText=path=/stats/index.html t=temperature_sensor
```

This makes the http server running on the host discoverable in the local network given MulticastDNS is enabled on the network interface.

Now the utility "resolvectl" should be able to resolve the service to the host's name:

```
$ resolvectl service meteo._http._tcp.local
meteo._http._tcp.local: meteo.local:80 [priority=0, weight=0]

                        169.254.208.106%senp0s21f0u2u4

                        fe80::213:3bff:fe49:8aa%senp0s21f0u2u4

                        path=/stats/index.html

                        t=temperature_sensor

                        (meteo/_http._tcp/local)
-- Information acquired via protocol mDNS/IPv6 in 4.0ms.
-- Data is authenticated: yes
```

"Avahi" running on a different host in the same local network should see the service as well:

```
$ avahi-browse -a -r
+ enp3s0 IPv6 meteo                                         Web Site             local
+ enp3s0 IPv4 meteo                                         Web Site             local
= enp3s0 IPv6 meteo                                         Web Site             local

   hostname = [meteo.local]

   address = [fe80::213:3bff:fe49:8aa]

   port = [80]

   txt = ["path=/stats/index.html" "t=temperature_sensor"]
= enp3s0 IPv4 meteo                                         Web Site             local

   hostname = [meteo.local]

   address = [169.254.208.106]

   port = [80]

   txt = ["path=/stats/index.html" "t=temperature_sensor"]
```

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

## NOTES
1.

RFC 6763

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