1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="systemd.dnssd"
7          xmlns:xi="http://www.w3.org/2001/XInclude"
8          conditional='ENABLE_RESOLVE'>
9
10  <refentryinfo>
11    <title>systemd.dnssd</title>
12    <productname>systemd</productname>
13  </refentryinfo>
14
15  <refmeta>
16    <refentrytitle>systemd.dnssd</refentrytitle>
17    <manvolnum>5</manvolnum>
18  </refmeta>
19
20  <refnamediv>
21    <refname>systemd.dnssd</refname>
22    <refpurpose>DNS-SD configuration</refpurpose>
23  </refnamediv>
24
25  <refsynopsisdiv>
26    <para><filename><replaceable>network_service</replaceable>.dnssd</filename></para>
27  </refsynopsisdiv>
28
29  <refsect1>
30    <title>Description</title>
31
32    <para>DNS-SD setup is performed by
33    <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
34    </para>
35
36    <para>The main network service file must have the extension <filename>.dnssd</filename>; other
37    extensions are ignored.</para>
38
39    <para>The <filename>.dnssd</filename> files are read from the files located in the system network
40    directories <filename>/usr/lib/systemd/dnssd</filename> and
41    <filename>/usr/local/lib/systemd/dnssd</filename>, the volatile runtime network directory
42    <filename>/run/systemd/dnssd</filename> and the local administration network directory
43    <filename>/etc/systemd/dnssd</filename>. All configuration files are collectively sorted and processed in
44    lexical order, regardless of the directories in which they live. However, files with identical filenames
45    replace each other. Files in <filename>/etc/</filename> have the highest priority, files in
46    <filename>/run/</filename> take precedence over files with the same name in
47    <filename>/usr/lib/</filename>. This can be used to override a system-supplied configuration file with a
48    local file if needed.</para>
49
50    <para>Along with the network service file <filename>foo.dnssd</filename>, a "drop-in" directory
51    <filename>foo.dnssd.d/</filename> may exist. All files with the suffix
52    <literal>.conf</literal> from this directory will be parsed after the file itself is
53    parsed. This is useful to alter or add configuration settings, without having to modify the main
54    configuration file. Each drop-in file must have appropriate section headers.</para>
55
56    <para>In addition to <filename>/etc/systemd/dnssd</filename>, drop-in <literal>.d</literal> directories
57    can be placed in <filename>/usr/lib/systemd/dnssd</filename> or <filename>/run/systemd/dnssd</filename>
58    directories. Drop-in files in <filename>/etc/</filename> take precedence over those in
59    <filename>/run/</filename> which in turn take precedence over those in <filename>/usr/lib/</filename> or
60    <filename>/usr/local/lib</filename>. Drop-in files under any of these directories take precedence over
61    the main network service file wherever located.</para>
62  </refsect1>
63
64  <refsect1>
65    <title>[Service] Section Options</title>
66
67      <para>The network service file contains a [Service]
68      section, which specifies a discoverable network service announced in a
69      local network with Multicast DNS broadcasts.</para>
70
71      <variablelist class='network-directives'>
72        <varlistentry>
73          <term><varname>Name=</varname></term>
74          <listitem>
75            <para>An instance name of the network service as defined in the section 4.1.1 of <ulink
76            url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>webserver</literal>.</para>
77            <para>The option supports simple specifier expansion. The following expansions are understood:</para>
78            <table class='specifiers'>
79              <title>Specifiers available</title>
80              <tgroup cols='3' align='left' colsep='1' rowsep='1'>
81                <colspec colname="spec" />
82                <colspec colname="mean" />
83                <colspec colname="detail" />
84                <thead>
85                  <row>
86                    <entry>Specifier</entry>
87                    <entry>Meaning</entry>
88                    <entry>Details</entry>
89                  </row>
90                </thead>
91                <tbody>
92                  <xi:include href="standard-specifiers.xml" xpointer="a"/>
93                  <xi:include href="standard-specifiers.xml" xpointer="A"/>
94                  <xi:include href="standard-specifiers.xml" xpointer="b"/>
95                  <xi:include href="standard-specifiers.xml" xpointer="B"/>
96                  <xi:include href="standard-specifiers.xml" xpointer="H"/>
97                  <xi:include href="standard-specifiers.xml" xpointer="m"/>
98                  <xi:include href="standard-specifiers.xml" xpointer="M"/>
99                  <xi:include href="standard-specifiers.xml" xpointer="o"/>
100                  <xi:include href="standard-specifiers.xml" xpointer="v"/>
101                  <xi:include href="standard-specifiers.xml" xpointer="w"/>
102                  <xi:include href="standard-specifiers.xml" xpointer="W"/>
103                  <xi:include href="standard-specifiers.xml" xpointer="percent"/>
104                </tbody>
105              </tgroup>
106            </table>
107          </listitem>
108        </varlistentry>
109        <varlistentry>
110          <term><varname>Type=</varname></term>
111          <listitem>
112            <para>A type of the network service as defined in the section 4.1.2 of <ulink
113            url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>_http._tcp</literal>.
114            </para>
115          </listitem>
116        </varlistentry>
117        <varlistentry>
118          <term><varname>Port=</varname></term>
119          <listitem>
120            <para>An IP port number of the network service.</para>
121          </listitem>
122        </varlistentry>
123        <varlistentry>
124          <term><varname>Priority=</varname></term>
125          <listitem>
126            <para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding
127            to the network service.</para>
128          </listitem>
129        </varlistentry>
130        <varlistentry>
131          <term><varname>Weight=</varname></term>
132          <listitem>
133            <para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding
134            to the network service.</para>
135          </listitem>
136        </varlistentry>
137        <varlistentry>
138          <term><varname>TxtText=</varname></term>
139          <listitem>
140            <para>A whitespace-separated list of arbitrary key/value pairs
141            conveying additional information about the named service in the corresponding TXT resource record,
142            e.g. <literal>path=/portal/index.html</literal>. Keys and values can contain C-style escape
143            sequences which get translated upon reading configuration files.
144            </para>
145            <para>This option together with <varname>TxtData=</varname> may be specified more than once, in which
146            case multiple TXT resource records will be created for the service. If the empty string is assigned to
147            this option, the list is reset and all prior assignments will have no effect.
148            </para>
149          </listitem>
150        </varlistentry>
151        <varlistentry>
152          <term><varname>TxtData=</varname></term>
153          <listitem>
154            <para>A whitespace-separated list of arbitrary key/value pairs
155            conveying additional information about the named service in the corresponding TXT resource record
156            where values are base64-encoded string representing any binary data,
157            e.g. <literal>data=YW55IGJpbmFyeSBkYXRhCg==</literal>. Keys can contain C-style escape
158            sequences which get translated upon reading configuration files.
159            </para>
160            <para>This option together with <varname>TxtText=</varname> may be specified more than once, in which
161            case multiple TXT resource records will be created for the service. If the empty string is assigned to
162            this option, the list is reset and all prior assignments will have no effect.
163            </para>
164          </listitem>
165        </varlistentry>
166      </variablelist>
167
168  </refsect1>
169
170  <refsect1>
171    <title>Examples</title>
172    <example>
173      <title>HTTP service</title>
174
175      <programlisting># /etc/systemd/dnssd/http.dnssd
176[Service]
177Name=%H
178Type=_http._tcp
179Port=80
180TxtText=path=/stats/index.html t=temperature_sensor</programlisting>
181
182      <para>This makes the http server running on the host discoverable in the local network
183      given MulticastDNS is enabled on the network interface.</para>
184
185      <para>Now the utility <literal>resolvectl</literal> should be able to resolve the
186      service to the host's name:</para>
187
188      <programlisting>$ resolvectl service meteo._http._tcp.local
189meteo._http._tcp.local: meteo.local:80 [priority=0, weight=0]
190                        169.254.208.106%senp0s21f0u2u4
191                        fe80::213:3bff:fe49:8aa%senp0s21f0u2u4
192                        path=/stats/index.html
193                        t=temperature_sensor
194                        (meteo/_http._tcp/local)
195
196-- Information acquired via protocol mDNS/IPv6 in 4.0ms.
197-- Data is authenticated: yes</programlisting>
198
199      <para><literal>Avahi</literal> running on a different host in the same local network should see the service as well:</para>
200
201      <programlisting>$ avahi-browse -a -r
202+ enp3s0 IPv6 meteo                                         Web Site             local
203+ enp3s0 IPv4 meteo                                         Web Site             local
204= enp3s0 IPv6 meteo                                         Web Site             local
205   hostname = [meteo.local]
206   address = [fe80::213:3bff:fe49:8aa]
207   port = [80]
208   txt = ["path=/stats/index.html" "t=temperature_sensor"]
209= enp3s0 IPv4 meteo                                         Web Site             local
210   hostname = [meteo.local]
211   address = [169.254.208.106]
212   port = [80]
213   txt = ["path=/stats/index.html" "t=temperature_sensor"]</programlisting>
214
215    </example>
216  </refsect1>
217
218  <refsect1>
219    <title>See Also</title>
220    <para>
221      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
222      <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
223      <citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
224    </para>
225  </refsect1>
226
227</refentry>
228