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