Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 116 insertions, 0 deletions

diff --git a/man/hostname.xml b/man/hostname.xml
new file mode 100644
index 0000000..a3dae72
--- /dev/null
+++ b/man/hostname.xml
@@ -0,0 +1,116 @@
+<?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="hostname">
+  <refentryinfo>
+    <title>hostname</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>hostname</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>hostname</refname>
+    <refpurpose>Local hostname configuration file</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>/etc/hostname</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <filename>/etc/hostname</filename> file configures the name of the local system. Unless
+    overridden as described in the next section,
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will set this
+    hostname during boot using the
+    <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
+    call.</para>
+
+    <para>The file should contain a single newline-terminated hostname string. Comments (lines starting with
+    a <literal>#</literal>) are ignored. The hostname should be composed of up to 64 7-bit ASCII lower-case
+    alphanumeric characters or hyphens forming a valid DNS domain name. It is recommended that this name
+    contains only a single label, i.e. without any dots. Invalid characters will be filtered out in an
+    attempt to make the name valid, but obviously it is recommended to use a valid name and not rely on this
+    filtering.</para>
+
+    <para>You may use
+    <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to change
+    the value of this file during runtime from the command line. Use
+    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
+    initialize it on mounted (but not booted) system images.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Hostname semantics</title>
+
+    <para><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and the
+    associated tools will obtain the hostname in the following ways:</para>
+    <itemizedlist>
+      <listitem><para>If the kernel command line parameter <varname>systemd.hostname=</varname> specifies a
+      valid hostname,
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will use it
+      to set the hostname during early boot, see
+      <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      </para></listitem>
+
+      <listitem><para>Otherwise, the "static" hostname specified by <filename>/etc/hostname</filename> as
+      described above will be used.</para></listitem>
+
+      <listitem><para>Otherwise, a transient hostname may be set during runtime, for example based on
+      information in a DHCP lease, see
+      <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+      Both <ulink url="https://developer.gnome.org/NetworkManager/stable/">NetworkManager</ulink> and
+      <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      allow this. Note that
+      <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      gives higher priority to the static hostname, so the transient hostname will only be used if the static
+      hostname is not configured.</para></listitem>
+
+      <listitem><para>Otherwise, a fallback hostname configured at compilation time will be used
+      (<literal>&FALLBACK_HOSTNAME;</literal>).</para></listitem>
+
+      <!-- what about the "linux" fallback fallback? -->
+    </itemizedlist>
+
+    <para>Effectively, the static hostname has higher priority than a transient hostname, which has higher
+    priority than the fallback hostname. Transient hostnames are equivalent, so setting a new transient
+    hostname causes the previous transient hostname to be forgotten. The hostname specified on the kernel
+    command line is like a transient hostname, with the exception that it has higher priority when the
+    machine boots. Also note that those are the semantics implemented by systemd tools, but other programs
+    may also set the hostname.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>History</title>
+
+    <para>The simple configuration file format of
+    <filename>/etc/hostname</filename> originates from Debian
+    GNU/Linux.</para>
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para>
+        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      </para>
+  </refsect1>
+
+</refentry>