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