HOSTNAMECTL(1)

NAME
hostnamectl - control the system hostname and related machine metadata

SYNOPSIS
hostnamectl [OPTIONS] COMMAND [ARGUMENT]

DESCRIPTION
hostnamectl is a Bash client used to query and change the system's static, transient, and pretty hostnames, along with related machine metadata such as the icon name, chassis type, deployment environment, and location.

Unlike a typical D-Bus client, hostnamectl writes directly to /etc/HOSTNAME (or /etc/hostname if the former does not exist) and /etc/machine-info. The hostnamed daemon watches these files with inotify(7) and automatically updates its org.freedesktop.hostname1 D-Bus properties and emits PropertiesChanged signals whenever they are modified, whether by hostnamectl or by any other tool. This means hostnamectl itself never talks to D-Bus or PolKit; it relies on ordinary file permissions, and most subcommands simply require root.

On first run as root, if /etc/machine-info does not yet exist, hostnamectl creates it automatically, deriving an initial chassis and icon name from SMBIOS data under /sys/class/dmi/id and an initial pretty hostname from the static hostname file. An existing /etc/machine-info is never overwritten by this bootstrap step.

COMMANDS

status
    Show the current hostname and machine information in human-readable form. This is the default command when none is given. Fields are only printed when a value is available; for example the pretty hostname, deployment, location, firmware fields, and virtualization line are omitted entirely if empty or undetectable. The transient hostname is only shown when it differs from the static hostname.

set-hostname [--static|--transient|--pretty] NAME
    Set the system hostname. With no mode flag, all three forms are updated at once: the static hostname file and the transient hostname (via the hostname(1) command) are both set to NAME, and the pretty hostname is set to NAME with any domain suffix stripped (the portion before the first dot).

    --static
        Update only the static hostname file.

    --transient
        Update only the running kernel's hostname via hostname(1), without touching any file.

    --pretty
        Update only the pretty hostname in /etc/machine-info. Unlike the other modes, the value is not validated as a DNS-style hostname, since pretty names are free-form and may contain spaces.

set-icon-name NAME
    Set the freedesktop icon name (for example computer-laptop) used to represent this machine in graphical tools. Stored as ICON_NAME in /etc/machine-info.

set-chassis TYPE
    Set the chassis type. Must be one of: desktop, laptop, server, tablet, handset, watch, embedded, vm, container, or convertible. Stored as CHASSIS in /etc/machine-info.

set-deployment ENVIRONMENT
    Set a free-form deployment label, for example production or staging. Stored as DEPLOYMENT in /etc/machine-info.

set-location LOCATION
    Set a free-form physical location string. Stored as LOCATION in /etc/machine-info.

OPTIONS

-h, --help
    Show a short usage summary and exit.

EXAMPLES

Show the current status:

        hostnamectl status

Rename the machine entirely (static, transient, and pretty hostnames):

        hostnamectl set-hostname web01.example.net

Give the machine a friendly display name without changing its network hostname:

        hostnamectl set-hostname --pretty "Nathan's Desktop"

Change only the running kernel's hostname, leaving the configured static hostname untouched until the next reboot:

        hostnamectl set-hostname --transient temphost

Mark a machine as part of staging:

        hostnamectl set-deployment staging

EXIT STATUS
Returns 0 on success and 1 on error (for example, an invalid hostname, an invalid chassis type, a missing argument, or insufficient permissions).

AUTHORIZATION
All subcommands other than status require root. There is no PolKit prompt or D-Bus round trip in hostnamectl itself; the daemon's PolKit policy governs only direct D-Bus callers such as gnome-control-center(1).

FILES

/etc/HOSTNAME
    Static hostname file, used in preference to /etc/hostname when present.

/etc/hostname
    Fallback static hostname file, used only if /etc/HOSTNAME does not exist.

/etc/machine-info
    Stores the pretty hostname, icon name, chassis, deployment, and location as shell-style KEY="value" assignments. Rewritten atomically (temporary file plus rename) on every write. Created automatically on first root invocation if missing.

/etc/os-release
    Read for the operating system's pretty name and CPE name when displaying status. Not modified by hostnamectl.

/etc/machine-id
    Read for the machine ID shown in status. Not modified by hostnamectl.

/sys/class/dmi/id/*
    SMBIOS/DMI sysfs nodes read for chassis detection, virtualization detection, and the hardware vendor, model, firmware version, and firmware date fields shown in status.

SEE ALSO
hostnamed(8), machine-info(5), os-release(5), hostname(1), inotify(7)

AUTHOR
Written by Nathaniel Russell.

Part of the hostnamed project, a non-systemd implementation of the org.freedesktop.hostname1 D-Bus interface for Slackware Linux.

LICENSE
This program is free software, distributed under the GNU General Public License, version 2 or later. See the source for copying conditions.