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 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 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
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 When systemd(1) or systemd-hostnamed.service(8) set the hostname, this
109 static hostname has the highest priority.
110 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 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 The DefaultHostname property exposes the default hostname (configured
124 through os-release(5), or a fallback set at compilation time).
125 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 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 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 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 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 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 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 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 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 SetPrettyHostname() sets the pretty hostname which is exposed by the
194 PrettyHostname property.
195 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 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 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 Describe() returns a JSON representation of all properties in one.
212 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 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
226 Here are three examples that show how the pretty hostname and the icon
227 name should be used:
228 • 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 • Set the bluetooth name to the pretty hostname.
236 • 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 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 Here are some recommendations to follow when generating a static
246 (internet) hostname from a pretty name:
247 • Generate a single DNS label only, not an FQDN. That means no dots
249 allowed. Strip them, or replace them with "-".
250 • 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 • Try to avoid creating repeated "-", as well as "-" as the first or
259 last char.
260 • Limit the hostname to 63 chars, which is the length of a DNS label.
262 • 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 • Uppercase charaacters should be replaced with their lowercase
268 equivalents.
269 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 Here are a couple of example conversions:
278 • "Lennart's PC" → "lennarts-pc"
280 • "Müllers Computer" → "muellers-computer"
282 • "Voran!" → "voran"
284 • "Es war einmal ein Männlein" → "es-war-einmal-ein-maennlein"
286 • "Jawoll. Ist doch wahr!" → "jawoll-ist-doch-wahr"
288 • "レナート" → "localhost"
290 • "...zack!!! zack!..." → "zack-zack"
292 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
300 These D-Bus interfaces follow the usual interface versioning
301 guidelines[2].
302
304 Example 1. Introspect org.freedesktop.hostname1 on the bus
305 $ gdbus introspect --system \
307 --dest org.freedesktop.hostname1 \
308 --object-path /org/freedesktop/hostname1
309
312 David Zeuthen's original Fedora Feature page about xdg-hostname[3]
313
315 1. polkit
316 https://www.freedesktop.org/software/polkit/docs/latest/
317 2. the usual interface versioning guidelines
319 http://0pointer.de/blog/projects/versioning-dbus.html
320 3. Feature page about xdg-hostname
322 https://fedoraproject.org/wiki/Features/BetterHostname
323systemd 250 ORG.FREEDESKTOP.HOSTNAME1(5)