systemd/man/systemd-hostnamed.service.xml
Zbigniew Jędrzejewski-Szmek de31bbc6b1 man/hostnamectl,hostaned,hostname1: adjust the docs to match reality
The semantics were significantly changed in c779a44222
("hostnamed: Fix the way that static and transient host names interact", Feb. 2014),
but when the dbus api documentation was imported much later, it wasn't properly
adjusted to describe those new semantics.

34293dfafd which added systemd.hostname= also
added new behaviour.

Let's ove various bits and pieces around so that they are in more appropriate
places. Drop recommendations to set the hostname for DHCP or mDNS purposes.
Nowadays we expect tools that want to expose some different hostname to the
outside to manage that internally without affecting visible state. Also drop
mentions of DHCP or mDNS directly setting the hostname, since nowadays network
management software is expected to (and does) go through hostnamed.

Also, add a high-level description of semantics. It glosses over the details of
handling of localhost-style names. Later commits will remove this special handling
anyway.
2020-12-16 10:54:57 +01:00

83 lines
3.3 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">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-hostnamed.service" conditional='ENABLE_HOSTNAMED'>
<refentryinfo>
<title>systemd-hostnamed.service</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-hostnamed.service</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-hostnamed.service</refname>
<refname>systemd-hostnamed</refname>
<refpurpose>Daemon to control system hostname from programs</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename>systemd-hostnamed.service</filename></para>
<para><filename>/usr/lib/systemd/systemd-hostnamed</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>systemd-hostnamed.service</filename> is a system service that may be used to change the
system's hostname and related machine metadata from user programs. It is automatically activated on
request and terminates itself when unused.</para>
<para>It currently offers access to five variables:
<itemizedlist>
<listitem><para>The current hostname (Example: <literal>dhcp-192-168-47-11</literal>)</para>
</listitem>
<listitem><para>The static (configured) hostname (Example:
<literal>lennarts-computer</literal>)</para></listitem>
<listitem><para>The pretty hostname (Example: <literal>Lennart's Computer</literal>)</para>
</listitem>
<listitem><para>A suitable icon name for the local host (Example:
<literal>computer-laptop</literal>)</para></listitem>
<listitem><para>A chassis type (Example: <literal>tablet</literal>)</para>
</listitem>
</itemizedlist></para>
<para>The static hostname is stored in <filename>/etc/hostname</filename>, see
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
information. The pretty hostname, chassis type, and icon name are stored in
<filename>/etc/machine-info</filename>, see
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>The tool
<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> is a
command line client to this service.</para>
<para>See
<citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for a description of the D-Bus API.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>