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'>
27 <title>hostnamectl</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>hostnamectl</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>hostnamectl</refname>
47 <refpurpose>Control the system hostname</refpurpose>
52 <command>hostnamectl</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="req">COMMAND</arg>
59 <title>Description</title>
61 <para><command>hostnamectl</command> may be used to
62 query and change the system hostname and related
65 <para>This tool distinguishes three different
66 hostnames: the high-level "pretty" hostname which
67 might include all kinds of special characters
68 (e.g. "Lennart's Laptop"), the static hostname which
69 is used to initialize the kernel hostname at boot
70 (e.g. "lennarts-laptop"), and the transient hostname
71 which might be assigned temporarily due to network
72 configuration and might revert back to the static
73 hostname if network connectivity is lost and is only
74 temporarily written to the kernel hostname
75 (e.g. "dhcp-47-11").</para>
77 <para>Note that the pretty hostname has little
78 restrictions on the characters used, while the static
79 and transient hostnames are limited to the usually
80 accepted characters of Internet domain names.</para>
82 <para>The static hostname is stored in
83 <filename>/etc/hostname</filename>, see
84 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
85 for more information. The pretty hostname, chassis
86 type, and icon name are stored in
87 <filename>/etc/machine-info</filename>, see
88 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
92 <title>Options</title>
94 <para>The following options are understood:</para>
98 <term><option>-h</option></term>
99 <term><option>--help</option></term>
101 <listitem><para>Prints a short help
102 text and exits.</para></listitem>
106 <term><option>--version</option></term>
108 <listitem><para>Prints a short version
109 string and exits.</para></listitem>
113 <term><option>--no-ask-password</option></term>
115 <listitem><para>Do not query the user
116 for authentication for privileged
117 operations.</para></listitem>
121 <term><option>-P</option></term>
122 <term><option>--privileged</option></term>
124 <listitem><para>Acquire privileges via PolicyKit
125 before executing the operation.</para></listitem>
129 <term><option>-H</option></term>
130 <term><option>--host</option></term>
132 <listitem><para>Execute the operation
133 remotely. Specify a hostname, or
134 username and hostname separated by <literal>@</literal>,
135 to connect to. This will use SSH to
137 system.</para></listitem>
141 <term><option>--static</option></term>
142 <term><option>--transient</option></term>
143 <term><option>--pretty</option></term>
146 <command>status</command> is used (or
147 no explicit command is given) and one
148 of those fields is given,
149 <command>hostnamectl</command> will
150 print out just this selected
154 <command>set-hostname</command>, only
155 the selected hostname(s) will be
156 updated. When more than one of those
157 options is used, all the specified
158 hostnames will be updated.
163 <para>The following commands are understood:</para>
167 <term><command>status</command></term>
169 <listitem><para>Show current system
171 information.</para></listitem>
175 <term><command>set-hostname [NAME]</command></term>
177 <listitem><para>Set the system
178 hostname. By default, this will alter
179 the pretty, the static, and the
180 transient hostname alike; however, if
182 <option>--static</option>,
183 <option>--transient</option>,
184 <option>--pretty</option> are used,
185 only the selected hostnames are
186 changed. If the pretty hostname is
187 being set, and static or transient are
188 being set as well, the specified
189 hostname will be simplified in regards
190 to the character set used before the
191 latter are updated. This is done by
192 replacing spaces with
193 <literal>-</literal> and removing
194 special characters. This ensures that
195 the pretty and the static hostname are
196 always closely related while still
197 following the validity rules of the
198 specific name. This simplification of
199 the hostname string is not done if
200 only the transient and/or static host
201 names are set, and the pretty host
202 name is left untouched. Pass the empty
203 string <literal></literal> as the
204 hostname to reset the selected
205 hostnames to their default (usually
206 <literal>localhost</literal>).</para></listitem>
210 <term><command>set-icon-name [NAME]</command></term>
212 <listitem><para>Set the system icon
213 name. The icon name is used by some
214 graphical applications to visualize
215 this host. The icon name should follow
217 url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon
218 Naming Specification</ulink>. Pass an
219 empty string to this operation to
220 reset the icon name to the default
221 value, which is determined from chassis
222 type (see below) and possibly other
223 parameters.</para></listitem>
227 <term><command>set-chassis [TYPE]</command></term>
229 <listitem><para>Set the chassis
230 type. The chassis type is used by some
231 graphical applications to visualize
232 the host or alter user
233 interaction. Currently, the following
234 chassis types are defined:
235 <literal>desktop</literal>,
236 <literal>laptop</literal>,
237 <literal>server</literal>,
238 <literal>tablet</literal>,
239 <literal>handset</literal>, as well as
240 the special chassis types
241 <literal>vm</literal> and
242 <literal>container</literal> for
243 virtualized systems that lack an
244 immediate physical chassis. Pass an
245 empty string to this operation to
246 reset the chassis type to the default
247 value which is determined from the
248 firmware and possibly other
249 parameters.</para></listitem>
256 <title>Exit status</title>
258 <para>On success, 0 is returned, a non-zero failure
259 code otherwise.</para>
263 <title>See Also</title>
265 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
266 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
267 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
268 <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
269 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
270 <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>