1ORG.FREEDESKTOP.HOSTNAME1(5)org.freedesktop.hostnameO1RG.FREEDESKTOP.HOSTNAME1(5)
2
6 org.freedesktop.hostname1 - The D-Bus interface of systemd-hostnamed
7
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
14 The service exposes the following interfaces on the bus:
15 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 GetHardwareSerial(out s serial);
36 Describe(out s json);
37 properties:
38 readonly s Hostname = '...';
39 readonly s StaticHostname = '...';
40 readonly s PrettyHostname = '...';
41 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
42 readonly s DefaultHostname = '...';
43 readonly s HostnameSource = '...';
44 readonly s IconName = '...';
45 readonly s Chassis = '...';
46 readonly s Deployment = '...';
47 readonly s Location = '...';
48 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
49 readonly s KernelName = '...';
50 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
51 readonly s KernelRelease = '...';
52 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
53 readonly s KernelVersion = '...';
54 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
55 readonly s OperatingSystemPrettyName = '...';
56 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
57 readonly s OperatingSystemCPEName = '...';
58 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
59 readonly t OperatingSystemSupportEnd = ...;
60 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
61 readonly s HomeURL = '...';
62 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
63 readonly s HardwareVendor = '...';
64 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
65 readonly s HardwareModel = '...';
66 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
67 readonly s FirmwareVersion = '...';
68 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
69 readonly s FirmwareVendor = '...';
70 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
71 readonly t FirmwareDate = ...;
72 };
73 interface org.freedesktop.DBus.Peer { ... };
74 interface org.freedesktop.DBus.Introspectable { ... };
75 interface org.freedesktop.DBus.Properties { ... };
76 };
77 Whenever the hostname or other metadata is changed via the daemon,
113 PropertyChanged signals are sent out to subscribed clients. Changing a
114 hostname using this interface is authenticated via polkit[1].
115
117 The StaticHostname property exposes the "static" hostname configured in
118 /etc/hostname. It is not always in sync with the current hostname as
119 returned by the gethostname(3) system call. If no static hostname is
120 configured this property will be the empty string.
121 When systemd(1) or systemd-hostnamed.service(8) set the hostname, this
123 static hostname has the highest priority.
124 The Hostname property exposes the actual hostname configured in the
126 kernel via sethostname(2). It can be different from the static
127 hostname. This property is never empty.
128 The PrettyHostname property exposes the pretty hostname which is a
130 free-form UTF-8 hostname for presentation to the user. User interfaces
131 should ensure that the pretty hostname and the static hostname stay in
132 sync. E.g. when the former is "Lennart’s Computer" the latter should be
133 "lennarts-computer". If no pretty hostname is set this setting will be
134 the empty string. Applications should then find a suitable fallback,
135 such as the dynamic hostname.
136 The DefaultHostname property exposes the default hostname (configured
138 through os-release(5), or a fallback set at compilation time).
139 The HostnameSource property exposes the origin of the currently
141 configured hostname. One of "static" (set from /etc/hostname),
142 "transient" (a non-permanent hostname from an external source),
143 "default" (the value from os-release or the compiled-in fallback).
144 The IconName property exposes the icon name following the XDG icon
146 naming spec. If not set, information such as the chassis type (see
147 below) is used to find a suitable fallback icon name (i.e.
148 "computer-laptop" vs. "computer-desktop" is picked based on the
149 chassis information). If no such data is available, the empty string is
150 returned. In that case an application should fall back to a replacement
151 icon, for example "computer". If this property is set to the empty
152 string, the automatic fallback name selection is enabled again.
153 The Chassis property exposes a chassis type, one of the currently
155 defined chassis types: "desktop", "laptop", "server", "tablet",
156 "handset", as well as the special chassis types "vm" and "container"
157 for virtualized systems. Note that in most cases the chassis type will
158 be determined automatically from DMI/SMBIOS/ACPI firmware information.
159 Writing to this setting is hence useful only to override misdetected
160 chassis types, or to configure the chassis type if it could not be
161 auto-detected. Set this property to the empty string to reenable the
162 automatic detection of the chassis type from firmware information.
163 Note that systemd-hostnamed starts only on request and terminates after
165 a short idle period. This effectively means that PropertyChanged
166 messages are not sent out for changes made directly on the files (as
167 in: administrator edits the files with vi). This is the intended
168 behavior: manual configuration changes should require manual reloading.
169 The transient (dynamic) hostname exposed by the Hostname property maps
171 directly to the kernel hostname. This hostname should be assumed to be
172 highly dynamic, and hence should be watched directly, without depending
173 on PropertyChanged messages from systemd-hostnamed. To accomplish this,
174 open /proc/sys/kernel/hostname and poll(3) for SIGHUP which is
175 triggered by the kernel every time the hostname changes. Again: this is
176 special for the transient (dynamic) hostname, and does not apply to the
177 configured (fixed) hostname.
178 Applications may read the hostname data directly if hostname change
180 notifications are not necessary. Use gethostname(2), /etc/hostname
181 (possibly with per-distribution fallbacks), and machine-info(3) for
182 that. For more information on these files and syscalls see the
183 respective man pages.
184 KernelName, KernelRelease, and KernelVersion expose the kernel name
186 (e.g. "Linux"), release (e.g. "5.0.0-11"), and version (i.e. the
187 build number, e.g. "#11") as reported by uname(2).
188 OperatingSystemPrettyName, OperatingSystemCPEName, and HomeURL expose
189 the PRETTY_NAME=, CPE_NAME= and HOME_URL= fields from os-release(5).
190 The purpose of those properties is to allow remote clients to access
191 this information over D-Bus. Local clients can access the information
192 directly.
193 Methods
195 SetHostname() sets the transient (dynamic) hostname, which is used if
196 no static hostname is set. This value must be an internet-style
197 hostname, 7-bit lowercase ASCII, no special chars/spaces. An empty
198 string will unset the transient hostname.
199 SetStaticHostname() sets the static hostname which is exposed by the
201 StaticHostname property. When called with an empty argument, the static
202 configuration in /etc/hostname is removed. Since the static hostname
203 has the highest priority, calling this function usually affects also
204 the Hostname property and the effective hostname configured in the
205 kernel.
206 SetPrettyHostname() sets the pretty hostname which is exposed by the
208 PrettyHostname property.
209 SetIconName(), SetChassis(), SetDeployment(), and SetLocation() set the
211 properties IconName (the name of the icon representing for the
212 machine), Chassis (the machine form factor), Deployment (the system
213 deployment environment), and Location (physical system location),
214 respectively.
215 PrettyHostname, IconName, Chassis, Deployment, and Location are stored
217 in /etc/machine-info. See machine-info(5) for the semantics of those
218 settings.
219 GetProductUUID() returns the "product UUID" as exposed by the kernel
221 based on DMI information in /sys/class/dmi/id/product_uuid. Reading the
222 file directly requires root privileges, and this method allows access
223 to unprivileged clients through the polkit framework.
224 Describe() returns a JSON representation of all properties in one.
226 Security
228 The interactive boolean parameters can be used to control whether
229 polkit should interactively ask the user for authentication credentials
230 if required.
231 The polkit action for SetHostname() is
233 org.freedesktop.hostname1.set-hostname. For SetStaticHostname() and
234 SetPrettyHostname() it is
235 org.freedesktop.hostname1.set-static-hostname. For SetIconName(),
236 SetChassis(), SetDeployment() and SetLocation() it is
237 org.freedesktop.hostname1.set-machine-info.
238
240 Here are three examples that show how the pretty hostname and the icon
241 name should be used:
242 • When registering DNS-SD services: use the pretty hostname in the
244 service name, and pass the icon name in the TXT data, if there is
245 an icon name. Browsing clients can then show the server icon on
246 each service. This is especially useful for WebDAV applications or
247 UPnP media sharing.
248 • Set the bluetooth name to the pretty hostname.
250 • When your file browser has a "Computer" icon, replace the name with
252 the pretty hostname if set, and the icon with the icon name, if it
253 is set.
254 To properly handle name lookups with changing local hostnames without
256 having to edit /etc/hosts, we recommend using systemd-hostnamed in
257 combination with nss-myhostname(3).
258 Here are some recommendations to follow when generating a static
260 (internet) hostname from a pretty name:
261 • Generate a single DNS label only, not an FQDN. That means no dots
263 allowed. Strip them, or replace them with "-".
264 • It's probably safer to not use any non-ASCII chars, even if DNS
266 allows this in some way these days. In fact, restrict your charset
267 to "a-zA-Z0-9" and "-". Strip other chars, or try to replace them
268 in some smart way with chars from this set, for example "ä" → "ae",
269 and use "-" as the replacement for all punctuation characters and
270 whitespace.
271 • Try to avoid creating repeated "-", as well as "-" as the first or
273 last char.
274 • Limit the hostname to 63 chars, which is the length of a DNS label.
276 • If after stripping special chars the empty string is the result,
278 you can pass this as-is to systemd-hostnamed in which case it will
279 automatically use a suitable fallback.
280 • Uppercase characters should be replaced with their lowercase
282 equivalents.
283 Note that while systemd-hostnamed applies some checks to the hostname
285 you pass they are much looser than the recommendations above. For
286 example, systemd-hostnamed will also accept "_" in the hostname, but we
287 recommend not using this to avoid clashes with DNS-SD service types.
288 Also systemd-hostnamed allows longer hostnames, but because of the DNS
289 label limitations, we recommend not making use of this.
290 Here are a couple of example conversions:
292 • "Lennart's PC" → "lennarts-pc"
294 • "Müllers Computer" → "muellers-computer"
296 • "Voran!" → "voran"
298 • "Es war einmal ein Männlein" → "es-war-einmal-ein-maennlein"
300 • "Jawoll. Ist doch wahr!" → "jawoll-ist-doch-wahr"
302 • "レナート" → "localhost"
304 • "...zack!!! zack!..." → "zack-zack"
306 Of course, an already valid internet hostname label you enter and pass
308 through this conversion should stay unmodified, so that users have
309 direct control of it, if they want — by simply ignoring the fact that
310 the pretty hostname is pretty and just edit it as if it was the normal
311 internet name.
312
314 These D-Bus interfaces follow the usual interface versioning
315 guidelines[2].
316
318 Example 1. Introspect org.freedesktop.hostname1 on the bus
319 $ gdbus introspect --system \
321 --dest org.freedesktop.hostname1 \
322 --object-path /org/freedesktop/hostname1
323
326 David Zeuthen's original Fedora Feature page about xdg-hostname[3]
327
329 1. polkit
330 https://www.freedesktop.org/software/polkit/docs/latest/
331 2. the usual interface versioning guidelines
333 https://0pointer.de/blog/projects/versioning-dbus.html
334 3. Feature page about xdg-hostname
336 https://fedoraproject.org/wiki/Features/BetterHostname
337systemd 253 ORG.FREEDESKTOP.HOSTNAME1(5)