369 lines
20 KiB
XML
369 lines
20 KiB
XML
<?xml version="1.0"?>
|
||
<!--*-nxml-*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
||
%entities;
|
||
]>
|
||
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
||
|
||
<refentry id="org.freedesktop.hostname1" conditional='ENABLE_HOSTNAMED'
|
||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
<refentryinfo>
|
||
<title>org.freedesktop.hostname1</title>
|
||
<productname>systemd</productname>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>org.freedesktop.hostname1</refentrytitle>
|
||
<manvolnum>5</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>org.freedesktop.hostname1</refname>
|
||
<refpurpose>The D-Bus interface of systemd-hostnamed</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsect1>
|
||
<title>Introduction</title>
|
||
|
||
<para>
|
||
<citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
is a system service that can be used to control the hostname and related machine metadata from user
|
||
programs. This page describes the hostname semantics and the D-Bus interface.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>The D-Bus API</title>
|
||
|
||
<para>The service exposes the following interfaces on the bus:</para>
|
||
|
||
<programlisting executable="systemd-hostnamed" node="/org/freedesktop/hostname1" interface="org.freedesktop.hostname1">
|
||
node /org/freedesktop/hostname1 {
|
||
interface org.freedesktop.hostname1 {
|
||
methods:
|
||
SetHostname(in s hostname,
|
||
in b interactive);
|
||
SetStaticHostname(in s hostname,
|
||
in b interactive);
|
||
SetPrettyHostname(in s hostname,
|
||
in b interactive);
|
||
SetIconName(in s icon,
|
||
in b interactive);
|
||
SetChassis(in s chassis,
|
||
in b interactive);
|
||
SetDeployment(in s deployment,
|
||
in b interactive);
|
||
SetLocation(in s location,
|
||
in b interactive);
|
||
GetProductUUID(in b interactive,
|
||
out ay uuid);
|
||
properties:
|
||
readonly s Hostname = '...';
|
||
readonly s StaticHostname = '...';
|
||
readonly s PrettyHostname = '...';
|
||
readonly s IconName = '...';
|
||
readonly s Chassis = '...';
|
||
readonly s Deployment = '...';
|
||
readonly s Location = '...';
|
||
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
||
readonly s KernelName = '...';
|
||
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
||
readonly s KernelRelease = '...';
|
||
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
||
readonly s KernelVersion = '...';
|
||
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
||
readonly s OperatingSystemPrettyName = '...';
|
||
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
||
readonly s OperatingSystemCPEName = '...';
|
||
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
||
readonly s HomeURL = '...';
|
||
};
|
||
interface org.freedesktop.DBus.Peer { ... };
|
||
interface org.freedesktop.DBus.Introspectable { ... };
|
||
interface org.freedesktop.DBus.Properties { ... };
|
||
};
|
||
</programlisting>
|
||
|
||
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
||
|
||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
|
||
|
||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetHostname()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetStaticHostname()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetPrettyHostname()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetIconName()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetChassis()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetDeployment()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="SetLocation()"/>
|
||
|
||
<variablelist class="dbus-method" generated="True" extra-ref="GetProductUUID()"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="Hostname"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="StaticHostname"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="PrettyHostname"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="IconName"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="Chassis"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="Deployment"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="Location"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="KernelName"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="KernelRelease"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="KernelVersion"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemPrettyName"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemCPEName"/>
|
||
|
||
<variablelist class="dbus-property" generated="True" extra-ref="HomeURL"/>
|
||
|
||
<!--End of Autogenerated section-->
|
||
|
||
<para>Whenever the hostname or other metadata is changed via the daemon,
|
||
<function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname
|
||
using this interface is authenticated via
|
||
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Semantics</title>
|
||
|
||
<para>The <emphasis>static (configured) hostname</emphasis> is the one configured in
|
||
<filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the
|
||
current hostname as returned by the
|
||
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
system call. If no hostname is configured this property will be the empty string. Setting this property
|
||
to the empty string will remove <filename>/etc/hostname</filename>. This property should be an
|
||
internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
|
||
|
||
<para>The <emphasis>transient (dynamic) hostname</emphasis> is the one configured via the kernel's
|
||
<citerefentry project="man-pages"><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||
It can be different from the static hostname if DHCP or mDNS have been configured to change the name
|
||
based on network information. <!-- FIXME: it's not DHCP that configures this... -->
|
||
This property is never empty. If no hostname is set this will default to
|
||
<literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the
|
||
empty string will reset the dynamic hostname to the static hostname. If no static hostname is
|
||
configured the dynamic hostname will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This property
|
||
should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
|
||
|
||
<para>The <emphasis>pretty hostname</emphasis> is a free-form UTF-8 hostname for presentation to the
|
||
user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync.
|
||
I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be
|
||
<literal>lennarts-computer</literal>. If no pretty hostname is set this setting will be the empty
|
||
string. Applications should then find a suitable fallback, such as the dynamic hostname.</para>
|
||
|
||
<para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set,
|
||
information such as the chassis type (see below) is used to find a suitable fallback icon name
|
||
(i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the
|
||
chassis information). If no such data is available, the empty string is returned. In that case an application
|
||
should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set
|
||
to the empty string, the automatic fallback name selection is enabled again.</para>
|
||
|
||
<para>The <emphasis>chassis type</emphasis> should be one of the currently defined chassis types:
|
||
<literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>,
|
||
<literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types
|
||
<literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases
|
||
the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to
|
||
this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if
|
||
it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of
|
||
the chassis type from firmware information.</para>
|
||
|
||
<para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a
|
||
short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent
|
||
out for changes made directly on the files (as in: administrator edits the files with vi). This is
|
||
the intended behavior: manual configuration changes should require manual reloading.</para>
|
||
|
||
<para>The transient (dynamic) hostname maps directly to the kernel hostname. This hostname should be
|
||
assumed to be highly dynamic, and hence should be watched directly, without depending on
|
||
<function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. To accomplish
|
||
this, open <filename>/proc/sys/kernel/hostname</filename> and
|
||
<citerefentry project="man-pages"><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again:
|
||
this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed)
|
||
hostname.</para>
|
||
|
||
<para>Applications may read the hostname data directly if hostname change notifications
|
||
are not necessary. Use
|
||
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||
<filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and
|
||
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
for that. For more information on these files and syscalls see the respective man pages.</para>
|
||
|
||
<refsect2>
|
||
<title>Methods and Properties</title>
|
||
|
||
<para><function>SetHostname()</function> sets the transient (dynamic) hostname which is exposed by the
|
||
<varname>Hostname</varname> property. If empty, the transient hostname is set to the static hostname.
|
||
</para>
|
||
|
||
<para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the
|
||
<varname>StaticHostname</varname> property. If empty, the built-in default of
|
||
<literal>&FALLBACK_HOSTNAME;</literal> is used.</para>
|
||
|
||
<para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the
|
||
<varname>PrettyHostname</varname> property.</para>
|
||
|
||
<para><function>SetIconName()</function>, <function>SetChassis()</function>,
|
||
<function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties
|
||
<varname>IconName</varname> (the name of the icon representing for the machine),
|
||
<varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system
|
||
deployment environment), and <varname>Location</varname> (physical system location), respectively.
|
||
</para>
|
||
|
||
<para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>,
|
||
<varname>Deployment</varname>, and <varname>Location</varname> are stored in
|
||
<filename>/etc/machine-info</filename>. See
|
||
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||
the semantics of those settings.</para>
|
||
|
||
<para><function>GetProductUUID()</function> returns the "product uuid" as exposed by the kernel based
|
||
on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly
|
||
requires root privileges, and this method allows access to unprivileged clients through the polkit
|
||
framework.</para>
|
||
|
||
<para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and
|
||
<varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release
|
||
(e.g. <literal>5.0.0-11</literal>), and version (i.e. the build number, e.g. <literal>#11</literal>) as
|
||
reported by
|
||
<citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
|
||
<varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and
|
||
<varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and
|
||
<varname>HOME_URL=</varname> fields from
|
||
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
|
||
purpose of those properties is to allow remote clients to access this information over D-Bus. Local
|
||
clients can access the information directly.</para>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Security</title>
|
||
|
||
<para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit
|
||
should interactively ask the user for authentication credentials if required.</para>
|
||
|
||
<para>The polkit action for <function>SetHostname()</function> is
|
||
<interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
|
||
<function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
|
||
<interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
|
||
<function>SetIconName()</function>, <function>SetChassis()</function>, <function>SetDeployment()</function>
|
||
and <function>SetLocation()</function> it is
|
||
<interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Recommendations</title>
|
||
|
||
<para>Here are three examples that show how the pretty hostname and the icon name should be used:
|
||
<itemizedlist>
|
||
<listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass
|
||
the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon
|
||
on each service. This is especially useful for WebDAV applications or UPnP media sharing.
|
||
</para></listitem>
|
||
|
||
<listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem>
|
||
|
||
<listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname
|
||
if set, and the icon with the icon name, if it is set.</para></listitem>
|
||
</itemizedlist></para>
|
||
|
||
<para>To properly handle name lookups with changing local hostnames without having to edit
|
||
<filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
|
||
with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||
</para>
|
||
|
||
<para>A client that wants to change the local hostname for DHCP/mDNS should invoke
|
||
<code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
|
||
<code>SetHostname("")</code>.</para>
|
||
|
||
<para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty
|
||
name:
|
||
<itemizedlist>
|
||
<listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them,
|
||
or replace them with <literal>-</literal>.</para></listitem>
|
||
|
||
<listitem><para>It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way
|
||
these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>.
|
||
Strip other chars, or try to replace them in some smart way with chars from this set, for example
|
||
<literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as the replacement for all
|
||
punctuation characters and whitespace.</para></listitem>
|
||
|
||
<listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as
|
||
the first or last char.</para></listitem>
|
||
|
||
<listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem>
|
||
|
||
<listitem><para>If after stripping special chars the empty string is the result, you can pass this
|
||
as-is to <filename>systemd-hostnamed</filename> in which case it will automatically use
|
||
<literal>&FALLBACK_HOSTNAME;</literal>.</para></listitem>
|
||
|
||
<listitem><para>Uppercase charaacters should be replaced with their lowercase equivalents.
|
||
</para></listitem>
|
||
</itemizedlist></para>
|
||
|
||
<para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass
|
||
they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename>
|
||
will also accept <literal>_</literal> in the hostname, but we recommend not using this to avoid clashes
|
||
with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but
|
||
because of the DNS label limitations, we recommend not making use of this.</para>
|
||
|
||
<para>Here are a couple of example conversions:
|
||
<itemizedlist>
|
||
<listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem>
|
||
<listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem>
|
||
<listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem>
|
||
<listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem>
|
||
<listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem>
|
||
<listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem>
|
||
<listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem>
|
||
</itemizedlist></para>
|
||
|
||
<para>Of course, an already valid internet hostname label you enter and pass through this
|
||
conversion should stay unmodified, so that users have direct control of it, if they want — by simply
|
||
ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
|
||
name.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Versioning</title>
|
||
|
||
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
|
||
the usual interface versioning guidelines</ulink>.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Examples</title>
|
||
|
||
<example>
|
||
<title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title>
|
||
|
||
<programlisting>$ gdbus introspect --system \
|
||
--dest org.freedesktop.hostname1 \
|
||
--object-path /org/freedesktop/hostname1
|
||
</programlisting>
|
||
</example>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>See also</title>
|
||
|
||
<para>David Zeuthen's original Fedora
|
||
<ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para>
|
||
</refsect1>
|
||
</refentry>
|