]>
Commit | Line | Data |
---|---|---|
e09a36bd ZJS |
1 | <?xml version="1.0"?> |
2 | <!--*-nxml-*--> | |
3 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 4 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
e09a36bd ZJS |
5 | <!ENTITY % entities SYSTEM "custom-entities.ent" > |
6 | %entities; | |
7 | ]> | |
db9ecf05 | 8 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
e09a36bd ZJS |
9 | |
10 | <refentry id="org.freedesktop.hostname1" conditional='ENABLE_HOSTNAMED' | |
11 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
12 | <refentryinfo> | |
13 | <title>org.freedesktop.hostname1</title> | |
14 | <productname>systemd</productname> | |
15 | </refentryinfo> | |
16 | ||
17 | <refmeta> | |
18 | <refentrytitle>org.freedesktop.hostname1</refentrytitle> | |
19 | <manvolnum>5</manvolnum> | |
20 | </refmeta> | |
21 | ||
22 | <refnamediv> | |
23 | <refname>org.freedesktop.hostname1</refname> | |
24 | <refpurpose>The D-Bus interface of systemd-hostnamed</refpurpose> | |
25 | </refnamediv> | |
26 | ||
27 | <refsect1> | |
28 | <title>Introduction</title> | |
29 | ||
30 | <para> | |
31 | <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
8024ac43 | 32 | is a system service that can be used to control the hostname and related machine metadata from user |
e09a36bd ZJS |
33 | programs. This page describes the hostname semantics and the D-Bus interface.</para> |
34 | </refsect1> | |
35 | ||
36 | <refsect1> | |
37 | <title>The D-Bus API</title> | |
38 | ||
39 | <para>The service exposes the following interfaces on the bus:</para> | |
40 | ||
48f99d7c | 41 | <programlisting executable="systemd-hostnamed" node="/org/freedesktop/hostname1" interface="org.freedesktop.hostname1"> |
e09a36bd ZJS |
42 | node /org/freedesktop/hostname1 { |
43 | interface org.freedesktop.hostname1 { | |
44 | methods: | |
4fb222c4 ZJS |
45 | SetHostname(in s hostname, |
46 | in b interactive); | |
47 | SetStaticHostname(in s hostname, | |
48 | in b interactive); | |
49 | SetPrettyHostname(in s hostname, | |
50 | in b interactive); | |
51 | SetIconName(in s icon, | |
52 | in b interactive); | |
53 | SetChassis(in s chassis, | |
54 | in b interactive); | |
55 | SetDeployment(in s deployment, | |
56 | in b interactive); | |
57 | SetLocation(in s location, | |
58 | in b interactive); | |
59 | GetProductUUID(in b interactive, | |
60 | out ay uuid); | |
ff28d259 | 61 | GetHardwareSerial(out s serial); |
c068a17f | 62 | Describe(out s json); |
e09a36bd | 63 | properties: |
4fb222c4 ZJS |
64 | readonly s Hostname = '...'; |
65 | readonly s StaticHostname = '...'; | |
66 | readonly s PrettyHostname = '...'; | |
ce6b138c | 67 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
8770c813 | 68 | readonly s DefaultHostname = '...'; |
60e4fb42 | 69 | readonly s HostnameSource = '...'; |
4fb222c4 ZJS |
70 | readonly s IconName = '...'; |
71 | readonly s Chassis = '...'; | |
72 | readonly s Deployment = '...'; | |
73 | readonly s Location = '...'; | |
74 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
75 | readonly s KernelName = '...'; | |
76 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
77 | readonly s KernelRelease = '...'; | |
78 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
79 | readonly s KernelVersion = '...'; | |
80 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
81 | readonly s OperatingSystemPrettyName = '...'; | |
82 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
83 | readonly s OperatingSystemCPEName = '...'; | |
84 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
b563d5ce LP |
85 | readonly t OperatingSystemSupportEnd = ...; |
86 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
4fb222c4 | 87 | readonly s HomeURL = '...'; |
a4c3c5b7 YW |
88 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
89 | readonly s HardwareVendor = '...'; | |
90 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
91 | readonly s HardwareModel = '...'; | |
c52950c2 SS |
92 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
93 | readonly s FirmwareVersion = '...'; | |
f233bbd6 JW |
94 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
95 | readonly s FirmwareVendor = '...'; | |
ff4d26df | 96 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
ad8858c1 | 97 | readonly t FirmwareDate = ...; |
5db7eb21 YW |
98 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
99 | readonly ay MachineID = [...]; | |
100 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
101 | readonly ay BootID = [...]; | |
19b8e712 LP |
102 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
103 | readonly u VSockCID = ...; | |
e09a36bd | 104 | }; |
4fb222c4 ZJS |
105 | interface org.freedesktop.DBus.Peer { ... }; |
106 | interface org.freedesktop.DBus.Introspectable { ... }; | |
107 | interface org.freedesktop.DBus.Properties { ... }; | |
e09a36bd ZJS |
108 | }; |
109 | </programlisting> | |
110 | ||
00bb75d7 ZJS |
111 | <!--Autogenerated cross-references for systemd.directives, do not edit--> |
112 | ||
113 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/> | |
114 | ||
115 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/> | |
116 | ||
117 | <variablelist class="dbus-method" generated="True" extra-ref="SetHostname()"/> | |
118 | ||
119 | <variablelist class="dbus-method" generated="True" extra-ref="SetStaticHostname()"/> | |
120 | ||
121 | <variablelist class="dbus-method" generated="True" extra-ref="SetPrettyHostname()"/> | |
122 | ||
123 | <variablelist class="dbus-method" generated="True" extra-ref="SetIconName()"/> | |
124 | ||
125 | <variablelist class="dbus-method" generated="True" extra-ref="SetChassis()"/> | |
126 | ||
127 | <variablelist class="dbus-method" generated="True" extra-ref="SetDeployment()"/> | |
128 | ||
129 | <variablelist class="dbus-method" generated="True" extra-ref="SetLocation()"/> | |
130 | ||
131 | <variablelist class="dbus-method" generated="True" extra-ref="GetProductUUID()"/> | |
132 | ||
96976629 YW |
133 | <variablelist class="dbus-method" generated="True" extra-ref="GetHardwareSerial()"/> |
134 | ||
97a72436 LP |
135 | <variablelist class="dbus-method" generated="True" extra-ref="Describe()"/> |
136 | ||
00bb75d7 ZJS |
137 | <variablelist class="dbus-property" generated="True" extra-ref="Hostname"/> |
138 | ||
139 | <variablelist class="dbus-property" generated="True" extra-ref="StaticHostname"/> | |
140 | ||
141 | <variablelist class="dbus-property" generated="True" extra-ref="PrettyHostname"/> | |
142 | ||
8770c813 | 143 | <variablelist class="dbus-property" generated="True" extra-ref="DefaultHostname"/> |
ce6b138c | 144 | |
60e4fb42 ZJS |
145 | <variablelist class="dbus-property" generated="True" extra-ref="HostnameSource"/> |
146 | ||
00bb75d7 ZJS |
147 | <variablelist class="dbus-property" generated="True" extra-ref="IconName"/> |
148 | ||
149 | <variablelist class="dbus-property" generated="True" extra-ref="Chassis"/> | |
150 | ||
151 | <variablelist class="dbus-property" generated="True" extra-ref="Deployment"/> | |
152 | ||
153 | <variablelist class="dbus-property" generated="True" extra-ref="Location"/> | |
154 | ||
155 | <variablelist class="dbus-property" generated="True" extra-ref="KernelName"/> | |
156 | ||
157 | <variablelist class="dbus-property" generated="True" extra-ref="KernelRelease"/> | |
158 | ||
159 | <variablelist class="dbus-property" generated="True" extra-ref="KernelVersion"/> | |
160 | ||
161 | <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemPrettyName"/> | |
162 | ||
163 | <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemCPEName"/> | |
164 | ||
b563d5ce LP |
165 | <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemSupportEnd"/> |
166 | ||
00bb75d7 ZJS |
167 | <variablelist class="dbus-property" generated="True" extra-ref="HomeURL"/> |
168 | ||
a4c3c5b7 YW |
169 | <variablelist class="dbus-property" generated="True" extra-ref="HardwareVendor"/> |
170 | ||
171 | <variablelist class="dbus-property" generated="True" extra-ref="HardwareModel"/> | |
172 | ||
c52950c2 SS |
173 | <variablelist class="dbus-property" generated="True" extra-ref="FirmwareVersion"/> |
174 | ||
f233bbd6 JW |
175 | <variablelist class="dbus-property" generated="True" extra-ref="FirmwareVendor"/> |
176 | ||
ff4d26df JW |
177 | <variablelist class="dbus-property" generated="True" extra-ref="FirmwareDate"/> |
178 | ||
5db7eb21 YW |
179 | <variablelist class="dbus-property" generated="True" extra-ref="MachineID"/> |
180 | ||
181 | <variablelist class="dbus-property" generated="True" extra-ref="BootID"/> | |
182 | ||
19b8e712 LP |
183 | <variablelist class="dbus-property" generated="True" extra-ref="VSockCID"/> |
184 | ||
00bb75d7 ZJS |
185 | <!--End of Autogenerated section--> |
186 | ||
8024ac43 | 187 | <para>Whenever the hostname or other metadata is changed via the daemon, |
e09a36bd | 188 | <function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname |
98ab0dae ZJS |
189 | using this interface is authenticated via |
190 | <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para> | |
e09a36bd ZJS |
191 | </refsect1> |
192 | ||
193 | <refsect1> | |
194 | <title>Semantics</title> | |
195 | ||
de31bbc6 ZJS |
196 | <para>The <varname>StaticHostname</varname> property exposes the "static" hostname configured in |
197 | <filename>/etc/hostname</filename>. It is not always in sync with the current hostname as returned by the | |
4fb222c4 | 198 | <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
de31bbc6 | 199 | system call. If no static hostname is configured this property will be the empty string.</para> |
e09a36bd | 200 | |
de31bbc6 ZJS |
201 | <para>When <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> or |
202 | <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
203 | set the hostname, this static hostname <emphasis>has the highest priority</emphasis>.</para> | |
204 | ||
205 | <para>The <varname>Hostname</varname> property exposes the actual hostname configured in the kernel via | |
191b891b | 206 | <citerefentry project="man-pages"><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. |
de31bbc6 ZJS |
207 | It can be different from the static hostname. This property is never empty.</para> |
208 | ||
209 | <para>The <varname>PrettyHostname</varname> property exposes the <emphasis>pretty hostname</emphasis> | |
210 | which is a free-form UTF-8 hostname for presentation to the user. User interfaces should ensure that the | |
211 | pretty hostname and the static hostname stay in sync. E.g. when the former is <literal>Lennart’s | |
212 | Computer</literal> the latter should be <literal>lennarts-computer</literal>. If no pretty hostname is | |
213 | set this setting will be the empty string. Applications should then find a suitable fallback, such as the | |
214 | dynamic hostname.</para> | |
215 | ||
8770c813 ZJS |
216 | <para>The <varname>DefaultHostname</varname> property exposes the default hostname (configured through |
217 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, or a | |
218 | fallback set at compilation time).</para> | |
ce6b138c | 219 | |
60e4fb42 ZJS |
220 | <para>The <varname>HostnameSource</varname> property exposes the origin of the currently configured |
221 | hostname. One of <literal>static</literal> (set from <filename>/etc/hostname</filename>), | |
222 | <literal>transient</literal> (a non-permanent hostname from an external source), | |
3d62af7d | 223 | <literal>default</literal> (the value from <filename>os-release</filename> or the compiled-in |
8770c813 | 224 | fallback).</para> |
60e4fb42 | 225 | |
de31bbc6 ZJS |
226 | <para>The <varname>IconName</varname> property exposes the <emphasis>icon name</emphasis> following the |
227 | XDG icon naming spec. If not set, information such as the chassis type (see below) is used to find a | |
228 | suitable fallback icon name (i.e. <literal>computer-laptop</literal> | |
229 | vs. <literal>computer-desktop</literal> is picked based on the chassis information). If no such data is | |
230 | available, the empty string is returned. In that case an application should fall back to a replacement | |
231 | icon, for example <literal>computer</literal>. If this property is set to the empty string, the automatic | |
232 | fallback name selection is enabled again.</para> | |
233 | ||
234 | <para>The <varname>Chassis</varname> property exposes a <emphasis>chassis type</emphasis>, one of the | |
235 | currently defined chassis types: <literal>desktop</literal>, <literal>laptop</literal>, | |
236 | <literal>server</literal>, <literal>tablet</literal>, <literal>handset</literal>, as well as the special | |
237 | chassis types <literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that | |
238 | in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware | |
239 | information. Writing to this setting is hence useful only to override misdetected chassis types, or to | |
240 | configure the chassis type if it could not be auto-detected. Set this property to the empty string to | |
241 | reenable the automatic detection of the chassis type from firmware information.</para> | |
e09a36bd | 242 | |
e09a36bd ZJS |
243 | <para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a |
244 | short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent | |
245 | out for changes made directly on the files (as in: administrator edits the files with vi). This is | |
8024ac43 | 246 | the intended behavior: manual configuration changes should require manual reloading.</para> |
e09a36bd | 247 | |
de31bbc6 ZJS |
248 | <para>The transient (dynamic) hostname exposed by the <varname>Hostname</varname> property maps directly |
249 | to the kernel hostname. This hostname should be assumed to be highly dynamic, and hence should be watched | |
250 | directly, without depending on <function>PropertyChanged</function> messages from | |
251 | <filename>systemd-hostnamed</filename>. To accomplish this, open | |
252 | <filename>/proc/sys/kernel/hostname</filename> and | |
4fb222c4 | 253 | <citerefentry project="man-pages"><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
e09a36bd ZJS |
254 | for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again: |
255 | this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) | |
256 | hostname.</para> | |
257 | ||
8024ac43 | 258 | <para>Applications may read the hostname data directly if hostname change notifications |
e09a36bd | 259 | are not necessary. Use |
191b891b | 260 | <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, |
e09a36bd ZJS |
261 | <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and |
262 | <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
263 | for that. For more information on these files and syscalls see the respective man pages.</para> | |
264 | ||
97a72436 LP |
265 | <para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and |
266 | <varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release | |
267 | (e.g. <literal>5.0.0-11</literal>), and version (i.e. the build number, e.g. <literal>#11</literal>) as | |
268 | reported by <citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
269 | <varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and | |
270 | <varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and | |
271 | <varname>HOME_URL=</varname> fields from | |
272 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The | |
273 | purpose of those properties is to allow remote clients to access this information over D-Bus. Local | |
274 | clients can access the information directly.</para> | |
275 | ||
19b8e712 LP |
276 | <para><varname>MachineID</varname> expose the 128bit machine ID, see |
277 | <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
278 | details.</para> | |
279 | ||
280 | <para><varname>BootID</varname> expose the 128bit boot ID, as per | |
281 | <filename>/proc/sys/kernel/random/boot_id</filename>.</para> | |
282 | ||
283 | <para><varname>VSockCID</varname> exposes the system's local <constant>AF_VSOCK</constant> CID (Context | |
284 | Identifier, i.e. address) for the system, if one is available in the virtual machine environment. Set to | |
285 | <constant>UINT32_MAX</constant> otherwise. See <citerefentry project="man-pages"><refentrytitle>vsock</refentrytitle><manvolnum>7</manvolnum></citerefentry> for | |
286 | details.</para> | |
287 | ||
fa6ea809 LP |
288 | <para><varname>OperatingSystemSupportEnd</varname> exposes when the OS' vendor support ends, if this |
289 | information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If this information | |
290 | is not known carries the value 2^64-1, i.e. <constant>UINT64_MAX</constant>.</para> | |
291 | ||
292 | <para><varname>HardwareVendor</varname> and <varname>HardwareModel</varname> expose information about the | |
293 | vendor of the hardware of the system. If no such information can be determined these properties are set | |
294 | to empty strings.</para> | |
295 | ||
296 | <para><varname>FirmwareVersion</varname> and <varname>FirmwareVendor</varname> expose information about | |
297 | the system's firmware, i.e. a version string and a vendor name. If no such information can be determined | |
298 | these properties are set to empty strings.</para> | |
299 | ||
300 | <para><varname>FirmwareDate</varname> exposes the firmware build date, if that information is known. It's | |
301 | an unsigned 64bit value, in µs since the UNIX epoch, UTC. If not known | |
302 | <constant>UNIT64_MAX</constant>.</para> | |
303 | ||
5d2262d7 | 304 | <refsect2> |
de31bbc6 | 305 | <title>Methods</title> |
5d2262d7 | 306 | |
de31bbc6 ZJS |
307 | <para><function>SetHostname()</function> sets the transient (dynamic) hostname, which is used if no |
308 | static hostname is set. This value must be an internet-style hostname, 7-bit lowercase ASCII, no | |
309 | special chars/spaces. An empty string will unset the transient hostname.</para> | |
5d2262d7 ZJS |
310 | |
311 | <para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the | |
de31bbc6 ZJS |
312 | <varname>StaticHostname</varname> property. When called with an empty argument, the static |
313 | configuration in <filename>/etc/hostname</filename> is removed. Since the static hostname has the | |
314 | highest priority, calling this function usually affects also the <varname>Hostname</varname> property | |
315 | and the effective hostname configured in the kernel.</para> | |
5d2262d7 ZJS |
316 | |
317 | <para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the | |
318 | <varname>PrettyHostname</varname> property.</para> | |
319 | ||
320 | <para><function>SetIconName()</function>, <function>SetChassis()</function>, | |
321 | <function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties | |
322 | <varname>IconName</varname> (the name of the icon representing for the machine), | |
323 | <varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system | |
324 | deployment environment), and <varname>Location</varname> (physical system location), respectively. | |
325 | </para> | |
326 | ||
327 | <para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>, | |
328 | <varname>Deployment</varname>, and <varname>Location</varname> are stored in | |
329 | <filename>/etc/machine-info</filename>. See | |
330 | <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
331 | the semantics of those settings.</para> | |
332 | ||
97a72436 | 333 | <para><function>GetProductUUID()</function> returns the "product UUID" as exposed by the kernel based |
5d2262d7 | 334 | on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly |
98ab0dae | 335 | requires root privileges, and this method allows access to unprivileged clients through the polkit |
5d2262d7 ZJS |
336 | framework.</para> |
337 | ||
fa6ea809 LP |
338 | <para><function>GetHardwareSerial()</function> returns the "hardware serial" as exposed by the kernel |
339 | based on DMI information. Reading the file directly requires root privileges, and this method allows | |
340 | access to unprivileged clients through the polkit framework.</para> | |
341 | ||
97a72436 | 342 | <para><function>Describe()</function> returns a JSON representation of all properties in one.</para> |
5d2262d7 ZJS |
343 | </refsect2> |
344 | ||
debf2ddd ZJS |
345 | <refsect2> |
346 | <title>Security</title> | |
347 | ||
98ab0dae | 348 | <para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit |
debf2ddd ZJS |
349 | should interactively ask the user for authentication credentials if required.</para> |
350 | ||
98ab0dae | 351 | <para>The polkit action for <function>SetHostname()</function> is |
debf2ddd ZJS |
352 | <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For |
353 | <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is | |
354 | <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For | |
50f7b8fb LW |
355 | <function>SetIconName()</function>, <function>SetChassis()</function>, <function>SetDeployment()</function> |
356 | and <function>SetLocation()</function> it is | |
debf2ddd ZJS |
357 | <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para> |
358 | </refsect2> | |
359 | </refsect1> | |
e09a36bd | 360 | |
debf2ddd ZJS |
361 | <refsect1> |
362 | <title>Recommendations</title> | |
e09a36bd | 363 | |
debf2ddd | 364 | <para>Here are three examples that show how the pretty hostname and the icon name should be used: |
e09a36bd | 365 | <itemizedlist> |
debf2ddd ZJS |
366 | <listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass |
367 | the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon | |
368 | on each service. This is especially useful for WebDAV applications or UPnP media sharing. | |
8024ac43 | 369 | </para></listitem> |
e09a36bd | 370 | |
8024ac43 | 371 | <listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem> |
e09a36bd | 372 | |
debf2ddd ZJS |
373 | <listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname |
374 | if set, and the icon with the icon name, if it is set.</para></listitem> | |
e09a36bd ZJS |
375 | </itemizedlist></para> |
376 | ||
377 | <para>To properly handle name lookups with changing local hostnames without having to edit | |
debf2ddd ZJS |
378 | <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination |
379 | with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
e09a36bd ZJS |
380 | </para> |
381 | ||
382 | <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty | |
383 | name: | |
384 | <itemizedlist> | |
385 | <listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, | |
8024ac43 | 386 | or replace them with <literal>-</literal>.</para></listitem> |
e09a36bd | 387 | |
8024ac43 | 388 | <listitem><para>It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way |
e09a36bd ZJS |
389 | these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>. |
390 | Strip other chars, or try to replace them in some smart way with chars from this set, for example | |
8024ac43 ZJS |
391 | <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as the replacement for all |
392 | punctuation characters and whitespace.</para></listitem> | |
e09a36bd ZJS |
393 | |
394 | <listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as | |
395 | the first or last char.</para></listitem> | |
396 | ||
397 | <listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem> | |
398 | ||
399 | <listitem><para>If after stripping special chars the empty string is the result, you can pass this | |
8770c813 ZJS |
400 | as-is to <filename>systemd-hostnamed</filename> in which case it will automatically use a suitable |
401 | fallback.</para></listitem> | |
e09a36bd | 402 | |
6ebfecd0 | 403 | <listitem><para>Uppercase characters should be replaced with their lowercase equivalents. |
8024ac43 | 404 | </para></listitem> |
e09a36bd ZJS |
405 | </itemizedlist></para> |
406 | ||
407 | <para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass | |
408 | they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename> | |
8024ac43 | 409 | will also accept <literal>_</literal> in the hostname, but we recommend not using this to avoid clashes |
e09a36bd | 410 | with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but |
8024ac43 | 411 | because of the DNS label limitations, we recommend not making use of this.</para> |
e09a36bd ZJS |
412 | |
413 | <para>Here are a couple of example conversions: | |
414 | <itemizedlist> | |
415 | <listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem> | |
416 | <listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem> | |
417 | <listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem> | |
418 | <listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem> | |
419 | <listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem> | |
420 | <listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem> | |
421 | <listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem> | |
422 | </itemizedlist></para> | |
423 | ||
8024ac43 | 424 | <para>Of course, an already valid internet hostname label you enter and pass through this |
debf2ddd | 425 | conversion should stay unmodified, so that users have direct control of it, if they want — by simply |
e09a36bd ZJS |
426 | ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet |
427 | name.</para> | |
428 | </refsect1> | |
429 | ||
e4239a34 | 430 | <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> |
e09a36bd | 431 | |
48f99d7c ZJS |
432 | <refsect1> |
433 | <title>Examples</title> | |
434 | ||
435 | <example> | |
436 | <title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title> | |
437 | ||
438 | <programlisting>$ gdbus introspect --system \ | |
439 | --dest org.freedesktop.hostname1 \ | |
440 | --object-path /org/freedesktop/hostname1 | |
441 | </programlisting> | |
442 | </example> | |
443 | </refsect1> | |
444 | ||
e09a36bd | 445 | <refsect1> |
59b44379 | 446 | <title>See Also</title> |
e09a36bd ZJS |
447 | |
448 | <para>David Zeuthen's original Fedora | |
449 | <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para> | |
450 | </refsect1> | |
d9d2d16a AK |
451 | |
452 | <refsect1> | |
453 | <title>History</title> | |
454 | <refsect2> | |
455 | <title>The D-Bus API</title> | |
456 | <para><varname>FirmwareVersion</varname> and | |
457 | <function>GetHardwareSerial()</function> were added in version 251.</para> | |
458 | <para><varname>OperatingSystemSupportEnd</varname>, | |
459 | <varname>FirmwareVendor</varname>, and | |
460 | <varname>FirmwareDate</varname> were added in version 253.</para> | |
19b8e712 LP |
461 | <para><varname>MachineID</varname>, <varname>BootID</varname> and |
462 | <varname>VSockCID</varname> were added in version 256.</para> | |
d9d2d16a AK |
463 | </refsect2> |
464 | </refsect1> | |
e09a36bd | 465 | </refentry> |