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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2012 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'
  28     xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>hostnamectl</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>Lennart</firstname>
  38         <surname>Poettering</surname>
  39         <email>lennart@poettering.net</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>hostnamectl</refentrytitle>
  46     <manvolnum>1</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>hostnamectl</refname>
  51     <refpurpose>Control the system hostname</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>hostnamectl</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58       <arg choice="req">COMMAND</arg>
  59     </cmdsynopsis>
  60   </refsynopsisdiv>
  61
  62   <refsect1>
  63     <title>Description</title>
  64
  65     <para><command>hostnamectl</command> may be used to query and
  66     change the system hostname and related settings.</para>
  67
  68     <para>This tool distinguishes three different hostnames: the
  69     high-level "pretty" hostname which might include all kinds of
  70     special characters (e.g. "Lennart's Laptop"), the static hostname
  71     which is used to initialize the kernel hostname at boot (e.g.
  72     "lennarts-laptop"), and the transient hostname which is a default
  73     received from network configuration. If a static hostname is set,
  74     and is valid (something other than localhost), then the transient
  75     hostname is not used.</para>
  76
  77     <para>Note that the pretty hostname has little restrictions on the
  78     characters used, while the static and transient hostnames are
  79     limited to the usually accepted characters of Internet domain
  80     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 type, and icon
  86     name are stored in <filename>/etc/machine-info</filename>, see
  87     <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  88
  89     <para>Use
  90     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  91     to initialize the system host name for mounted (but not booted)
  92     system images.</para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Options</title>
  97
  98     <para>The following options are understood:</para>
  99
 100     <variablelist>
 101       <varlistentry>
 102         <term><option>--no-ask-password</option></term>
 103
 104         <listitem><para>Do not query the user for authentication for
 105         privileged operations.</para></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><option>--static</option></term>
 110         <term><option>--transient</option></term>
 111         <term><option>--pretty</option></term>
 112
 113         <listitem><para>If <command>status</command> is used (or no
 114         explicit command is given) and one of those fields is given,
 115         <command>hostnamectl</command> will print out just this
 116         selected hostname.</para>
 117
 118         <para>If used with <command>set-hostname</command>, only the
 119         selected hostname(s) will be updated. When more than one of
 120         those options is used, all the specified hostnames will be
 121         updated. </para></listitem>
 122       </varlistentry>
 123
 124       <xi:include href="user-system-options.xml" xpointer="host" />
 125       <xi:include href="user-system-options.xml" xpointer="machine" />
 126
 127       <xi:include href="standard-options.xml" xpointer="help" />
 128       <xi:include href="standard-options.xml" xpointer="version" />
 129     </variablelist>
 130
 131     <para>The following commands are understood:</para>
 132
 133     <variablelist>
 134       <varlistentry>
 135         <term><command>status</command></term>
 136
 137         <listitem><para>Show current system
 138         hostname and related
 139         information.</para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><command>set-hostname <replaceable>NAME</replaceable></command></term>
 144
 145         <listitem><para>Set the system hostname to
 146         <replaceable>NAME</replaceable>. By default, this will alter
 147         the pretty, the static, and the transient hostname alike;
 148         however, if one or more of <option>--static</option>,
 149         <option>--transient</option>, <option>--pretty</option> are
 150         used, only the selected hostnames are changed. If the pretty
 151         hostname is being set, and static or transient are being set
 152         as well, the specified hostname will be simplified in regards
 153         to the character set used before the latter are updated. This
 154         is done by replacing spaces with <literal>-</literal> and
 155         removing special characters. This ensures that the pretty and
 156         the static hostname are always closely related while still
 157         following the validity rules of the specific name. This
 158         simplification of the hostname string is not done if only the
 159         transient and/or static host names are set, and the pretty
 160         host name is left untouched.</para>
 161
 162         <para>Pass the empty string <literal></literal> as the
 163         hostname to reset the selected hostnames to their default
 164         (usually <literal>localhost</literal>).</para></listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><command>set-icon-name <replaceable>NAME</replaceable></command></term>
 169
 170         <listitem><para>Set the system icon name to
 171         <replaceable>NAME</replaceable>. The icon name is used by some
 172         graphical applications to visualize this host. The icon name
 173         should follow the <ulink
 174         url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon
 175         Naming Specification</ulink>.</para>
 176
 177         <para>Pass an empty string to reset the icon name to the
 178         default value, which is determined from chassis type (see
 179         below) and possibly other parameters.</para></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><command>set-chassis <replaceable>TYPE</replaceable></command></term>
 184
 185         <listitem><para>Set the chassis type to
 186         <replaceable>TYPE</replaceable>. The chassis type is used by
 187         some graphical applications to visualize the host or alter
 188         user interaction. Currently, the following chassis types are
 189         defined:
 190         <literal>desktop</literal>,
 191         <literal>laptop</literal>,
 192         <literal>server</literal>,
 193         <literal>tablet</literal>,
 194         <literal>handset</literal>,
 195         <literal>watch</literal>,
 196         <literal>embedded</literal>,
 197         as well as the special chassis types
 198         <literal>vm</literal> and
 199         <literal>container</literal> for virtualized systems that lack
 200         an immediate physical chassis.</para>
 201
 202         <para>Pass an empty string to reset the chassis type to the
 203         default value which is determined from the firmware and
 204         possibly other parameters.</para>
 205         </listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><command>set-deployment <replaceable>ENVIRONMENT</replaceable></command></term>
 210
 211         <listitem><para>Set the deployment environment description.
 212         <replaceable>ENVIRONMENT</replaceable> must be a single word
 213         without any control characters. One of the following is
 214         suggested:
 215         <literal>development</literal>,
 216         <literal>integration</literal>,
 217         <literal>staging</literal>,
 218         <literal>production</literal>.
 219         </para>
 220
 221         <para>Pass an empty string to reset to the default empty
 222         value.</para>
 223         </listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><command>set-location <replaceable>LOCATION</replaceable></command></term>
 228
 229         <listitem><para>Set the location string for the system, if it
 230         is known. <replaceable>LOCATION</replaceable> should be a
 231         human-friendly, free-form string describing the physical
 232         location of the system, if it is known and applicable. This
 233         may be as generic as <literal>Berlin, Germany</literal> or as
 234         specific as <literal>Left Rack, 2nd Shelf</literal>.</para>
 235
 236         <para>Pass an empty string to reset to the default empty
 237         value.</para>
 238         </listitem>
 239       </varlistentry>
 240     </variablelist>
 241   </refsect1>
 242
 243   <refsect1>
 244     <title>Exit status</title>
 245
 246     <para>On success, 0 is returned, a non-zero failure code
 247     otherwise.</para>
 248   </refsect1>
 249
 250   <refsect1>
 251     <title>See Also</title>
 252     <para>
 253       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 257       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 260     </para>
 261   </refsect1>
 262
 263 </refentry>