man/org.freedesktop.hostname1.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   5 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   6 %entities;
   7 ]>
   8 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   9
  10 <refentry id="org.freedesktop.hostname1" conditional='ENABLE_HOSTNAMED'
  11     xmlns:xi="http://www.w3.org/2001/XInclude">
  12   <refentryinfo>
  13     <title>org.freedesktop.hostname1</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>org.freedesktop.hostname1</refentrytitle>
  19     <manvolnum>5</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>org.freedesktop.hostname1</refname>
  24     <refpurpose>The D-Bus interface of systemd-hostnamed</refpurpose>
  25   </refnamediv>
  26
  27   <refsect1>
  28     <title>Introduction</title>
  29
  30     <para>
  31     <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  32     is a system service that can be used to control the hostname and related machine metadata from user
  33     programs. This page describes the hostname semantics and the D-Bus interface.</para>
  34   </refsect1>
  35
  36   <refsect1>
  37     <title>The D-Bus API</title>
  38
  39     <para>The service exposes the following interfaces on the bus:</para>
  40
  41     <programlisting executable="systemd-hostnamed" node="/org/freedesktop/hostname1" interface="org.freedesktop.hostname1">
  42 node /org/freedesktop/hostname1 {
  43   interface org.freedesktop.hostname1 {
  44     methods:
  45       SetHostname(in  s hostname,
  46                   in  b interactive);
  47       SetStaticHostname(in  s hostname,
  48                         in  b interactive);
  49       SetPrettyHostname(in  s hostname,
  50                         in  b interactive);
  51       SetIconName(in  s icon,
  52                   in  b interactive);
  53       SetChassis(in  s chassis,
  54                  in  b interactive);
  55       SetDeployment(in  s deployment,
  56                     in  b interactive);
  57       SetLocation(in  s location,
  58                   in  b interactive);
  59       GetProductUUID(in  b interactive,
  60                      out ay uuid);
  61     properties:
  62       readonly s Hostname = '...';
  63       readonly s StaticHostname = '...';
  64       readonly s PrettyHostname = '...';
  65       readonly s IconName = '...';
  66       readonly s Chassis = '...';
  67       readonly s Deployment = '...';
  68       readonly s Location = '...';
  69       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
  70       readonly s KernelName = '...';
  71       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
  72       readonly s KernelRelease = '...';
  73       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
  74       readonly s KernelVersion = '...';
  75       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
  76       readonly s OperatingSystemPrettyName = '...';
  77       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
  78       readonly s OperatingSystemCPEName = '...';
  79       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
  80       readonly s HomeURL = '...';
  81   };
  82   interface org.freedesktop.DBus.Peer { ... };
  83   interface org.freedesktop.DBus.Introspectable { ... };
  84   interface org.freedesktop.DBus.Properties { ... };
  85 };
  86     </programlisting>
  87
  88     <!--Autogenerated cross-references for systemd.directives, do not edit-->
  89
  90     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
  91
  92     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
  93
  94     <variablelist class="dbus-method" generated="True" extra-ref="SetHostname()"/>
  95
  96     <variablelist class="dbus-method" generated="True" extra-ref="SetStaticHostname()"/>
  97
  98     <variablelist class="dbus-method" generated="True" extra-ref="SetPrettyHostname()"/>
  99
 100     <variablelist class="dbus-method" generated="True" extra-ref="SetIconName()"/>
 101
 102     <variablelist class="dbus-method" generated="True" extra-ref="SetChassis()"/>
 103
 104     <variablelist class="dbus-method" generated="True" extra-ref="SetDeployment()"/>
 105
 106     <variablelist class="dbus-method" generated="True" extra-ref="SetLocation()"/>
 107
 108     <variablelist class="dbus-method" generated="True" extra-ref="GetProductUUID()"/>
 109
 110     <variablelist class="dbus-property" generated="True" extra-ref="Hostname"/>
 111
 112     <variablelist class="dbus-property" generated="True" extra-ref="StaticHostname"/>
 113
 114     <variablelist class="dbus-property" generated="True" extra-ref="PrettyHostname"/>
 115
 116     <variablelist class="dbus-property" generated="True" extra-ref="IconName"/>
 117
 118     <variablelist class="dbus-property" generated="True" extra-ref="Chassis"/>
 119
 120     <variablelist class="dbus-property" generated="True" extra-ref="Deployment"/>
 121
 122     <variablelist class="dbus-property" generated="True" extra-ref="Location"/>
 123
 124     <variablelist class="dbus-property" generated="True" extra-ref="KernelName"/>
 125
 126     <variablelist class="dbus-property" generated="True" extra-ref="KernelRelease"/>
 127
 128     <variablelist class="dbus-property" generated="True" extra-ref="KernelVersion"/>
 129
 130     <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemPrettyName"/>
 131
 132     <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemCPEName"/>
 133
 134     <variablelist class="dbus-property" generated="True" extra-ref="HomeURL"/>
 135
 136     <!--End of Autogenerated section-->
 137
 138     <para>Whenever the hostname or other metadata is changed via the daemon,
 139     <function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname
 140     using this interface is authenticated via
 141     <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Semantics</title>
 146
 147     <para>The <emphasis>static (configured) hostname</emphasis> is the one configured in
 148     <filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the
 149     current hostname as returned by the
 150     <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 151     system call. If no hostname is configured this property will be the empty string. Setting this property
 152     to the empty string will remove <filename>/etc/hostname</filename>. This property should be an
 153     internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
 154
 155     <para>The <emphasis>transient (dynamic) hostname</emphasis> is the one configured via the kernel's
 156     <citerefentry project="man-pages"><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 157     It can be different from the static hostname if DHCP or mDNS have been configured to change the name
 158     based on network information. <!-- FIXME: it's not DHCP that configures this... -->
 159     This property is never empty. If no hostname is set this will default to
 160     <literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the
 161     empty string will reset the dynamic hostname to the static hostname. If no static hostname is
 162     configured the dynamic hostname will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This property
 163     should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
 164
 165     <para>The <emphasis>pretty hostname</emphasis> is a free-form UTF-8 hostname for presentation to the
 166     user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync.
 167     I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be
 168     <literal>lennarts-computer</literal>. If no pretty hostname is set this setting will be the empty
 169     string. Applications should then find a suitable fallback, such as the dynamic hostname.</para>
 170
 171     <para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set,
 172     information such as the chassis type (see below) is used to find a suitable fallback icon name
 173     (i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the
 174     chassis information). If no such data is available, the empty string is returned. In that case an application
 175     should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set
 176     to the empty string, the automatic fallback name selection is enabled again.</para>
 177
 178     <para>The <emphasis>chassis type</emphasis> should be one of the currently defined chassis types:
 179     <literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>,
 180     <literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types
 181     <literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases
 182     the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to
 183     this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if
 184     it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of
 185     the chassis type from firmware information.</para>
 186
 187     <para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a
 188     short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent
 189     out for changes made directly on the files (as in: administrator edits the files with vi). This is
 190     the intended behavior: manual configuration changes should require manual reloading.</para>
 191
 192     <para>The transient (dynamic) hostname maps directly to the kernel hostname. This hostname should be
 193     assumed to be highly dynamic, and hence should be watched directly, without depending on
 194     <function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. To accomplish
 195     this, open <filename>/proc/sys/kernel/hostname</filename> and
 196     <citerefentry project="man-pages"><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 197     for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again:
 198     this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed)
 199     hostname.</para>
 200
 201     <para>Applications may read the hostname data directly if hostname change notifications
 202     are not necessary. Use
 203     <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 204     <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and
 205     <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 206     for that. For more information on these files and syscalls see the respective man pages.</para>
 207
 208     <refsect2>
 209       <title>Methods and Properties</title>
 210
 211       <para><function>SetHostname()</function> sets the transient (dynamic) hostname which is exposed by the
 212       <varname>Hostname</varname> property. If empty, the transient hostname is set to the static hostname.
 213       </para>
 214
 215       <para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the
 216       <varname>StaticHostname</varname> property. If empty, the built-in default of
 217       <literal>&FALLBACK_HOSTNAME;</literal> is used.</para>
 218
 219       <para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the
 220       <varname>PrettyHostname</varname> property.</para>
 221
 222       <para><function>SetIconName()</function>, <function>SetChassis()</function>,
 223       <function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties
 224       <varname>IconName</varname> (the name of the icon representing for the machine),
 225       <varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system
 226       deployment environment), and <varname>Location</varname> (physical system location), respectively.
 227       </para>
 228
 229       <para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>,
 230       <varname>Deployment</varname>, and <varname>Location</varname> are stored in
 231       <filename>/etc/machine-info</filename>. See
 232       <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 233       the semantics of those settings.</para>
 234
 235       <para><function>GetProductUUID()</function> returns the "product uuid" as exposed by the kernel based
 236       on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly
 237       requires root privileges, and this method allows access to unprivileged clients through the polkit
 238       framework.</para>
 239
 240       <para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and
 241       <varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release
 242       (e.g. <literal>5.0.0-11</literal>), and version (i.e. the build number, e.g. <literal>#11</literal>) as
 243       reported by
 244       <citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
 245       <varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and
 246       <varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and
 247       <varname>HOME_URL=</varname> fields from
 248       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 249       purpose of those properties is to allow remote clients to access this information over D-Bus. Local
 250       clients can access the information directly.</para>
 251     </refsect2>
 252
 253     <refsect2>
 254       <title>Security</title>
 255
 256       <para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit
 257       should interactively ask the user for authentication credentials if required.</para>
 258
 259       <para>The polkit action for <function>SetHostname()</function> is
 260       <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
 261       <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
 262       <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
 263       <function>SetIconName()</function> and <function>SetChassis()</function> it is
 264       <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
 265     </refsect2>
 266   </refsect1>
 267
 268   <refsect1>
 269     <title>Recommendations</title>
 270
 271     <para>Here are three examples that show how the pretty hostname and the icon name should be used:
 272     <itemizedlist>
 273       <listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass
 274       the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon
 275       on each service. This is especially useful for WebDAV applications or UPnP media sharing.
 276       </para></listitem>
 277
 278       <listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem>
 279
 280       <listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname
 281       if set, and the icon with the icon name, if it is set.</para></listitem>
 282     </itemizedlist></para>
 283
 284     <para>To properly handle name lookups with changing local hostnames without having to edit
 285     <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
 286     with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 287     </para>
 288
 289     <para>A client that wants to change the local hostname for DHCP/mDNS should invoke
 290     <code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
 291     <code>SetHostname("")</code>.</para>
 292
 293     <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty
 294     name:
 295     <itemizedlist>
 296       <listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them,
 297       or replace them with <literal>-</literal>.</para></listitem>
 298
 299       <listitem><para>It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way
 300       these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>.
 301       Strip other chars, or try to replace them in some smart way with chars from this set, for example
 302       <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as the replacement for all
 303       punctuation characters and whitespace.</para></listitem>
 304
 305       <listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as
 306       the first or last char.</para></listitem>
 307
 308       <listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem>
 309
 310       <listitem><para>If after stripping special chars the empty string is the result, you can pass this
 311       as-is to <filename>systemd-hostnamed</filename> in which case it will automatically use
 312       <literal>&FALLBACK_HOSTNAME;</literal>.</para></listitem>
 313
 314       <listitem><para>Uppercase charaacters should be replaced with their lowercase equivalents.
 315       </para></listitem>
 316     </itemizedlist></para>
 317
 318     <para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass
 319     they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename>
 320     will also accept <literal>_</literal> in the hostname, but we recommend not using this to avoid clashes
 321     with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but
 322     because of the DNS label limitations, we recommend not making use of this.</para>
 323
 324     <para>Here are a couple of example conversions:
 325     <itemizedlist>
 326       <listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem>
 327       <listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem>
 328       <listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem>
 329       <listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem>
 330       <listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem>
 331       <listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem>
 332       <listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem>
 333     </itemizedlist></para>
 334
 335     <para>Of course, an already valid internet hostname label you enter and pass through this
 336     conversion should stay unmodified, so that users have direct control of it, if they want — by simply
 337     ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
 338     name.</para>
 339   </refsect1>
 340
 341   <refsect1>
 342     <title>Versioning</title>
 343
 344     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 345     the usual interface versioning guidelines</ulink>.</para>
 346   </refsect1>
 347
 348   <refsect1>
 349     <title>Examples</title>
 350
 351     <example>
 352       <title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title>
 353
 354       <programlisting>$ gdbus introspect --system \
 355   --dest org.freedesktop.hostname1 \
 356   --object-path /org/freedesktop/hostname1
 357       </programlisting>
 358     </example>
 359   </refsect1>
 360
 361   <refsect1>
 362     <title>See also</title>
 363
 364     <para>David Zeuthen's original Fedora
 365     <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para>
 366   </refsect1>
 367 </refentry>