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