org.freedesktop.hostname1(5) — Linux manual page

NAME | INTRODUCTION | THE D-BUS API | SEMANTICS | RECOMMENDATIONS | VERSIONING | EXAMPLES | SEE ALSO | NOTES | COLOPHON

ORG.FREEDESKTOP.HOSTNAME1(5)g.freedesktop.hostname1.FREEDESKTOP.HOSTNAME1(5)

NAME         top

       org.freedesktop.hostname1 - The D-Bus interface of systemd-hostnamed

INTRODUCTION         top

       systemd-hostnamed.service(8) is a system service that can be used to
       control the hostname and related machine metadata from user programs.
       This page describes the hostname semantics and the D-Bus interface.

THE D-BUS API         top

       The service exposes the following interfaces on the bus:

           node /org/freedesktop/hostname1 {
             interface org.freedesktop.hostname1 {
               methods:
                 SetHostname(in  s hostname,
                             in  b interactive);
                 SetStaticHostname(in  s hostname,
                                   in  b interactive);
                 SetPrettyHostname(in  s hostname,
                                   in  b interactive);
                 SetIconName(in  s icon,
                             in  b interactive);
                 SetChassis(in  s chassis,
                            in  b interactive);
                 SetDeployment(in  s deployment,
                               in  b interactive);
                 SetLocation(in  s location,
                             in  b interactive);
                 GetProductUUID(in  b interactive,
                                out ay uuid);
               properties:
                 readonly s Hostname = '...';
                 readonly s StaticHostname = '...';
                 readonly s PrettyHostname = '...';
                 readonly s IconName = '...';
                 readonly s Chassis = '...';
                 readonly s Deployment = '...';
                 readonly s Location = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s KernelName = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s KernelRelease = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s KernelVersion = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s OperatingSystemPrettyName = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s OperatingSystemCPEName = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s HomeURL = '...';
             };
             interface org.freedesktop.DBus.Peer { ... };
             interface org.freedesktop.DBus.Introspectable { ... };
             interface org.freedesktop.DBus.Properties { ... };
           };

       Whenever the hostname or other metadata is changed via the daemon,
       PropertyChanged signals are sent out to subscribed clients. Changing
       a hostname using this interface is authenticated via polkit[1].

SEMANTICS         top

       The static (configured) hostname is the one configured in
       /etc/hostname. It is chosen by the local user. It is not always in
       sync with the current hostname as returned by the gethostname(3)
       system call. If no hostname is configured this property will be the
       empty string. Setting this property to the empty string will remove
       /etc/hostname. This property should be an internet-style hostname,
       7-bit lowercase ASCII, no special chars/spaces.

       The transient (dynamic) hostname is the one configured via the
       kernel's sethostname(3). It can be different from the static hostname
       if DHCP or mDNS have been configured to change the name based on
       network information.  This property is never empty. If no hostname is
       set this will default to "localhost" (configurable at compilation
       time). Setting this property to the empty string will reset the
       dynamic hostname to the static hostname. If no static hostname is
       configured the dynamic hostname will be reset to "localhost". This
       property should be an internet-style hostname, 7-bit lowercase ASCII,
       no special chars/spaces.

       The pretty hostname is a free-form UTF-8 hostname for presentation to
       the user. User interfaces should ensure that the pretty hostname and
       the static hostname stay in sync. I.e. when the former is "Lennart’s
       Computer" the latter should be "lennarts-computer". If no pretty
       hostname is set this setting will be the empty string. Applications
       should then find a suitable fallback, such as the dynamic hostname.

       The icon name is a name following the XDG icon naming spec. If not
       set, information such as the chassis type (see below) is used to find
       a suitable fallback icon name (i.e.  "computer-laptop" vs.
       "computer-desktop" is picked based on the chassis information). If no
       such data is available, the empty string is returned. In that case an
       application should fall back to a replacement icon, for example
       "computer". If this property is set to the empty string, the
       automatic fallback name selection is enabled again.

       The chassis type should be one of the currently defined chassis
       types: "desktop", "laptop", "server", "tablet", "handset", as well as
       the special chassis types "vm" and "container" for virtualized
       systems. Note that in most cases the chassis type will be determined
       automatically from DMI/SMBIOS/ACPI firmware information. Writing to
       this setting is hence useful only to override misdetected chassis
       types, or to configure the chassis type if it could not be
       auto-detected. Set this property to the empty string to reenable the
       automatic detection of the chassis type from firmware information.

       Note that systemd-hostnamed starts only on request and terminates
       after a short idle period. This effectively means that
       PropertyChanged messages are not sent out for changes made directly
       on the files (as in: administrator edits the files with vi). This is
       the intended behavior: manual configuration changes should require
       manual reloading.

       The transient (dynamic) hostname maps directly to the kernel
       hostname. This hostname should be assumed to be highly dynamic, and
       hence should be watched directly, without depending on
       PropertyChanged messages from systemd-hostnamed. To accomplish this,
       open /proc/sys/kernel/hostname and poll(3) for SIGHUP which is
       triggered by the kernel every time the hostname changes. Again: this
       is special for the transient (dynamic) hostname, and does not apply
       to the configured (fixed) hostname.

       Applications may read the hostname data directly if hostname change
       notifications are not necessary. Use gethostname(3), /etc/hostname
       (possibly with per-distribution fallbacks), and machine-info(3) for
       that. For more information on these files and syscalls see the
       respective man pages.

   Methods and Properties
       SetHostname() sets the transient (dynamic) hostname which is exposed
       by the Hostname property. If empty, the transient hostname is set to
       the static hostname.

       SetStaticHostname() sets the static hostname which is exposed by the
       StaticHostname property. If empty, the built-in default of
       "localhost" is used.

       SetPrettyHostname() sets the pretty hostname which is exposed by the
       PrettyHostname property.

       SetIconName(), SetChassis(), SetDeployment(), and SetLocation() set
       the properties IconName (the name of the icon representing for the
       machine), Chassis (the machine form factor), Deployment (the system
       deployment environment), and Location (physical system location),
       respectively.

       PrettyHostname, IconName, Chassis, Deployment, and Location are
       stored in /etc/machine-info. See machine-info(5) for the semantics of
       those settings.

       GetProductUUID() returns the "product uuid" as exposed by the kernel
       based on DMI information in /sys/class/dmi/id/product_uuid. Reading
       the file directly requires root privileges, and this method allows
       access to unprivileged clients through the polkit framework.

       KernelName, KernelRelease, and KernelVersion expose the kernel name
       (e.g.  "Linux"), release (e.g.  "5.0.0-11"), and version (i.e. the
       build number, e.g.  "#11") as reported by uname(2).
       OperatingSystemPrettyName, OperatingSystemCPEName, and HomeURL expose
       the PRETTY_NAME=, CPE_NAME= and HOME_URL= fields from os-release(5).
       The purpose of those properties is to allow remote clients to access
       this information over D-Bus. Local clients can access the information
       directly.

   Security
       The interactive boolean parameters can be used to control whether
       polkit should interactively ask the user for authentication
       credentials if required.

       The polkit action for SetHostname() is
       org.freedesktop.hostname1.set-hostname. For SetStaticHostname() and
       SetPrettyHostname() it is
       org.freedesktop.hostname1.set-static-hostname. For SetIconName() and
       SetChassis() it is org.freedesktop.hostname1.set-machine-info.

RECOMMENDATIONS         top

       Here are three examples that show how the pretty hostname and the
       icon name should be used:

       ·   When registering DNS-SD services: use the pretty hostname in the
           service name, and pass the icon name in the TXT data, if there is
           an icon name. Browsing clients can then show the server icon on
           each service. This is especially useful for WebDAV applications
           or UPnP media sharing.

       ·   Set the bluetooth name to the pretty hostname.

       ·   When your file browser has a "Computer" icon, replace the name
           with the pretty hostname if set, and the icon with the icon name,
           if it is set.

       To properly handle name lookups with changing local hostnames without
       having to edit /etc/hosts, we recommend using systemd-hostnamed in
       combination with nss-myhostname(3).

       A client that wants to change the local hostname for DHCP/mDNS should
       invoke SetHostname("newname", false) as soon as the name is available
       and afterwards reset it via SetHostname("").

       Here are some recommendations to follow when generating a static
       (internet) hostname from a pretty name:

       ·   Generate a single DNS label only, not an FQDN. That means no dots
           allowed. Strip them, or replace them with "-".

       ·   It's probably safer to not use any non-ASCII chars, even if DNS
           allows this in some way these days. In fact, restrict your
           charset to "a-zA-Z0-9" and "-". Strip other chars, or try to
           replace them in some smart way with chars from this set, for
           example "ä" → "ae", and use "-" as the replacement for all
           punctuation characters and whitespace.

       ·   Try to avoid creating repeated "-", as well as "-" as the first
           or last char.

       ·   Limit the hostname to 63 chars, which is the length of a DNS
           label.

       ·   If after stripping special chars the empty string is the result,
           you can pass this as-is to systemd-hostnamed in which case it
           will automatically use "localhost".

       ·   Uppercase charaacters should be replaced with their lowercase
           equivalents.

       Note that while systemd-hostnamed applies some checks to the hostname
       you pass they are much looser than the recommendations above. For
       example, systemd-hostnamed will also accept "_" in the hostname, but
       we recommend not using this to avoid clashes with DNS-SD service
       types. Also systemd-hostnamed allows longer hostnames, but because of
       the DNS label limitations, we recommend not making use of this.

       Here are a couple of example conversions:

       ·   "Lennart's PC" → "lennarts-pc"

       ·   "Müllers Computer" → "muellers-computer"

       ·   "Voran!"  → "voran"

       ·   "Es war einmal ein Männlein" → "es-war-einmal-ein-maennlein"

       ·   "Jawoll. Ist doch wahr!"  → "jawoll-ist-doch-wahr"

       ·   "レナート" → "localhost"

       ·   "...zack!!! zack!..."  → "zack-zack"

       Of course, an already valid internet hostname label you enter and
       pass through this conversion should stay unmodified, so that users
       have direct control of it, if they want — by simply ignoring the fact
       that the pretty hostname is pretty and just edit it as if it was the
       normal internet name.

VERSIONING         top

       These D-Bus interfaces follow the usual interface versioning
       guidelines[2].

EXAMPLES         top

       Example 1. Introspect org.freedesktop.hostname1 on the bus

           $ gdbus introspect --system \
             --dest org.freedesktop.hostname1 \
             --object-path /org/freedesktop/hostname1

SEE ALSO         top

       David Zeuthen's original Fedora Feature page about xdg-hostname[3]

NOTES         top

        1. polkit
           https://www.freedesktop.org/software/polkit/docs/latest/

        2. the usual interface versioning guidelines
           http://0pointer.de/blog/projects/versioning-dbus.html

        3. Feature page about xdg-hostname
           https://fedoraproject.org/wiki/Features/BetterHostname

COLOPHON         top

       This page is part of the systemd (systemd system and service manager)
       project.  Information about the project can be found at 
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a bug
       report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2020-09-18.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-09-18.)  If you discover any rendering problems in
       this HTML version of the page, or you believe there is a better or
       more up-to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not part
       of the original manual page), send a mail to man-pages@man7.org

systemd 246                                     ORG.FREEDESKTOP.HOSTNAME1(5)

Pages that refer to this page: 30-systemd-environment-d-generator(7)systemd.directives(7)systemd.index(7)systemd-hostnamed(8)systemd-hostnamed.service(8)