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

<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="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>