]>
Commit | Line | Data |
---|---|---|
6a7e63ef | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
de31bbc6 ZJS |
4 | <!ENTITY % entities SYSTEM "custom-entities.ent" > |
5 | %entities; | |
6 | ]> | |
db9ecf05 | 7 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
6a7e63ef LP |
8 | |
9 | <refentry id="hostname"> | |
798d3a52 ZJS |
10 | <refentryinfo> |
11 | <title>hostname</title> | |
12 | <productname>systemd</productname> | |
798d3a52 ZJS |
13 | </refentryinfo> |
14 | ||
15 | <refmeta> | |
16 | <refentrytitle>hostname</refentrytitle> | |
17 | <manvolnum>5</manvolnum> | |
18 | </refmeta> | |
19 | ||
20 | <refnamediv> | |
21 | <refname>hostname</refname> | |
22 | <refpurpose>Local hostname configuration file</refpurpose> | |
23 | </refnamediv> | |
24 | ||
25 | <refsynopsisdiv> | |
26 | <para><filename>/etc/hostname</filename></para> | |
27 | </refsynopsisdiv> | |
28 | ||
29 | <refsect1> | |
30 | <title>Description</title> | |
31 | ||
de31bbc6 ZJS |
32 | <para>The <filename>/etc/hostname</filename> file configures the name of the local system. Unless |
33 | overridden as described in the next section, | |
34 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will set this | |
35 | hostname during boot using the | |
36 | <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> system | |
37 | call.</para> | |
38 | ||
39 | <para>The file should contain a single newline-terminated hostname string. Comments (lines starting with | |
40 | a <literal>#</literal>) are ignored. The hostname should be composed of up to 64 7-bit ASCII lower-case | |
41 | alphanumeric characters or hyphens forming a valid DNS domain name. It is recommended that this name | |
42 | contains only a single label, i.e. without any dots. Invalid characters will be filtered out in an | |
43 | attempt to make the name valid, but obviously it is recommended to use a valid name and not rely on this | |
44 | filtering.</para> | |
798d3a52 | 45 | |
798d3a52 | 46 | <para>You may use |
de31bbc6 ZJS |
47 | <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to change |
48 | the value of this file during runtime from the command line. Use | |
49 | <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to | |
50 | initialize it on mounted (but not booted) system images.</para> | |
51 | </refsect1> | |
52 | ||
53 | <refsect1> | |
54 | <title>Hostname semantics</title> | |
55 | ||
56 | <para><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and the | |
57 | associated tools will obtain the hostname in the following ways:</para> | |
58 | <itemizedlist> | |
7c52d523 | 59 | <listitem><para>If the kernel command line parameter <varname>systemd.hostname=</varname> specifies a |
de31bbc6 ZJS |
60 | valid hostname, |
61 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will use it | |
62 | to set the hostname during early boot, see | |
63 | <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
64 | </para></listitem> | |
65 | ||
66 | <listitem><para>Otherwise, the "static" hostname specified by <filename>/etc/hostname</filename> as | |
67 | described above will be used.</para></listitem> | |
68 | ||
69 | <listitem><para>Otherwise, a transient hostname may be set during runtime, for example based on | |
70 | information in a DHCP lease, see | |
71 | <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. | |
72 | Both <ulink url="https://developer.gnome.org/NetworkManager/stable/">NetworkManager</ulink> and | |
73 | <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
74 | allow this. Note that | |
75 | <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
76 | gives higher priority to the static hostname, so the transient hostname will only be used if the static | |
77 | hostname is not configured.</para></listitem> | |
78 | ||
79 | <listitem><para>Otherwise, a fallback hostname configured at compilation time will be used | |
80 | (<literal>&FALLBACK_HOSTNAME;</literal>).</para></listitem> | |
81 | ||
82 | <!-- what about the "linux" fallback fallback? --> | |
83 | </itemizedlist> | |
84 | ||
85 | <para>Effectively, the static hostname has higher priority than a transient hostname, which has higher | |
86 | priority than the fallback hostname. Transient hostnames are equivalent, so setting a new transient | |
87 | hostname causes the previous transient hostname to be forgotten. The hostname specified on the kernel | |
88 | command line is like a transient hostname, with the exception that it has higher priority when the | |
89 | machine boots. Also note that those are the semantics implemented by systemd tools, but other programs | |
90 | may also set the hostname.</para> | |
798d3a52 ZJS |
91 | </refsect1> |
92 | ||
93 | <refsect1> | |
94 | <title>History</title> | |
95 | ||
96 | <para>The simple configuration file format of | |
97 | <filename>/etc/hostname</filename> originates from Debian | |
98 | GNU/Linux.</para> | |
99 | </refsect1> | |
100 | ||
101 | <refsect1> | |
102 | <title>See Also</title> | |
13a69c12 DT |
103 | <para><simplelist type="inline"> |
104 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
105 | <member><citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry></member> | |
106 | <member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
107 | <member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
108 | <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
109 | <member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
110 | <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
111 | <member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
112 | <member><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
113 | </simplelist></para> | |
798d3a52 | 114 | </refsect1> |
6a7e63ef LP |
115 | |
116 | </refentry> |