diff options
Diffstat (limited to 'man/hostname.xml')
| -rw-r--r-- | man/hostname.xml | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/man/hostname.xml b/man/hostname.xml new file mode 100644 index 0000000..d050703 --- /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 commandline 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> |