| <?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 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> |
| |
| <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 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> |
| |
| <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 |
| replacing spaces with |
| <literal>-</literal> and removing |
| special characters. 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>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> |