man/systemd.dnssd.xml

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