chiark / gitweb /
man: fix grammatical errors and other formatting issues
[elogind.git] / man / hostnamectl.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'>
25
26         <refentryinfo>
27                 <title>hostnamectl</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>hostnamectl</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>hostnamectl</refname>
47                 <refpurpose>Control the system hostname</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>hostnamectl</command>
53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
54                         <arg choice="req">COMMAND</arg>
55                 </cmdsynopsis>
56         </refsynopsisdiv>
57
58         <refsect1>
59                 <title>Description</title>
60
61                 <para><command>hostnamectl</command> may be used to
62                 query and change the system hostname and related
63                 settings.</para>
64
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>
76
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>
81
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>
89         </refsect1>
90
91         <refsect1>
92                 <title>Options</title>
93
94                 <para>The following options are understood:</para>
95
96                 <variablelist>
97                         <varlistentry>
98                                 <term><option>-h</option></term>
99                                 <term><option>--help</option></term>
100
101                                 <listitem><para>Prints a short help
102                                 text and exits.</para></listitem>
103                         </varlistentry>
104
105                         <varlistentry>
106                                 <term><option>--version</option></term>
107
108                                 <listitem><para>Prints a short version
109                                 string and exits.</para></listitem>
110                         </varlistentry>
111
112                         <varlistentry>
113                                 <term><option>--no-ask-password</option></term>
114
115                                 <listitem><para>Do not query the user
116                                 for authentication for privileged
117                                 operations.</para></listitem>
118                         </varlistentry>
119
120                         <varlistentry>
121                                 <term><option>-P</option></term>
122                                 <term><option>--privileged</option></term>
123
124                                 <listitem><para>Acquire privileges via PolicyKit
125                                 before executing the operation.</para></listitem>
126                         </varlistentry>
127
128                         <varlistentry>
129                                 <term><option>-H</option></term>
130                                 <term><option>--host</option></term>
131
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
136                                 talk to the remote
137                                 system.</para></listitem>
138                         </varlistentry>
139
140                         <varlistentry>
141                                 <term><option>--static</option></term>
142                                 <term><option>--transient</option></term>
143                                 <term><option>--pretty</option></term>
144
145                                 <listitem><para>If
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
151                                 hostname.</para>
152
153                                 <para>If used with
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.
159                                 </para></listitem>
160                         </varlistentry>
161                 </variablelist>
162
163                 <para>The following commands are understood:</para>
164
165                 <variablelist>
166                         <varlistentry>
167                                 <term><command>status</command></term>
168
169                                 <listitem><para>Show current system
170                                 hostname and related
171                                 information.</para></listitem>
172                         </varlistentry>
173
174                         <varlistentry>
175                                 <term><command>set-hostname [NAME]</command></term>
176
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
181                                 one or more of
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>
207                         </varlistentry>
208
209                         <varlistentry>
210                                 <term><command>set-icon-name [NAME]</command></term>
211
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
216                                 the <ulink
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>
224                         </varlistentry>
225
226                         <varlistentry>
227                                 <term><command>set-chassis [TYPE]</command></term>
228
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>
250                         </varlistentry>
251
252                 </variablelist>
253         </refsect1>
254
255         <refsect1>
256                 <title>Exit status</title>
257
258                 <para>On success, 0 is returned, a non-zero failure
259                 code otherwise.</para>
260         </refsect1>
261
262         <refsect1>
263                 <title>See Also</title>
264                 <para>
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>
271                 </para>
272         </refsect1>
273
274 </refentry>