along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'>
+<refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>hostnamectl</title>
<refsynopsisdiv>
<cmdsynopsis>
- <command>hostnamectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
+ <command>hostnamectl</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="req">COMMAND</arg>
</cmdsynopsis>
</refsynopsisdiv>
query and change the system hostname and related
settings.</para>
- <para>This tool distinguishes three different host
- names: the high-level "pretty" hostname which might
- include all kinds of special characters
+ <para>This tool distinguishes three different
+ hostnames: the high-level "pretty" hostname which
+ might include all kinds of special characters
(e.g. "Lennart's Laptop"), the static hostname which
is used to initialize the kernel hostname at boot
(e.g. "lennarts-laptop"), and the transient hostname
- which might be assigned temporarily due to network
- configuration and might revert back to the static
- hostname if network connectivity is lost and is only
- temporarily written to the kernel hostname
- (e.g. "dhcp-47-11").</para>
+ which is a default received from network configuration.
+ If a static hostname is set, and is valid (something other
+ than localhost), then the transient hostname is not used.</para>
<para>Note that the pretty hostname has little
restrictions on the characters used, while the static
and transient hostnames are limited to the usually
- accepted characters of internet domain names.</para>
+ accepted characters of Internet domain names.</para>
- <para>The static host name is stored in
+ <para>The static hostname is stored in
<filename>/etc/hostname</filename>, see
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information. The pretty host name, chassis
- type and icon name are stored in
+ for more information. The pretty hostname, chassis
+ type, and icon name are stored in
<filename>/etc/machine-info</filename>, see
- <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <para>Use
+ <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ to initialize the system host name for mounted (but
+ not booted) system images.</para>
</refsect1>
<refsect1>
<para>The following options are understood:</para>
<variablelist>
- <varlistentry>
- <term><option>-h</option></term>
- <term><option>--help</option></term>
-
- <listitem><para>Prints a short help
- text and exits.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--version</option></term>
-
- <listitem><para>Prints a short version
- string and exits.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--no-ask-password</option></term>
- <listitem><para>Don't query the user
+ <listitem><para>Do not query the user
for authentication for privileged
operations.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><option>-H</option></term>
- <term><option>--host</option></term>
-
- <listitem><para>Execute the operation
- remotely. Specify a hostname, or
- username and hostname separated by @,
- to connect to. This will use SSH to
- talk to a remote
- system.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--static</option></term>
<term><option>--transient</option></term>
<term><option>--pretty</option></term>
<listitem><para>If
- <command>set-hostname</command> is
- invoked and one or more of these
- options are passed only the selected
- hostnames is
- updated.</para></listitem>
+ <command>status</command> is used (or
+ no explicit command is given) and one
+ of those fields is given,
+ <command>hostnamectl</command> will
+ print out just this selected
+ hostname.</para>
+
+ <para>If used with
+ <command>set-hostname</command>, only
+ the selected hostname(s) will be
+ updated. When more than one of those
+ options is used, all the specified
+ hostnames will be updated.
+ </para></listitem>
</varlistentry>
+
+ <xi:include href="user-system-options.xml" xpointer="host" />
+ <xi:include href="user-system-options.xml" xpointer="machine" />
+
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
<para>The following commands are understood:</para>
</varlistentry>
<varlistentry>
- <term><command>set-hostname [NAME]</command></term>
+ <term><command>set-hostname <replaceable>NAME</replaceable></command></term>
<listitem><para>Set the system
- hostname. By default this will alter
- the pretty, the static, and the
- transient hostname alike, however if
- one or more of
+ hostname to
+ <replaceable>NAME</replaceable>. By
+ default, this will alter the pretty,
+ the static, and the transient hostname
+ alike; however, if one or more of
<option>--static</option>,
<option>--transient</option>,
- <option>--pretty</option> are used
+ <option>--pretty</option> are used,
only the selected hostnames are
changed. If the pretty hostname is
being set, and static or transient are
- being set as well the specified host
- name will be simplified in regards to
- the character set used before the
+ being set as well, the specified
+ hostname will be simplified in regards
+ to the character set used before the
latter are updated. This is done by
- replacing spaces by "-" and removing
+ replacing spaces with
+ <literal>-</literal> and removing
special characters. This ensures that
- the pretty and the static hostname
- are always closely related while still
+ the pretty and the static hostname are
+ always closely related while still
following the validity rules of the
specific name. This simplification of
the hostname string is not done if
only the transient and/or static host
names are set, and the pretty host
- name is left untouched. Pass the empty
- string "" as hostname to reset the
- selected hostnames to their default
- (usually
- "localhost").</para></listitem>
+ name is left untouched.</para>
+
+ <para>Pass the empty string
+ <literal></literal> as the hostname to
+ reset the selected hostnames to their
+ default (usually
+ <literal>localhost</literal>).</para></listitem>
</varlistentry>
<varlistentry>
- <term><command>set-icon-name [NAME]</command></term>
+ <term><command>set-icon-name <replaceable>NAME</replaceable></command></term>
<listitem><para>Set the system icon
- name. The icon name is used by some
- graphical applications to visualize
- this host. The icon name should follow
- the <ulink
+ name to
+ <replaceable>NAME</replaceable>. The
+ icon name is used by some graphical
+ applications to visualize this host.
+ The icon name should follow the <ulink
url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon
- Naming Specification</ulink>. Pass an
- empty string to this operation to
- reset the icon name to the default
- value which is determined from chassis
- type (see below) and possibly other
+ Naming Specification</ulink>.</para>
+
+ <para>Pass an empty string to reset
+ the icon name to the default value,
+ which is determined from chassis type
+ (see below) and possibly other
parameters.</para></listitem>
</varlistentry>
<varlistentry>
- <term><command>set-chassis [TYPE]</command></term>
+ <term><command>set-chassis <replaceable>TYPE</replaceable></command></term>
- <listitem><para>Set the chassis
- type. The chassis type is used by some
+ <listitem><para>Set the chassis type
+ to <replaceable>TYPE</replaceable>.
+ The chassis type is used by some
graphical applications to visualize
- the host or alter user
- interaction. Currently, the following
- chassis types are defined:
+ the host or alter user interaction.
+ Currently, the following chassis types
+ are defined:
<literal>desktop</literal>,
<literal>laptop</literal>,
<literal>server</literal>,
<literal>tablet</literal>,
- <literal>handset</literal>, as well as
+ <literal>handset</literal>,
+ <literal>watch</literal>,
+ <literal>embedded</literal> as well as
the special chassis types
<literal>vm</literal> and
<literal>container</literal> for
virtualized systems that lack an
- immediate physical chassis. Pass an
- empty string to this operation to
- reset the chassis type to the default
- value which is determined from the
- firmware and possibly other
- parameters.</para></listitem>
+ immediate physical chassis.</para>
+
+ <para>Pass an empty string to reset
+ the chassis type to the default value
+ which is determined from the firmware
+ and possibly other parameters.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>set-deployment <replaceable>ENVIRONMENT</replaceable></command></term>
+
+ <listitem><para>Set the deployment
+ environment
+ description. <replaceable>ENVIRONMENT</replaceable>
+ must be a single word without any
+ control characters. One of the
+ following is suggested:
+ <literal>development</literal>,
+ <literal>integration</literal>,
+ <literal>staging</literal>,
+ <literal>production</literal>.
+ </para>
+
+ <para>Pass an empty string to reset to
+ the default empty value.</para>
+ </listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>set-location <replaceable>LOCATION</replaceable></command></term>
+
+ <listitem><para>Set the location
+ string for the system, if it is
+ known. <replaceable>LOCATION</replaceable>
+ should be a human-friendly, free-form
+ string describing the physical
+ location of the system, if it is known
+ and applicable. This may be as generic
+ as <literal>Berlin, Germany</literal>
+ or as specific as <literal>Left Rack,
+ 2nd Shelf</literal>.</para>
+
+ <para>Pass an empty string to reset to
+ the default empty value.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
- <para>On success 0 is returned, a non-zero failure
+ <para>On success, 0 is returned, a non-zero failure
code otherwise.</para>
</refsect1>
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff