1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"hostnamectl" conditional='ENABLE_HOSTNAMED'
25 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
28 <title>hostnamectl
</title>
29 <productname>systemd
</productname>
33 <contrib>Developer
</contrib>
34 <firstname>Lennart
</firstname>
35 <surname>Poettering
</surname>
36 <email>lennart@poettering.net
</email>
42 <refentrytitle>hostnamectl
</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>hostnamectl
</refname>
48 <refpurpose>Control the system hostname
</refpurpose>
53 <command>hostnamectl
</command>
54 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
55 <arg choice=
"req">COMMAND
</arg>
60 <title>Description
</title>
62 <para><command>hostnamectl
</command> may be used to
63 query and change the system hostname and related
66 <para>This tool distinguishes three different
67 hostnames: the high-level
"pretty" hostname which
68 might include all kinds of special characters
69 (e.g.
"Lennart's Laptop"), the static hostname which
70 is used to initialize the kernel hostname at boot
71 (e.g.
"lennarts-laptop"), and the transient hostname
72 which is a default received from network configuration.
73 If a static hostname is set, and is valid (something other
74 than localhost), then the transient hostname is not used.
</para>
76 <para>Note that the pretty hostname has little
77 restrictions on the characters used, while the static
78 and transient hostnames are limited to the usually
79 accepted characters of Internet domain names.
</para>
81 <para>The static hostname is stored in
82 <filename>/etc/hostname
</filename>, see
83 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
84 for more information. The pretty hostname, chassis
85 type, and icon name are stored in
86 <filename>/etc/machine-info
</filename>, see
87 <citerefentry><refentrytitle>machine-info
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
90 <citerefentry><refentrytitle>systemd-firstboot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
91 to initialize the system host name for mounted (but
92 not booted) system images.
</para>
96 <title>Options
</title>
98 <para>The following options are understood:
</para>
102 <term><option>--no-ask-password
</option></term>
104 <listitem><para>Do not query the user
105 for authentication for privileged
106 operations.
</para></listitem>
110 <term><option>--static
</option></term>
111 <term><option>--transient
</option></term>
112 <term><option>--pretty
</option></term>
115 <command>status
</command> is used (or
116 no explicit command is given) and one
117 of those fields is given,
118 <command>hostnamectl
</command> will
119 print out just this selected
123 <command>set-hostname
</command>, only
124 the selected hostname(s) will be
125 updated. When more than one of those
126 options is used, all the specified
127 hostnames will be updated.
131 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
133 <xi:include href=
"standard-options.xml" xpointer=
"help" />
134 <xi:include href=
"standard-options.xml" xpointer=
"version" />
137 <para>The following commands are understood:
</para>
141 <term><command>status
</command></term>
143 <listitem><para>Show current system
145 information.
</para></listitem>
149 <term><command>set-hostname
<replaceable>NAME
</replaceable></command></term>
151 <listitem><para>Set the system
153 <replaceable>NAME
</replaceable>. By
154 default, this will alter the pretty,
155 the static, and the transient hostname
156 alike; however, if one or more of
157 <option>--static
</option>,
158 <option>--transient
</option>,
159 <option>--pretty
</option> are used,
160 only the selected hostnames are
161 changed. If the pretty hostname is
162 being set, and static or transient are
163 being set as well, the specified
164 hostname will be simplified in regards
165 to the character set used before the
166 latter are updated. This is done by
167 replacing spaces with
168 <literal>-
</literal> and removing
169 special characters. This ensures that
170 the pretty and the static hostname are
171 always closely related while still
172 following the validity rules of the
173 specific name. This simplification of
174 the hostname string is not done if
175 only the transient and/or static host
176 names are set, and the pretty host
177 name is left untouched.
</para>
179 <para>Pass the empty string
180 <literal></literal> as the hostname to
181 reset the selected hostnames to their
183 <literal>localhost
</literal>).
</para></listitem>
187 <term><command>set-icon-name
<replaceable>NAME
</replaceable></command></term>
189 <listitem><para>Set the system icon
191 <replaceable>NAME
</replaceable>. The
192 icon name is used by some graphical
193 applications to visualize this host.
194 The icon name should follow the
<ulink
195 url=
"http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon
196 Naming Specification
</ulink>.
</para>
198 <para>Pass an empty string to reset
199 the icon name to the default value,
200 which is determined from chassis type
201 (see below) and possibly other
202 parameters.
</para></listitem>
206 <term><command>set-chassis
<replaceable>TYPE
</replaceable></command></term>
208 <listitem><para>Set the chassis type
209 to
<replaceable>TYPE
</replaceable>.
210 The chassis type is used by some
211 graphical applications to visualize
212 the host or alter user interaction.
213 Currently, the following chassis types
215 <literal>desktop
</literal>,
216 <literal>laptop
</literal>,
217 <literal>server
</literal>,
218 <literal>tablet
</literal>,
219 <literal>handset
</literal>,
220 <literal>watch
</literal>,
221 <literal>embedded
</literal> as well as
222 the special chassis types
223 <literal>vm
</literal> and
224 <literal>container
</literal> for
225 virtualized systems that lack an
226 immediate physical chassis.
</para>
228 <para>Pass an empty string to reset
229 the chassis type to the default value
230 which is determined from the firmware
231 and possibly other parameters.
</para>
236 <term><command>set-deployment
<replaceable>ENVIRONMENT
</replaceable></command></term>
238 <listitem><para>Set the deployment
240 description.
<replaceable>ENVIRONMENT
</replaceable>
241 must be a single word without any
242 control characters. One of the
243 following is suggested:
244 <literal>development
</literal>,
245 <literal>integration
</literal>,
246 <literal>staging
</literal>,
247 <literal>production
</literal>.
250 <para>Pass an empty string to reset to
251 the default empty value.
</para>
256 <term><command>set-location
<replaceable>LOCATION
</replaceable></command></term>
258 <listitem><para>Set the location
259 string for the system, if it is
260 known.
<replaceable>LOCATION
</replaceable>
261 should be a human-friendly, free-form
262 string describing the physical
263 location of the system, if it is known
264 and applicable. This may be as generic
265 as
<literal>Berlin, Germany
</literal>
266 or as specific as
<literal>Left Rack,
267 2nd Shelf
</literal>.
</para>
269 <para>Pass an empty string to reset to
270 the default empty value.
</para>
277 <title>Exit status
</title>
279 <para>On success,
0 is returned, a non-zero failure
280 code otherwise.
</para>
284 <title>See Also
</title>
286 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
289 <citerefentry><refentrytitle>machine-info
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
290 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
291 <citerefentry><refentrytitle>systemd-hostnamed.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
292 <citerefentry><refentrytitle>systemd-firstboot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>