[thirdparty/systemd.git] / man / systemd.dnssd.xml

<?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.dnssd"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          conditional='ENABLE_RESOLVE'>

  <refentryinfo>
    <title>systemd.dnssd</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd.dnssd</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd.dnssd</refname>
    <refpurpose>DNS-SD configuration</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename><replaceable>network_service</replaceable>.dnssd</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>DNS-SD setup is performed by
    <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
    </para>

    <para>The main network service file must have the extension <filename>.dnssd</filename>; other
    extensions are ignored.</para>

    <para>The <filename>.dnssd</filename> files are read from the files located in the system network
    directories <filename>/usr/lib/systemd/dnssd</filename> and
    <filename>/usr/local/lib/systemd/dnssd</filename>, the volatile runtime network directory
    <filename>/run/systemd/dnssd</filename> and the local administration network directory
    <filename>/etc/systemd/dnssd</filename>. 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 <filename>/etc/</filename> have the highest priority, files in
    <filename>/run/</filename> take precedence over files with the same name in
    <filename>/usr/lib/</filename>. This can be used to override a system-supplied configuration file with a
    local file if needed.</para>

    <para>Along with the network service file <filename>foo.dnssd</filename>, a "drop-in" directory
    <filename>foo.dnssd.d/</filename> may exist. All files with the suffix
    <literal>.conf</literal> 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.</para>

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

  <refsect1>
    <title>[Service] Section Options</title>

      <para>The network service file contains a [Service]
      section, which specifies a discoverable network service announced in a
      local network with Multicast DNS broadcasts.</para>

      <variablelist class='network-directives'>
        <varlistentry>
          <term><varname>Name=</varname></term>
          <listitem>
            <para>An instance name of the network service as defined in the section 4.1.1 of <ulink
            url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>webserver</literal>.</para>
            <para>The option supports simple specifier expansion. The following expansions are understood:</para>
            <table class='specifiers'>
              <title>Specifiers available</title>
              <tgroup cols='3' align='left' colsep='1' rowsep='1'>
                <colspec colname="spec" />
                <colspec colname="mean" />
                <colspec colname="detail" />
                <thead>
                  <row>
                    <entry>Specifier</entry>
                    <entry>Meaning</entry>
                    <entry>Details</entry>
                  </row>
                </thead>
                <tbody>
                  <xi:include href="standard-specifiers.xml" xpointer="a"/>
                  <xi:include href="standard-specifiers.xml" xpointer="A"/>
                  <xi:include href="standard-specifiers.xml" xpointer="b"/>
                  <xi:include href="standard-specifiers.xml" xpointer="B"/>
                  <xi:include href="standard-specifiers.xml" xpointer="H"/>
                  <xi:include href="standard-specifiers.xml" xpointer="m"/>
                  <xi:include href="standard-specifiers.xml" xpointer="M"/>
                  <xi:include href="standard-specifiers.xml" xpointer="o"/>
                  <xi:include href="standard-specifiers.xml" xpointer="v"/>
                  <xi:include href="standard-specifiers.xml" xpointer="w"/>
                  <xi:include href="standard-specifiers.xml" xpointer="W"/>
                  <xi:include href="standard-specifiers.xml" xpointer="percent"/>
                </tbody>
              </tgroup>
            </table>

              <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Type=</varname></term>
          <listitem>
            <para>A type of the network service as defined in the section 4.1.2 of <ulink
            url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>_http._tcp</literal>.
            </para>

          <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>SubType=</varname></term>
          <listitem>
            <para>A subtype of the network service as defined in the section 7.1 of <ulink
            url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>_printer</literal>.
            </para>

          <xi:include href="version-info.xml" xpointer="v256"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Port=</varname></term>
          <listitem>
            <para>An IP port number of the network service.</para>

          <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Priority=</varname></term>
          <listitem>
            <para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding
            to the network service.</para>

          <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Weight=</varname></term>
          <listitem>
            <para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding
            to the network service.</para>

          <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>TxtText=</varname></term>
          <listitem>
            <para>A whitespace-separated list of arbitrary key/value pairs
            conveying additional information about the named service in the corresponding TXT resource record,
            e.g. <literal>path=/portal/index.html</literal>. Keys and values can contain C-style escape
            sequences which get translated upon reading configuration files.
            </para>
            <para>This option together with <varname>TxtData=</varname> 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.
            </para>

            <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>TxtData=</varname></term>
          <listitem>
            <para>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. <literal>data=YW55IGJpbmFyeSBkYXRhCg==</literal>. Keys can contain C-style escape
            sequences which get translated upon reading configuration files.
            </para>
            <para>This option together with <varname>TxtText=</varname> 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.
            </para>

            <xi:include href="version-info.xml" xpointer="v236"/>
          </listitem>
        </varlistentry>
      </variablelist>

  </refsect1>

  <refsect1>
    <title>Examples</title>
    <example>
      <title>HTTP service</title>

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

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

      <para>Now the utility <literal>resolvectl</literal> should be able to resolve the
      service to the host's name:</para>

      <programlisting>$ 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</programlisting>

      <para><literal>Avahi</literal> running on a different host in the same local network should see the service as well:</para>

      <programlisting>$ 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"]</programlisting>

    </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>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>

</refentry>
Commit	Line	Data
514094f9	1	<?xml version='1.0'?>
3a54a157	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26	3	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
db9ecf05	4	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6e73d91e	5
503298b7 LP	6	<refentry id="systemd.dnssd"
	7	xmlns:xi="http://www.w3.org/2001/XInclude"
	8	conditional='ENABLE_RESOLVE'>
6e73d91e DR	9
	10	<refentryinfo>
	11	<title>systemd.dnssd</title>
	12	<productname>systemd</productname>
6e73d91e DR	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
eb5f4dde ZJS	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
3b121157 ZJS	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
eb5f4dde	48	local file if needed.</para>
6e73d91e DR	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
eb5f4dde ZJS	56	<para>In addition to <filename>/etc/systemd/dnssd</filename>, drop-in <literal>.d</literal> directories
eb5f4dde ZJS	57	can be placed in <filename>/usr/lib/systemd/dnssd</filename> or <filename>/run/systemd/dnssd</filename>
3b121157 ZJS	58	directories. Drop-in files in <filename>/etc/</filename> take precedence over those in
3b121157 ZJS	59	<filename>/run/</filename> which in turn take precedence over those in <filename>/usr/lib/</filename> or
eb5f4dde ZJS	60	<filename>/usr/local/lib</filename>. Drop-in files under any of these directories take precedence over
eb5f4dde ZJS	61	the main network service file wherever located.</para>
6e73d91e DR	62	</refsect1>
	63
	64	<refsect1>
	65	<title>[Service] Section Options</title>
	66
bdac5608	67	<para>The network service file contains a [Service]
6e73d91e DR	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>
0d525a3e	78	<table class='specifiers'>
6e73d91e DR	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>
503298b7	92	<xi:include href="standard-specifiers.xml" xpointer="a"/>
9a515f0a	93	<xi:include href="standard-specifiers.xml" xpointer="A"/>
c83347b4	94	<xi:include href="standard-specifiers.xml" xpointer="b"/>
503298b7	95	<xi:include href="standard-specifiers.xml" xpointer="B"/>
c83347b4 LP	96	<xi:include href="standard-specifiers.xml" xpointer="H"/>
c83347b4 LP	97	<xi:include href="standard-specifiers.xml" xpointer="m"/>
9a515f0a	98	<xi:include href="standard-specifiers.xml" xpointer="M"/>
503298b7	99	<xi:include href="standard-specifiers.xml" xpointer="o"/>
c83347b4	100	<xi:include href="standard-specifiers.xml" xpointer="v"/>
503298b7 LP	101	<xi:include href="standard-specifiers.xml" xpointer="w"/>
503298b7 LP	102	<xi:include href="standard-specifiers.xml" xpointer="W"/>
c83347b4	103	<xi:include href="standard-specifiers.xml" xpointer="percent"/>
6e73d91e DR	104	</tbody>
	105	</tgroup>
	106	</table>
ec07c3c8 AK	107
ec07c3c8 AK	108	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	109	</listitem>
	110	</varlistentry>
	111	<varlistentry>
	112	<term><varname>Type=</varname></term>
	113	<listitem>
	114	<para>A type of the network service as defined in the section 4.1.2 of <ulink
	115	url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>_http._tcp</literal>.
	116	</para>
ec07c3c8 AK	117
ec07c3c8 AK	118	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	119	</listitem>
6e73d91e DR	120	</varlistentry>
88123aa2 RP	121	<varlistentry>
	122	<term><varname>SubType=</varname></term>
	123	<listitem>
	124	<para>A subtype of the network service as defined in the section 7.1 of <ulink
	125	url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>_printer</literal>.
	126	</para>
	127
	128	<xi:include href="version-info.xml" xpointer="v256"/>
	129	</listitem>
	130	</varlistentry>
6e73d91e DR	131	<varlistentry>
	132	<term><varname>Port=</varname></term>
	133	<listitem>
	134	<para>An IP port number of the network service.</para>
ec07c3c8 AK	135
ec07c3c8 AK	136	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	137	</listitem>
	138	</varlistentry>
	139	<varlistentry>
	140	<term><varname>Priority=</varname></term>
	141	<listitem>
9a024bf1 ZJS	142	<para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding
9a024bf1 ZJS	143	to the network service.</para>
ec07c3c8 AK	144
ec07c3c8 AK	145	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	146	</listitem>
	147	</varlistentry>
	148	<varlistentry>
	149	<term><varname>Weight=</varname></term>
	150	<listitem>
9a024bf1 ZJS	151	<para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding
9a024bf1 ZJS	152	to the network service.</para>
ec07c3c8 AK	153
ec07c3c8 AK	154	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	155	</listitem>
	156	</varlistentry>
	157	<varlistentry>
	158	<term><varname>TxtText=</varname></term>
	159	<listitem>
	160	<para>A whitespace-separated list of arbitrary key/value pairs
	161	conveying additional information about the named service in the corresponding TXT resource record,
	162	e.g. <literal>path=/portal/index.html</literal>. Keys and values can contain C-style escape
	163	sequences which get translated upon reading configuration files.
	164	</para>
400f54fb DR	165	<para>This option together with <varname>TxtData=</varname> may be specified more than once, in which
	166	case multiple TXT resource records will be created for the service. If the empty string is assigned to
	167	this option, the list is reset and all prior assignments will have no effect.
	168	</para>
ec07c3c8 AK	169
ec07c3c8 AK	170	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	171	</listitem>
	172	</varlistentry>
	173	<varlistentry>
	174	<term><varname>TxtData=</varname></term>
	175	<listitem>
	176	<para>A whitespace-separated list of arbitrary key/value pairs
	177	conveying additional information about the named service in the corresponding TXT resource record
	178	where values are base64-encoded string representing any binary data,
	179	e.g. <literal>data=YW55IGJpbmFyeSBkYXRhCg==</literal>. Keys can contain C-style escape
	180	sequences which get translated upon reading configuration files.
	181	</para>
400f54fb DR	182	<para>This option together with <varname>TxtText=</varname> may be specified more than once, in which
	183	case multiple TXT resource records will be created for the service. If the empty string is assigned to
	184	this option, the list is reset and all prior assignments will have no effect.
	185	</para>
ec07c3c8 AK	186
ec07c3c8 AK	187	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	188	</listitem>
	189	</varlistentry>
	190	</variablelist>
	191
	192	</refsect1>
	193
	194	<refsect1>
	195	<title>Examples</title>
	196	<example>
	197	<title>HTTP service</title>
	198
	199	<programlisting># /etc/systemd/dnssd/http.dnssd
	200	[Service]
5526ac50	201	Name=%H
6e73d91e DR	202	Type=_http._tcp
	203	Port=80
	204	TxtText=path=/stats/index.html t=temperature_sensor</programlisting>
	205
	206	<para>This makes the http server running on the host discoverable in the local network
	207	given MulticastDNS is enabled on the network interface.</para>
	208
b69f810c	209	<para>Now the utility <literal>resolvectl</literal> should be able to resolve the
6e73d91e DR	210	service to the host's name:</para>
6e73d91e DR	211
b69f810c	212	<programlisting>$ resolvectl service meteo._http._tcp.local
6e73d91e DR	213	meteo._http._tcp.local: meteo.local:80 [priority=0, weight=0]
	214	169.254.208.106%senp0s21f0u2u4
	215	fe80::213:3bff:fe49:8aa%senp0s21f0u2u4
	216	path=/stats/index.html
	217	t=temperature_sensor
	218	(meteo/_http._tcp/local)
	219
	220	-- Information acquired via protocol mDNS/IPv6 in 4.0ms.
	221	-- Data is authenticated: yes</programlisting>
	222
	223	<para><literal>Avahi</literal> running on a different host in the same local network should see the service as well:</para>
	224
	225	<programlisting>$ avahi-browse -a -r
	226	+ enp3s0 IPv6 meteo Web Site local
	227	+ enp3s0 IPv4 meteo Web Site local
	228	= enp3s0 IPv6 meteo Web Site local
	229	hostname = [meteo.local]
	230	address = [fe80::213:3bff:fe49:8aa]
	231	port = [80]
	232	txt = ["path=/stats/index.html" "t=temperature_sensor"]
	233	= enp3s0 IPv4 meteo Web Site local
	234	hostname = [meteo.local]
	235	address = [169.254.208.106]
	236	port = [80]
	237	txt = ["path=/stats/index.html" "t=temperature_sensor"]</programlisting>
	238
	239	</example>
	240	</refsect1>
	241
	242	<refsect1>
	243	<title>See Also</title>
13a69c12 DT	244	<para><simplelist type="inline">
	245	<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	246	<member><citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
	247	<member><citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	248	</simplelist></para>
6e73d91e DR	249	</refsect1>
	250
	251	</refentry>