From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 2 Apr 2025 13:39:54 +0000 (+0200)
Subject: man: document dns-delegate files
X-Git-Tag: v258-rc1~563^2~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=89768b601bc92c9de855394be4959c469ce9107c;p=thirdparty%2Fsystemd.git

man: document dns-delegate files
---

diff --git a/man/rules/meson.build b/man/rules/meson.build
index f44643352b4..048cc79430a 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -1187,6 +1187,7 @@ manpages = [
  ['systemd', '1', ['init'], ''],
  ['systemd.automount', '5', [], ''],
  ['systemd.device', '5', [], ''],
+ ['systemd.dns-delegate', '5', [], 'ENABLE_RESOLVE'],
  ['systemd.dnssd', '5', [], 'ENABLE_RESOLVE'],
  ['systemd.environment-generator', '7', [], 'ENABLE_ENVIRONMENT_D'],
  ['systemd.exec', '5', [], ''],
diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 3bc3a01ab7e..e736f78b0f5 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -509,6 +509,8 @@ search foobar.com barbar.com
     <para><simplelist type="inline">
       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systed.dns-delegate</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systed.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
diff --git a/man/systemd.dns-delegate.xml b/man/systemd.dns-delegate.xml
new file mode 100644
index 00000000000..3da069d8a6f
--- /dev/null
+++ b/man/systemd.dns-delegate.xml
@@ -0,0 +1,99 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd.dns-delegate"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          conditional='ENABLE_RESOLVE'>
+
+  <refentryinfo>
+    <title>systemd.dns-delegate</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd.dns-delegate</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd.dns-delegate</refname>
+    <refpurpose>DNS Server Delegation Configuration</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><simplelist>
+      <member><filename>/etc/systemd/dns-delegate.d/*.dns-delegate</filename></member>
+      <member><filename>/run/systemd/dns-delegate.d/*.dns-delegate</filename></member>
+      <member><filename>/usr/local/lib/systemd/dns-delegate.d/*.dns-delegate</filename></member>
+      <member><filename>/usr/lib/systemd/dns-delegate.d/*.dns-delegate</filename></member>
+    </simplelist></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>*.dns-delegate</filename> files may be used to delegate DNS lookups in specific domains to
+    specific DNS servers. These files are read by
+    <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    Each such file defines a combination of one or more DNS servers and one or more DNS domains. Each such
+    definition synthesizes a DNS lookup scope that ensure lookups below the specified domains are sent to the
+    specified DNS servers, possibly in addition to any per-interface scopes and the global scope that
+    <command>systemd-resolved</command> maintains anyway.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>[Delegate] Section Options</title>
+
+      <variablelist class='network-directives'>
+        <varlistentry>
+          <term><varname>DNS=</varname></term>
+          <listitem>
+            <para>Takes one or more DNS server specifications, in the same syntax as the option of the same name in <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+            <xi:include href="version-info.xml" xpointer="v258"/>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Domains=</varname></term>
+          <listitem>
+            <para>Takes one or more domain name specifications, in the same syntax as the option of the same name in <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+            <xi:include href="version-info.xml" xpointer="v258"/>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>DefaultRoute=</varname></term>
+          <listitem>
+            <para>Takes a boolean value, defaults to off. Controls whether this DNS server is a candidate for
+            looking up records for which no better route exists.</para>
+            <xi:include href="version-info.xml" xpointer="v258"/>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+    <example>
+      <programlisting># /etc/systemd/dns-delegate.d/foobar.dns-delegate
+[Delegate]
+DNS=203.0.113.47
+Domain=foobar.com</programlisting>
+
+      <para>This ensures lookups of <literal>foobar.com</literal> and any domains below it are directed to
+      DNS server 203.0.113.47.</para>
+    </example>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
+</refentry>