Debian Codegraph @

upstream/opensuse-tumbleweed/man5/org.freedesktop.hostname1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.HOSTNAME1" "5" "" "systemd 260.1" "org.freedesktop.hostname1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.hostname1 \- The D\-Bus interface of systemd\-hostnamed
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-hostnamed.service\fR(8)
27 is a system service that can be used to control the hostname and related machine metadata from user programs\&. This page describes the hostname semantics and the D\-Bus interface\&.
28 .SH "THE D\-BUS API"
29 .PP
30 The service exposes the following interfaces on the bus:
31 .sp
32 .if n \{\
33 .RS 4
34 .\}
35 .nf
36 node /org/freedesktop/hostname1 {
37 interface org\&.freedesktop\&.hostname1 {
38 methods:
39 SetHostname(in s hostname,
40 in b interactive);
41 SetStaticHostname(in s hostname,
42 in b interactive);
43 SetPrettyHostname(in s hostname,
44 in b interactive);
45 SetIconName(in s icon,
46 in b interactive);
47 SetChassis(in s chassis,
48 in b interactive);
49 SetDeployment(in s deployment,
50 in b interactive);
51 SetLocation(in s location,
52 in b interactive);
53 GetProductUUID(in b interactive,
54 out ay uuid);
55 GetHardwareSerial(out s serial);
56 Describe(out s json);
57 properties:
58 readonly s Hostname = \*(Aq\&.\&.\&.\*(Aq;
59 readonly s StaticHostname = \*(Aq\&.\&.\&.\*(Aq;
60 readonly s PrettyHostname = \*(Aq\&.\&.\&.\*(Aq;
61 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
62 readonly s DefaultHostname = \*(Aq\&.\&.\&.\*(Aq;
63 readonly s HostnameSource = \*(Aq\&.\&.\&.\*(Aq;
64 readonly s IconName = \*(Aq\&.\&.\&.\*(Aq;
65 readonly s Chassis = \*(Aq\&.\&.\&.\*(Aq;
66 readonly s Deployment = \*(Aq\&.\&.\&.\*(Aq;
67 readonly s Location = \*(Aq\&.\&.\&.\*(Aq;
68 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
69 readonly s KernelName = \*(Aq\&.\&.\&.\*(Aq;
70 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
71 readonly s KernelRelease = \*(Aq\&.\&.\&.\*(Aq;
72 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
73 readonly s KernelVersion = \*(Aq\&.\&.\&.\*(Aq;
74 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
75 readonly s OperatingSystemPrettyName = \*(Aq\&.\&.\&.\*(Aq;
76 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
77 readonly s OperatingSystemFancyName = \*(Aq\&.\&.\&.\*(Aq;
78 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
79 readonly s OperatingSystemCPEName = \*(Aq\&.\&.\&.\*(Aq;
80 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
81 readonly t OperatingSystemSupportEnd = \&.\&.\&.;
82 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
83 readonly s HomeURL = \*(Aq\&.\&.\&.\*(Aq;
84 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
85 readonly s OperatingSystemImageID = \*(Aq\&.\&.\&.\*(Aq;
86 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
87 readonly s OperatingSystemImageVersion = \*(Aq\&.\&.\&.\*(Aq;
88 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
89 readonly s HardwareVendor = \*(Aq\&.\&.\&.\*(Aq;
90 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
91 readonly s HardwareModel = \*(Aq\&.\&.\&.\*(Aq;
92 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
93 readonly s HardwareSKU = \*(Aq\&.\&.\&.\*(Aq;
94 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
95 readonly s HardwareVersion = \*(Aq\&.\&.\&.\*(Aq;
96 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
97 readonly s FirmwareVersion = \*(Aq\&.\&.\&.\*(Aq;
98 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
99 readonly s FirmwareVendor = \*(Aq\&.\&.\&.\*(Aq;
100 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
101 readonly t FirmwareDate = \&.\&.\&.;
102 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
103 readonly ay MachineID = [\&.\&.\&.];
104 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
105 readonly ay BootID = [\&.\&.\&.];
106 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
107 readonly u VSockCID = \&.\&.\&.;
108 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
109 readonly s ChassisAssetTag = \*(Aq\&.\&.\&.\*(Aq;
110 };
111 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
112 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
113 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
114 };
115 .fi
116 .if n \{\
117 .RE
118 .\}
119 .sp
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161 .PP
162 Whenever the hostname or other metadata is changed via the daemon,
163 \fBPropertyChanged\fR
164 signals are sent out to subscribed clients\&. Changing a hostname using this interface is authenticated via
165 \m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2\&.
166 .SH "SEMANTICS"
167 .PP
168 The
169 \fIStaticHostname\fR
170 property exposes the "static" hostname configured in
171 /etc/hostname\&. It is not always in sync with the current hostname as returned by the
172 \fBgethostname\fR(3)
173 system call\&. If no static hostname is configured this property will be the empty string\&.
174 .PP
175 When
176 \fBsystemd\fR(1)
177 or
178 \fBsystemd-hostnamed.service\fR(8)
179 set the hostname, this static hostname
180 \fIhas the highest priority\fR\&.
181 .PP
182 The
183 \fIHostname\fR
184 property exposes the actual hostname configured in the kernel via
185 \fBsethostname\fR(2)\&. It can be different from the static hostname\&. This property is never empty\&.
186 .PP
187 The
188 \fIPrettyHostname\fR
189 property exposes the
190 \fIpretty hostname\fR
191 which is a free\-form UTF\-8 hostname for presentation to the user\&. User interfaces should ensure that the pretty hostname and the static hostname stay in sync\&. E\&.g\&. when the former is
192 "Lennart\(cqs Computer"
193 the latter should be
194 "lennarts\-computer"\&. If no pretty hostname is set this setting will be the empty string\&. Applications should then find a suitable fallback, such as the dynamic hostname\&.
195 .PP
196 The
197 \fIDefaultHostname\fR
198 property exposes the default hostname (configured through
199 \fBos-release\fR(5), or a fallback set at compilation time)\&.
200 .PP
201 The
202 \fIHostnameSource\fR
203 property exposes the origin of the currently configured hostname\&. One of
204 "static"
205 (set from
206 /etc/hostname),
207 "transient"
208 (a non\-permanent hostname from an external source),
209 "default"
210 (the value from
211 os\-release
212 or the compiled\-in fallback)\&.
213 .PP
214 The
215 \fIIconName\fR
216 property exposes the
217 \fIicon name\fR
218 following the XDG icon naming spec\&. If not set, information such as the chassis type (see below) is used to find a suitable fallback icon name (i\&.e\&.
219 "computer\-laptop"
220 vs\&.
221 "computer\-desktop"
222 is picked based on the chassis information)\&. If no such data is available, the empty string is returned\&. In that case an application should fall back to a replacement icon, for example
223 "computer"\&. If this property is set to the empty string, the automatic fallback name selection is enabled again\&.
224 .PP
225 The
226 \fIChassis\fR
227 property exposes a
228 \fIchassis type\fR, one of the currently defined chassis types:
229 "desktop",
230 "laptop",
231 "server",
232 "tablet",
233 "handset", as well as the special chassis types
234 "vm"
235 and
236 "container"
237 for virtualized systems\&. Note that in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information\&. Writing to this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if it could not be auto\-detected\&. Set this property to the empty string to reenable the automatic detection of the chassis type from firmware information\&.
238 .PP
239 Note that
240 systemd\-hostnamed
241 starts only on request and terminates after a short idle period\&. This effectively means that
242 \fBPropertyChanged\fR
243 messages are not sent out for changes made directly on the files (as in: administrator edits the files with vi)\&. This is the intended behavior: manual configuration changes should require manual reloading\&.
244 .PP
245 The transient (dynamic) hostname exposed by the
246 \fIHostname\fR
247 property maps directly to the kernel hostname\&. This hostname should be assumed to be highly dynamic, and hence should be watched directly, without depending on
248 \fBPropertyChanged\fR
249 messages from
250 systemd\-hostnamed\&. To accomplish this, open
251 /proc/sys/kernel/hostname
252 and
253 \fBpoll\fR(3)
254 for
255 \fBSIGHUP\fR
256 which is triggered by the kernel every time the hostname changes\&. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname\&.
257 .PP
258 Applications may read the hostname data directly if hostname change notifications are not necessary\&. Use
259 \fBgethostname\fR(2),
260 /etc/hostname
261 (possibly with per\-distribution fallbacks), and
262 \fBmachine-info\fR(5)
263 for that\&. For more information on these files and syscalls see the respective man pages\&.
264 .PP
265 \fIKernelName\fR,
266 \fIKernelRelease\fR, and
267 \fIKernelVersion\fR
268 expose the kernel name (e\&.g\&.
269 "Linux"), release (e\&.g\&.
270 "5\&.0\&.0\-11"), and version (i\&.e\&. the build number, e\&.g\&.
271 "#11") as reported by
272 \fBuname\fR(2)\&.
273 .PP
274 \fIOperatingSystemPrettyName\fR,
275 \fIOperatingSystemFancyName\fR,
276 \fIOperatingSystemCPEName\fR, and
277 \fIHomeURL\fR
278 expose the
279 \fIPRETTY_NAME=\fR,
280 \fIFANCY_NAME=\fR,
281 \fICPE_NAME=\fR
282 and
283 \fIHOME_URL=\fR
284 fields from
285 \fBos-release\fR(5)\&. The purpose of those properties is to allow remote clients to access this information over D\-Bus\&. Local clients can access the information directly\&.
286 .PP
287 \fIMachineID\fR
288 expose the 128bit machine ID, see
289 \fBmachine-id\fR(5)
290 for details\&.
291 .PP
292 \fIBootID\fR
293 expose the 128bit boot ID, as per
294 /proc/sys/kernel/random/boot_id\&.
295 .PP
296 \fIVSockCID\fR
297 exposes the system\*(Aqs local
298 \fBAF_VSOCK\fR
299 CID (Context Identifier, i\&.e\&. address) for the system, if one is available in the virtual machine environment\&. Set to
300 \fBUINT32_MAX\fR
301 otherwise\&. See
302 \fBvsock\fR(7)
303 for details\&.
304 .PP
305 \fIOperatingSystemSupportEnd\fR
306 exposes when the OS\*(Aq vendor support ends, if this information is known\&. It\*(Aqs an unsigned 64bit value, in \(mcs since the UNIX epoch, UTC\&. If this information is not known carries the value 2^64\-1, i\&.e\&.
307 \fBUINT64_MAX\fR\&.
308 .PP
309 \fIOperatingSystemImageID\fR
310 and
311 \fIOperatingSystemImageVersion\fR
312 expose the OS image name and version if available, or contain empty strings otherwise\&. This mostly corresponds to the
313 \fIIMAGE_ID=\fR
314 and
315 \fIIMAGE_VERSION=\fR
316 fields of the
317 os\-release
318 file\&.
319 .PP
320 \fIHardwareVendor\fR,
321 \fIHardwareModel\fR,
322 \fIHardwareSKU\fR, and
323 \fIHardwareVersion\fR
324 expose vendor information about the hardware of the system\&. The stock keeping unit (SKU) describes a distinct type of hardware for sale, purchase or inventory management\&. The SKU and version are only available if they deviate from the model and among each other\&. Thereby the version is more specific and only available if it differs from the model and SKU\&. If no such information can be determined these properties are set to empty strings\&.
325 .PP
326 \fIFirmwareVersion\fR
327 and
328 \fIFirmwareVendor\fR
329 expose information about the system\*(Aqs firmware, i\&.e\&. a version string and a vendor name\&. If no such information can be determined these properties are set to empty strings\&.
330 .PP
331 \fIFirmwareDate\fR
332 exposes the firmware build date, if that information is known\&. It\*(Aqs an unsigned 64bit value, in \(mcs since the UNIX epoch, UTC\&. If not known
333 \fBUNIT64_MAX\fR\&.
334 .PP
335 \fIChassisAssetTag\fR
336 exposes an unique identifier of the system chassis\&. If this information is not known this property is set to an empty string\&.
337 .SS "Methods"
338 .PP
339 \fBSetHostname()\fR
340 sets the transient (dynamic) hostname, which is used if no static hostname is set\&. This value must be an internet\-style hostname, 7\-bit lowercase ASCII, no special chars/spaces\&. An empty string will unset the transient hostname\&.
341 .PP
342 \fBSetStaticHostname()\fR
343 sets the static hostname which is exposed by the
344 \fIStaticHostname\fR
345 property\&. When called with an empty argument, the static configuration in
346 /etc/hostname
347 is removed\&. Since the static hostname has the highest priority, calling this function usually affects also the
348 \fIHostname\fR
349 property and the effective hostname configured in the kernel\&.
350 .PP
351 \fBSetPrettyHostname()\fR
352 sets the pretty hostname which is exposed by the
353 \fIPrettyHostname\fR
354 property\&.
355 .PP
356 \fBSetIconName()\fR,
357 \fBSetChassis()\fR,
358 \fBSetDeployment()\fR, and
359 \fBSetLocation()\fR
360 set the properties
361 \fIIconName\fR
362 (the name of the icon representing for the machine),
363 \fIChassis\fR
364 (the machine form factor),
365 \fIDeployment\fR
366 (the system deployment environment), and
367 \fILocation\fR
368 (physical system location), respectively\&.
369 .PP
370 \fIPrettyHostname\fR,
371 \fIIconName\fR,
372 \fIChassis\fR,
373 \fIDeployment\fR, and
374 \fILocation\fR
375 are stored in
376 /etc/machine\-info\&. See
377 \fBmachine-info\fR(5)
378 for the semantics of those settings\&.
379 .PP
380 \fBGetProductUUID()\fR
381 returns the "product UUID" as exposed by the kernel based on DMI information in
382 /sys/class/dmi/id/product_uuid\&. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework\&.
383 .PP
384 \fBGetHardwareSerial()\fR
385 returns the "hardware serial" as exposed by the kernel based on DMI information\&. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework\&.
386 .PP
387 \fBDescribe()\fR
388 returns a JSON representation of all properties in one\&.
389 .SS "Security"
390 .PP
391 The
392 \fIinteractive\fR
393 boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required\&.
394 .PP
395 The polkit action for
396 \fBSetHostname()\fR
397 is
398 org\&.freedesktop\&.hostname1\&.set\-hostname\&. For
399 \fBSetStaticHostname()\fR
400 and
401 \fBSetPrettyHostname()\fR
402 it is
403 org\&.freedesktop\&.hostname1\&.set\-static\-hostname\&. For
404 \fBSetIconName()\fR,
405 \fBSetChassis()\fR,
406 \fBSetDeployment()\fR
407 and
408 \fBSetLocation()\fR
409 it is
410 org\&.freedesktop\&.hostname1\&.set\-machine\-info\&.
411 .SH "RECOMMENDATIONS"
412 .PP
413 Here are three examples that show how the pretty hostname and the icon name should be used:
414 .sp
415 .RS 4
416 .ie n \{\
417 \h'-04'\(bu\h'+03'\c
418 .\}
419 .el \{\
420 .sp -1
421 .IP \(bu 2.3
422 .\}
423 When registering DNS\-SD services: use the pretty hostname in the service name, and pass the icon name in the TXT data, if there is an icon name\&. Browsing clients can then show the server icon on each service\&. This is especially useful for WebDAV applications or UPnP media sharing\&.
424 .RE
425 .sp
426 .RS 4
427 .ie n \{\
428 \h'-04'\(bu\h'+03'\c
429 .\}
430 .el \{\
431 .sp -1
432 .IP \(bu 2.3
433 .\}
434 Set the bluetooth name to the pretty hostname\&.
435 .RE
436 .sp
437 .RS 4
438 .ie n \{\
439 \h'-04'\(bu\h'+03'\c
440 .\}
441 .el \{\
442 .sp -1
443 .IP \(bu 2.3
444 .\}
445 When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set\&.
446 .RE
447 .PP
448 To properly handle name lookups with changing local hostnames without having to edit
449 /etc/hosts, we recommend using
450 systemd\-hostnamed
451 in combination with
452 \fBnss-myhostname\fR(8)\&.
453 .PP
454 Here are some recommendations to follow when generating a static (internet) hostname from a pretty name:
455 .sp
456 .RS 4
457 .ie n \{\
458 \h'-04'\(bu\h'+03'\c
459 .\}
460 .el \{\
461 .sp -1
462 .IP \(bu 2.3
463 .\}
464 Generate a single DNS label only, not an FQDN\&. That means no dots allowed\&. Strip them, or replace them with
465 "\-"\&.
466 .RE
467 .sp
468 .RS 4
469 .ie n \{\
470 \h'-04'\(bu\h'+03'\c
471 .\}
472 .el \{\
473 .sp -1
474 .IP \(bu 2.3
475 .\}
476 It\*(Aqs probably safer to not use any non\-ASCII chars, even if DNS allows this in some way these days\&. In fact, restrict your charset to
477 "a\-zA\-Z0\-9"
478 and
479 "\-"\&. Strip other chars, or try to replace them in some smart way with chars from this set, for example
480 "ä"
481 →
482 "ae", and use
483 "\-"
484 as the replacement for all punctuation characters and whitespace\&.
485 .RE
486 .sp
487 .RS 4
488 .ie n \{\
489 \h'-04'\(bu\h'+03'\c
490 .\}
491 .el \{\
492 .sp -1
493 .IP \(bu 2.3
494 .\}
495 Try to avoid creating repeated
496 "\-", as well as
497 "\-"
498 as the first or last char\&.
499 .RE
500 .sp
501 .RS 4
502 .ie n \{\
503 \h'-04'\(bu\h'+03'\c
504 .\}
505 .el \{\
506 .sp -1
507 .IP \(bu 2.3
508 .\}
509 Limit the hostname to 63 chars, which is the length of a DNS label\&.
510 .RE
511 .sp
512 .RS 4
513 .ie n \{\
514 \h'-04'\(bu\h'+03'\c
515 .\}
516 .el \{\
517 .sp -1
518 .IP \(bu 2.3
519 .\}
520 If after stripping special chars the empty string is the result, you can pass this as\-is to
521 systemd\-hostnamed
522 in which case it will automatically use a suitable fallback\&.
523 .RE
524 .sp
525 .RS 4
526 .ie n \{\
527 \h'-04'\(bu\h'+03'\c
528 .\}
529 .el \{\
530 .sp -1
531 .IP \(bu 2.3
532 .\}
533 Uppercase characters should be replaced with their lowercase equivalents\&.
534 .RE
535 .PP
536 Note that while
537 systemd\-hostnamed
538 applies some checks to the hostname you pass they are much looser than the recommendations above\&. For example,
539 systemd\-hostnamed
540 will also accept
541 "_"
542 in the hostname, but we recommend not using this to avoid clashes with DNS\-SD service types\&. Also
543 systemd\-hostnamed
544 allows longer hostnames, but because of the DNS label limitations, we recommend not making use of this\&.
545 .PP
546 Here are a couple of example conversions:
547 .sp
548 .RS 4
549 .ie n \{\
550 \h'-04'\(bu\h'+03'\c
551 .\}
552 .el \{\
553 .sp -1
554 .IP \(bu 2.3
555 .\}
556 "Lennart\*(Aqs PC"
557 →
558 "lennarts\-pc"
559 .RE
560 .sp
561 .RS 4
562 .ie n \{\
563 \h'-04'\(bu\h'+03'\c
564 .\}
565 .el \{\
566 .sp -1
567 .IP \(bu 2.3
568 .\}
569 "Müllers Computer"
570 →
571 "muellers\-computer"
572 .RE
573 .sp
574 .RS 4
575 .ie n \{\
576 \h'-04'\(bu\h'+03'\c
577 .\}
578 .el \{\
579 .sp -1
580 .IP \(bu 2.3
581 .\}
582 "Voran!"
583 →
584 "voran"
585 .RE
586 .sp
587 .RS 4
588 .ie n \{\
589 \h'-04'\(bu\h'+03'\c
590 .\}
591 .el \{\
592 .sp -1
593 .IP \(bu 2.3
594 .\}
595 "Es war einmal ein Männlein"
596 →
597 "es\-war\-einmal\-ein\-maennlein"
598 .RE
599 .sp
600 .RS 4
601 .ie n \{\
602 \h'-04'\(bu\h'+03'\c
603 .\}
604 .el \{\
605 .sp -1
606 .IP \(bu 2.3
607 .\}
608 "Jawoll\&. Ist doch wahr!"
609 →
610 "jawoll\-ist\-doch\-wahr"
611 .RE
612 .sp
613 .RS 4
614 .ie n \{\
615 \h'-04'\(bu\h'+03'\c
616 .\}
617 .el \{\
618 .sp -1
619 .IP \(bu 2.3
620 .\}
621 "レナート"
622 →
623 "localhost"
624 .RE
625 .sp
626 .RS 4
627 .ie n \{\
628 \h'-04'\(bu\h'+03'\c
629 .\}
630 .el \{\
631 .sp -1
632 .IP \(bu 2.3
633 .\}
634 "\&.\&.\&.zack!!! zack!\&.\&.\&."
635 →
636 "zack\-zack"
637 .RE
638 .PP
639 Of course, an already valid internet hostname label you enter and pass through this conversion should stay unmodified, so that users have direct control of it, if they want \(em by simply ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet name\&.
640 .SH "EXAMPLES"
641 .PP
642 \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.hostname1 on the bus\fR
643 .sp
644 .if n \{\
645 .RS 4
646 .\}
647 .nf
648 $ gdbus introspect \-\-system \e
649 \-\-dest org\&.freedesktop\&.hostname1 \e
650 \-\-object\-path /org/freedesktop/hostname1
651 .fi
652 .if n \{\
653 .RE
654 .\}
655 .SH "VERSIONING"
656 .PP
657 These D\-Bus interfaces follow
658 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&.
659 .SH "HISTORY"
660 .SS "The D\-Bus API"
661 .PP
662 \fIFirmwareVersion\fR
663 and
664 \fBGetHardwareSerial()\fR
665 were added in version 251\&.
666 .PP
667 \fIOperatingSystemSupportEnd\fR,
668 \fIFirmwareVendor\fR, and
669 \fIFirmwareDate\fR
670 were added in version 253\&.
671 .PP
672 \fIMachineID\fR,
673 \fIBootID\fR
674 and
675 \fIVSockCID\fR
676 were added in version 256\&.
677 .PP
678 \fIChassisAssetTag\fR,
679 \fIOperatingSystemImageID\fR,
680 \fIOperatingSystemImageVersion\fR,
681 \fIHardwareSKU\fR, and
682 \fIHardwareVersion\fR
683 were added in version 258\&.
684 .PP
685 \fIOperatingSystemFancyName\fR
686 was added in version 260\&.
687 .SH "SEE ALSO"
688 .PP
689 \fBsystemd\fR(1), \fBsystemd-hostnamed.service\fR(8), \fBhostnamectl\fR(1), David Zeuthen\*(Aqs original Fedora \m[blue]\fBFeature page about xdg\-hostname\fR\m[]\&\s-2\u[3]\d\s+2
690 .SH "NOTES"
691 .IP " 1." 4
692 polkit
693 .RS 4
694 \%https://www.freedesktop.org/software/polkit/docs/latest/
695 .RE
696 .IP " 2." 4
697 the usual interface versioning guidelines
698 .RS 4
699 \%https://0pointer.de/blog/projects/versioning-dbus.html
700 .RE
701 .IP " 3." 4
702 Feature page about xdg-hostname
703 .RS 4
704 \%https://fedoraproject.org/wiki/Features/BetterHostname
705 .RE