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>