[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.2/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>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"
6e73d91e	3	"http://www.oasis-open.org/docbook/xml/4.2/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>
	120	</varlistentry>
	121	<varlistentry>
	122	<term><varname>Port=</varname></term>
	123	<listitem>
	124	<para>An IP port number of the network service.</para>
ec07c3c8 AK	125
ec07c3c8 AK	126	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	127	</listitem>
	128	</varlistentry>
	129	<varlistentry>
	130	<term><varname>Priority=</varname></term>
	131	<listitem>
9a024bf1 ZJS	132	<para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding
9a024bf1 ZJS	133	to the network service.</para>
ec07c3c8 AK	134
ec07c3c8 AK	135	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	136	</listitem>
	137	</varlistentry>
	138	<varlistentry>
	139	<term><varname>Weight=</varname></term>
	140	<listitem>
9a024bf1 ZJS	141	<para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding
9a024bf1 ZJS	142	to the network service.</para>
ec07c3c8 AK	143
ec07c3c8 AK	144	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	145	</listitem>
	146	</varlistentry>
	147	<varlistentry>
	148	<term><varname>TxtText=</varname></term>
	149	<listitem>
	150	<para>A whitespace-separated list of arbitrary key/value pairs
	151	conveying additional information about the named service in the corresponding TXT resource record,
	152	e.g. <literal>path=/portal/index.html</literal>. Keys and values can contain C-style escape
	153	sequences which get translated upon reading configuration files.
	154	</para>
400f54fb DR	155	<para>This option together with <varname>TxtData=</varname> may be specified more than once, in which
	156	case multiple TXT resource records will be created for the service. If the empty string is assigned to
	157	this option, the list is reset and all prior assignments will have no effect.
	158	</para>
ec07c3c8 AK	159
ec07c3c8 AK	160	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	161	</listitem>
	162	</varlistentry>
	163	<varlistentry>
	164	<term><varname>TxtData=</varname></term>
	165	<listitem>
	166	<para>A whitespace-separated list of arbitrary key/value pairs
	167	conveying additional information about the named service in the corresponding TXT resource record
	168	where values are base64-encoded string representing any binary data,
	169	e.g. <literal>data=YW55IGJpbmFyeSBkYXRhCg==</literal>. Keys can contain C-style escape
	170	sequences which get translated upon reading configuration files.
	171	</para>
400f54fb DR	172	<para>This option together with <varname>TxtText=</varname> may be specified more than once, in which
	173	case multiple TXT resource records will be created for the service. If the empty string is assigned to
	174	this option, the list is reset and all prior assignments will have no effect.
	175	</para>
ec07c3c8 AK	176
ec07c3c8 AK	177	<xi:include href="version-info.xml" xpointer="v236"/>
6e73d91e DR	178	</listitem>
	179	</varlistentry>
	180	</variablelist>
	181
	182	</refsect1>
	183
	184	<refsect1>
	185	<title>Examples</title>
	186	<example>
	187	<title>HTTP service</title>
	188
	189	<programlisting># /etc/systemd/dnssd/http.dnssd
	190	[Service]
5526ac50	191	Name=%H
6e73d91e DR	192	Type=_http._tcp
	193	Port=80
	194	TxtText=path=/stats/index.html t=temperature_sensor</programlisting>
	195
	196	<para>This makes the http server running on the host discoverable in the local network
	197	given MulticastDNS is enabled on the network interface.</para>
	198
b69f810c	199	<para>Now the utility <literal>resolvectl</literal> should be able to resolve the
6e73d91e DR	200	service to the host's name:</para>
6e73d91e DR	201
b69f810c	202	<programlisting>$ resolvectl service meteo._http._tcp.local
6e73d91e DR	203	meteo._http._tcp.local: meteo.local:80 [priority=0, weight=0]
	204	169.254.208.106%senp0s21f0u2u4
	205	fe80::213:3bff:fe49:8aa%senp0s21f0u2u4
	206	path=/stats/index.html
	207	t=temperature_sensor
	208	(meteo/_http._tcp/local)
	209
	210	-- Information acquired via protocol mDNS/IPv6 in 4.0ms.
	211	-- Data is authenticated: yes</programlisting>
	212
	213	<para><literal>Avahi</literal> running on a different host in the same local network should see the service as well:</para>
	214
	215	<programlisting>$ avahi-browse -a -r
	216	+ enp3s0 IPv6 meteo Web Site local
	217	+ enp3s0 IPv4 meteo Web Site local
	218	= enp3s0 IPv6 meteo Web Site local
	219	hostname = [meteo.local]
	220	address = [fe80::213:3bff:fe49:8aa]
	221	port = [80]
	222	txt = ["path=/stats/index.html" "t=temperature_sensor"]
	223	= enp3s0 IPv4 meteo Web Site local
	224	hostname = [meteo.local]
	225	address = [169.254.208.106]
	226	port = [80]
	227	txt = ["path=/stats/index.html" "t=temperature_sensor"]</programlisting>
	228
	229	</example>
	230	</refsect1>
	231
	232	<refsect1>
	233	<title>See Also</title>
13a69c12 DT	234	<para><simplelist type="inline">
	235	<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	236	<member><citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
	237	<member><citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	238	</simplelist></para>
6e73d91e DR	239	</refsect1>
	240
	241	</refentry>