| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ |
| <!ENTITY % entities SYSTEM "custom-entities.ent" > |
| %entities; |
| ]> |
| <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
| |
| <refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED' |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| |
| <refentryinfo> |
| <title>hostnamectl</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>hostnamectl</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>hostnamectl</refname> |
| <refpurpose>Control the system hostname</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>hostnamectl</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="req">COMMAND</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><command>hostnamectl</command> may be used to query and change the system hostname and related |
| settings.</para> |
| |
| <para><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| and this tool distinguish 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 the |
| user-configured hostname (e.g. "lennarts-laptop"), and the transient hostname which is a fallback value |
| received from network configuration (e.g. "node12345678"). If a static hostname is set to a valid value, |
| then the transient hostname is not used.</para> |
| |
| <para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and |
| transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at |
| maximum (the latter being a Linux limitation).</para> |
| |
| <para>Use |
| <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to |
| initialize the system hostname for mounted (but not booted) system images.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Commands</title> |
| |
| <para>The following commands are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command>status</command></term> |
| |
| <listitem><para>Show system hostname and related information. If no command is specified, |
| this is the implied default.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>hostname</command> [<replaceable>NAME</replaceable>]</term> |
| |
| <listitem><para>If no argument is given, print the system hostname. If an |
| optional argument <replaceable>NAME</replaceable> is provided then the command changes the |
| system 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, only the selected hostnames are changed. If |
| the pretty hostname is being set, and static or transient are 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 removing special |
| characters and spaces. This ensures that 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 hostnames are set, and the pretty hostname is left untouched.</para> |
| |
| <para>The static and transient hostnames must each be either a single DNS label (a string composed of |
| 7-bit ASCII lower-case characters and no spaces or dots, limited to the format allowed for DNS domain |
| name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN. The |
| hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names).</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>icon-name</command> [<replaceable>NAME</replaceable>]</term> |
| |
| <listitem><para>If no argument is given, print the icon name of the system. If an |
| optional argument <replaceable>NAME</replaceable> is provided then the command changes the |
| icon 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>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>chassis</command> [<replaceable>TYPE</replaceable>]</term> |
| |
| <listitem><para>If no argument is given, print the chassis type. If an |
| optional argument <replaceable>TYPE</replaceable> is provided then the command changes 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: |
| <literal>desktop</literal>, |
| <literal>laptop</literal>, |
| <literal>convertible</literal>, |
| <literal>server</literal>, |
| <literal>tablet</literal>, |
| <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.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>deployment</command> [<replaceable>ENVIRONMENT</replaceable>]</term> |
| |
| <listitem><para>If no argument is given, print the deployment environment. If an |
| optional argument <replaceable>ENVIRONMENT</replaceable> is provided then the command changes the |
| deployment environment to <replaceable>ENVIRONMENT</replaceable>. |
| Argument <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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>location</command> [<replaceable>LOCATION</replaceable>]</term> |
| |
| <listitem><para>If no argument is given, print the location string for the system. If an |
| optional argument <replaceable>LOCATION</replaceable> is provided then the command changes the |
| location string for the system to <replaceable>LOCATION</replaceable>. |
| Argument <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> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The following options are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--no-ask-password</option></term> |
| |
| <listitem><para>Do not query the user for authentication for |
| privileged operations.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--static</option></term> |
| <term><option>--transient</option></term> |
| <term><option>--pretty</option></term> |
| |
| <listitem><para>If <command>status</command> is invoked (or no explicit command is given) and one of these |
| switches is specified, <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 these switches are specified, 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" /> |
| <xi:include href="standard-options.xml" xpointer="json" /> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Exit status</title> |
| |
| <para>On success, 0 is returned, a non-zero failure code |
| otherwise.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <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-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |