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