[thirdparty/systemd.git] / man / hostnamectl.xml

<?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 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>

                <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-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</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>-P</option></term>
                                <term><option>--privileged</option></term>

                                <listitem><para>Acquire privileges via PolicyKit
                                before executing the operation.</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="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 [NAME]</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
                                <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. 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>

                                <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
                                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
                                parameters.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>set-chassis [TYPE]</command></term>

                                <listitem><para>Set the chassis
                                type. 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>, 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>
                        </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>
                </para>
        </refsect1>

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