1ORG.FREEDESKTOP.HOSTNAME1(5)org.freedesktop.hostnameO1RG.FREEDESKTOP.HOSTNAME1(5)
2
3
4

NAME

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

INTRODUCTION

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

THE D-BUS API

14       The service exposes the following interfaces on the bus:
15
16           node /org/freedesktop/hostname1 {
17             interface org.freedesktop.hostname1 {
18               methods:
19                 SetHostname(in  s hostname,
20                             in  b interactive);
21                 SetStaticHostname(in  s hostname,
22                                   in  b interactive);
23                 SetPrettyHostname(in  s hostname,
24                                   in  b interactive);
25                 SetIconName(in  s icon,
26                             in  b interactive);
27                 SetChassis(in  s chassis,
28                            in  b interactive);
29                 SetDeployment(in  s deployment,
30                               in  b interactive);
31                 SetLocation(in  s location,
32                             in  b interactive);
33                 GetProductUUID(in  b interactive,
34                                out ay uuid);
35                 Describe(out s json);
36               properties:
37                 readonly s Hostname = '...';
38                 readonly s StaticHostname = '...';
39                 readonly s PrettyHostname = '...';
40                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
41                 readonly s DefaultHostname = '...';
42                 readonly s HostnameSource = '...';
43                 readonly s IconName = '...';
44                 readonly s Chassis = '...';
45                 readonly s Deployment = '...';
46                 readonly s Location = '...';
47                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
48                 readonly s KernelName = '...';
49                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
50                 readonly s KernelRelease = '...';
51                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
52                 readonly s KernelVersion = '...';
53                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
54                 readonly s OperatingSystemPrettyName = '...';
55                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
56                 readonly s OperatingSystemCPEName = '...';
57                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
58                 readonly s HomeURL = '...';
59                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
60                 readonly s HardwareVendor = '...';
61                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
62                 readonly s HardwareModel = '...';
63             };
64             interface org.freedesktop.DBus.Peer { ... };
65             interface org.freedesktop.DBus.Introspectable { ... };
66             interface org.freedesktop.DBus.Properties { ... };
67           };
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98       Whenever the hostname or other metadata is changed via the daemon,
99       PropertyChanged signals are sent out to subscribed clients. Changing a
100       hostname using this interface is authenticated via polkit[1].
101

SEMANTICS

103       The StaticHostname property exposes the "static" hostname configured in
104       /etc/hostname. It is not always in sync with the current hostname as
105       returned by the gethostname(3) system call. If no static hostname is
106       configured this property will be the empty string.
107
108       When systemd(1) or systemd-hostnamed.service(8) set the hostname, this
109       static hostname has the highest priority.
110
111       The Hostname property exposes the actual hostname configured in the
112       kernel via sethostname(3). It can be different from the static
113       hostname. This property is never empty.
114
115       The PrettyHostname property exposes the pretty hostname which is a
116       free-form UTF-8 hostname for presentation to the user. User interfaces
117       should ensure that the pretty hostname and the static hostname stay in
118       sync. E.g. when the former is "Lennart’s Computer" the latter should be
119       "lennarts-computer". If no pretty hostname is set this setting will be
120       the empty string. Applications should then find a suitable fallback,
121       such as the dynamic hostname.
122
123       The DefaultHostname property exposes the default hostname (configured
124       through os-release(5), or a fallback set at compilation time).
125
126       The HostnameSource property exposes the origin of the currently
127       configured hostname. One of "static" (set from /etc/hostname),
128       "transient" (a non-permanent hostname from an external source),
129       "default" (the value from os-release or the compiled-in fallback).
130
131       The IconName property exposes the icon name following the XDG icon
132       naming spec. If not set, information such as the chassis type (see
133       below) is used to find a suitable fallback icon name (i.e.
134       "computer-laptop" vs.  "computer-desktop" is picked based on the
135       chassis information). If no such data is available, the empty string is
136       returned. In that case an application should fall back to a replacement
137       icon, for example "computer". If this property is set to the empty
138       string, the automatic fallback name selection is enabled again.
139
140       The Chassis property exposes a chassis type, one of the currently
141       defined chassis types: "desktop", "laptop", "server", "tablet",
142       "handset", as well as the special chassis types "vm" and "container"
143       for virtualized systems. Note that in most cases the chassis type will
144       be determined automatically from DMI/SMBIOS/ACPI firmware information.
145       Writing to this setting is hence useful only to override misdetected
146       chassis types, or to configure the chassis type if it could not be
147       auto-detected. Set this property to the empty string to reenable the
148       automatic detection of the chassis type from firmware information.
149
150       Note that systemd-hostnamed starts only on request and terminates after
151       a short idle period. This effectively means that PropertyChanged
152       messages are not sent out for changes made directly on the files (as
153       in: administrator edits the files with vi). This is the intended
154       behavior: manual configuration changes should require manual reloading.
155
156       The transient (dynamic) hostname exposed by the Hostname property maps
157       directly to the kernel hostname. This hostname should be assumed to be
158       highly dynamic, and hence should be watched directly, without depending
159       on PropertyChanged messages from systemd-hostnamed. To accomplish this,
160       open /proc/sys/kernel/hostname and poll(3) for SIGHUP which is
161       triggered by the kernel every time the hostname changes. Again: this is
162       special for the transient (dynamic) hostname, and does not apply to the
163       configured (fixed) hostname.
164
165       Applications may read the hostname data directly if hostname change
166       notifications are not necessary. Use gethostname(3), /etc/hostname
167       (possibly with per-distribution fallbacks), and machine-info(3) for
168       that. For more information on these files and syscalls see the
169       respective man pages.
170
171       KernelName, KernelRelease, and KernelVersion expose the kernel name
172       (e.g.  "Linux"), release (e.g.  "5.0.0-11"), and version (i.e. the
173       build number, e.g.  "#11") as reported by uname(2).
174       OperatingSystemPrettyName, OperatingSystemCPEName, and HomeURL expose
175       the PRETTY_NAME=, CPE_NAME= and HOME_URL= fields from os-release(5).
176       The purpose of those properties is to allow remote clients to access
177       this information over D-Bus. Local clients can access the information
178       directly.
179
180   Methods
181       SetHostname() sets the transient (dynamic) hostname, which is used if
182       no static hostname is set. This value must be an internet-style
183       hostname, 7-bit lowercase ASCII, no special chars/spaces. An empty
184       string will unset the transient hostname.
185
186       SetStaticHostname() sets the static hostname which is exposed by the
187       StaticHostname property. When called with an empty argument, the static
188       configuration in /etc/hostname is removed. Since the static hostname
189       has the highest priority, calling this function usually affects also
190       the Hostname property and the effective hostname configured in the
191       kernel.
192
193       SetPrettyHostname() sets the pretty hostname which is exposed by the
194       PrettyHostname property.
195
196       SetIconName(), SetChassis(), SetDeployment(), and SetLocation() set the
197       properties IconName (the name of the icon representing for the
198       machine), Chassis (the machine form factor), Deployment (the system
199       deployment environment), and Location (physical system location),
200       respectively.
201
202       PrettyHostname, IconName, Chassis, Deployment, and Location are stored
203       in /etc/machine-info. See machine-info(5) for the semantics of those
204       settings.
205
206       GetProductUUID() returns the "product UUID" as exposed by the kernel
207       based on DMI information in /sys/class/dmi/id/product_uuid. Reading the
208       file directly requires root privileges, and this method allows access
209       to unprivileged clients through the polkit framework.
210
211       Describe() returns a JSON representation of all properties in one.
212
213   Security
214       The interactive boolean parameters can be used to control whether
215       polkit should interactively ask the user for authentication credentials
216       if required.
217
218       The polkit action for SetHostname() is
219       org.freedesktop.hostname1.set-hostname. For SetStaticHostname() and
220       SetPrettyHostname() it is
221       org.freedesktop.hostname1.set-static-hostname. For SetIconName(),
222       SetChassis(), SetDeployment() and SetLocation() it is
223       org.freedesktop.hostname1.set-machine-info.
224

RECOMMENDATIONS

226       Here are three examples that show how the pretty hostname and the icon
227       name should be used:
228
229       •   When registering DNS-SD services: use the pretty hostname in the
230           service name, and pass the icon name in the TXT data, if there is
231           an icon name. Browsing clients can then show the server icon on
232           each service. This is especially useful for WebDAV applications or
233           UPnP media sharing.
234
235       •   Set the bluetooth name to the pretty hostname.
236
237       •   When your file browser has a "Computer" icon, replace the name with
238           the pretty hostname if set, and the icon with the icon name, if it
239           is set.
240
241       To properly handle name lookups with changing local hostnames without
242       having to edit /etc/hosts, we recommend using systemd-hostnamed in
243       combination with nss-myhostname(3).
244
245       Here are some recommendations to follow when generating a static
246       (internet) hostname from a pretty name:
247
248       •   Generate a single DNS label only, not an FQDN. That means no dots
249           allowed. Strip them, or replace them with "-".
250
251       •   It's probably safer to not use any non-ASCII chars, even if DNS
252           allows this in some way these days. In fact, restrict your charset
253           to "a-zA-Z0-9" and "-". Strip other chars, or try to replace them
254           in some smart way with chars from this set, for example "ä" → "ae",
255           and use "-" as the replacement for all punctuation characters and
256           whitespace.
257
258       •   Try to avoid creating repeated "-", as well as "-" as the first or
259           last char.
260
261       •   Limit the hostname to 63 chars, which is the length of a DNS label.
262
263       •   If after stripping special chars the empty string is the result,
264           you can pass this as-is to systemd-hostnamed in which case it will
265           automatically use a suitable fallback.
266
267       •   Uppercase charaacters should be replaced with their lowercase
268           equivalents.
269
270       Note that while systemd-hostnamed applies some checks to the hostname
271       you pass they are much looser than the recommendations above. For
272       example, systemd-hostnamed will also accept "_" in the hostname, but we
273       recommend not using this to avoid clashes with DNS-SD service types.
274       Also systemd-hostnamed allows longer hostnames, but because of the DNS
275       label limitations, we recommend not making use of this.
276
277       Here are a couple of example conversions:
278
279       •   "Lennart's PC" → "lennarts-pc"
280
281       •   "Müllers Computer" → "muellers-computer"
282
283       •   "Voran!"  → "voran"
284
285       •   "Es war einmal ein Männlein" → "es-war-einmal-ein-maennlein"
286
287       •   "Jawoll. Ist doch wahr!"  → "jawoll-ist-doch-wahr"
288
289       •   "レナート" → "localhost"
290
291       •   "...zack!!! zack!..."  → "zack-zack"
292
293       Of course, an already valid internet hostname label you enter and pass
294       through this conversion should stay unmodified, so that users have
295       direct control of it, if they want — by simply ignoring the fact that
296       the pretty hostname is pretty and just edit it as if it was the normal
297       internet name.
298

VERSIONING

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

EXAMPLES

304       Example 1. Introspect org.freedesktop.hostname1 on the bus
305
306           $ gdbus introspect --system \
307             --dest org.freedesktop.hostname1 \
308             --object-path /org/freedesktop/hostname1
309
310

SEE ALSO

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

NOTES

315        1. polkit
316           https://www.freedesktop.org/software/polkit/docs/latest/
317
318        2. the usual interface versioning guidelines
319           http://0pointer.de/blog/projects/versioning-dbus.html
320
321        3. Feature page about xdg-hostname
322           https://fedoraproject.org/wiki/Features/BetterHostname
323
324
325
326systemd 250                                       ORG.FREEDESKTOP.HOSTNAME1(5)
Impressum