hostnamectl.xml revision dfdebb1b925332352966804303b2516a6506a429
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek<?xml version='1.0'?> <!--*-nxml-*-->
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek This file is part of systemd.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek Copyright 2012 Lennart Poettering
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek (at your option) any later version.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
21ac6ff143cc8bebfbd1818af28e8c6f82cd5265Zbigniew Jędrzejewski-Szmek<refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED'
21ac6ff143cc8bebfbd1818af28e8c6f82cd5265Zbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <productname>systemd</productname>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <refentrytitle>hostnamectl</refentrytitle>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <refpurpose>Control the system hostname</refpurpose>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <refsynopsisdiv>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">OPTIONS</arg>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <para><command>hostnamectl</command> may be used to
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek query and change the system hostname and related
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek settings.</para>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <para>This tool distinguishes three different
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek hostnames: the high-level "pretty" hostname which
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek might include all kinds of special characters
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek (e.g. "Lennart's Laptop"), the static hostname which
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek is used to initialize the kernel hostname at boot
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek (e.g. "lennarts-laptop"), and the transient hostname
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek which might be assigned temporarily due to network
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek configuration and might revert back to the static
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek hostname if network connectivity is lost and is only
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek temporarily written to the kernel hostname
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <para>Note that the pretty hostname has little
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering restrictions on the characters used, while the static
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering and transient hostnames are limited to the usually
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering accepted characters of Internet domain names.</para>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <para>The static hostname is stored in
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering for more information. The pretty hostname, chassis
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering type, and icon name are stored in
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <filename>/etc/machine-info</filename>, see
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <para>The following options are understood:</para>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <variablelist>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <varlistentry>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <term><option>--no-ask-password</option></term>
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering for authentication for privileged
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <term><option>-P</option></term>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <term><option>--privileged</option></term>
3fde5f30bda2a70d97f3dc8fa918e42e1c07cc2cLennart Poettering <listitem><para>Acquire privileges via PolicyKit
3fde5f30bda2a70d97f3dc8fa918e42e1c07cc2cLennart Poettering before executing the operation.</para></listitem>
acf97e213e69a97e63ab8f7fad7ecd53608c757aLennart Poettering remotely. Specify a hostname, or
acf97e213e69a97e63ab8f7fad7ecd53608c757aLennart Poettering username and hostname separated by <literal>@</literal>,
acf97e213e69a97e63ab8f7fad7ecd53608c757aLennart Poettering to connect to. This will use SSH to
acf97e213e69a97e63ab8f7fad7ecd53608c757aLennart Poettering talk to the remote
773e264d13cac53cbf7e0b174e1883dabb4c9bc2Thomas Hindoe Paaboel Andersen <term><option>--static</option></term>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <term><option>--transient</option></term>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <term><option>--pretty</option></term>
f7f74d8ec46532f13a1dc418d550eaf76b339fa3Lennart Poettering no explicit command is given) and one
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek of those fields is given,
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <command>hostnamectl</command> will
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek print out just this selected
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek hostname.</para>
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <para>If used with
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <command>set-hostname</command>, only
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek the selected hostname(s) will be
773e264d13cac53cbf7e0b174e1883dabb4c9bc2Thomas Hindoe Paaboel Andersen updated. When more than one of those
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek options is used, all the specified
f7f74d8ec46532f13a1dc418d550eaf76b339fa3Lennart Poettering hostnames will be updated.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="help" />
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="version" />
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <para>The following commands are understood:</para>
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering <variablelist>
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering <varlistentry>
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering hostname and related
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering </varlistentry>
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering <varlistentry>
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering <term><command>set-hostname [NAME]</command></term>
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering hostname. By default, this will alter
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering the pretty, the static, and the
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering transient hostname alike; however, if
785890acf6d629ff881a1f065f431df1b7fc8c7aLennart Poettering one or more of
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering only the selected hostnames are
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering changed. If the pretty hostname is
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering being set, and static or transient are
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering being set as well, the specified
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering hostname will be simplified in regards
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering to the character set used before the
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering latter are updated. This is done by
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering replacing spaces with
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering special characters. This ensures that
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering the pretty and the static hostname are
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering always closely related while still
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering following the validity rules of the
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering specific name. This simplification of
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering the hostname string is not done if
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering names are set, and the pretty host
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering name is left untouched. Pass the empty
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering hostname to reset the selected
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering hostnames to their default (usually
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering <literal>localhost</literal>).</para></listitem>
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering </varlistentry>
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering <varlistentry>
8b0cc9a36c8f92f010f2e8465942d2cd7c580d78Lennart Poettering <term><command>set-icon-name [NAME]</command></term>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering name. The icon name is used by some
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering graphical applications to visualize
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering this host. The icon name should follow
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering Naming Specification</ulink>. Pass an
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering empty string to this operation to
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering reset the icon name to the default
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering value, which is determined from chassis
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering type (see below) and possibly other
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering </varlistentry>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering <varlistentry>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering <term><command>set-chassis [TYPE]</command></term>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering type. The chassis type is used by some
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering graphical applications to visualize
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering the host or alter user
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering interaction. Currently, the following
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering chassis types are defined:
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering the special chassis types
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering virtualized systems that lack an
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering immediate physical chassis. Pass an
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering empty string to this operation to
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering reset the chassis type to the default
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering value which is determined from the
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering firmware and possibly other
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering </varlistentry>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering </variablelist>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering <para>On success, 0 is returned, a non-zero failure
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering code otherwise.</para>
12f15e596a3040f32bb8c9aa9d0bf9b43fc96567Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
dfdebb1b925332352966804303b2516a6506a429Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
dfdebb1b925332352966804303b2516a6506a429Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
e45fc5e738b0b7700e8b4f3c4b25c58a49b44b27Lennart Poettering <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>