| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <!-- |
| This file is part of systemd. |
| |
| Copyright 2012 Lennart Poettering |
| |
| systemd is free software; you can redistribute it and/or modify it |
| under the terms of the GNU Lesser General Public License as published by |
| the Free Software Foundation; either version 2.1 of the License, or |
| (at your option) any later version. |
| |
| systemd is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public License |
| along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| --> |
| |
| <refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED' |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| |
| <refentryinfo> |
| <title>hostnamectl</title> |
| <productname>systemd</productname> |
| |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Lennart</firstname> |
| <surname>Poettering</surname> |
| <email>lennart@poettering.net</email> |
| </author> |
| </authorgroup> |
| </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>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 is a fallback |
| value 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 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>The static hostname is stored in |
| <filename>/etc/hostname</filename>, see |
| <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| for more information. The pretty hostname, chassis type, and icon |
| name are stored in <filename>/etc/machine-info</filename>, see |
| <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> |
| <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" /> |
| </variablelist> |
| |
| <para>The following commands are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command>status</command></term> |
| |
| <listitem><para>Show current system |
| hostname and related |
| information.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>set-hostname <replaceable>NAME</replaceable></command></term> |
| |
| <listitem><para>Set 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 host names are set, and the pretty host 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 <replaceable>NAME</replaceable></command></term> |
| |
| <listitem><para>Set the system 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> |
| |
| <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 <replaceable>TYPE</replaceable></command></term> |
| |
| <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: |
| <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> |
| |
| <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 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> |