]>
Commit | Line | Data |
---|---|---|
e09a36bd ZJS |
1 | <?xml version="1.0"?> |
2 | <!--*-nxml-*--> | |
3 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
4 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ | |
5 | <!ENTITY % entities SYSTEM "custom-entities.ent" > | |
6 | %entities; | |
7 | ]> | |
8 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> | |
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); | |
e09a36bd | 61 | properties: |
4fb222c4 ZJS |
62 | readonly s Hostname = '...'; |
63 | readonly s StaticHostname = '...'; | |
64 | readonly s PrettyHostname = '...'; | |
65 | readonly s IconName = '...'; | |
66 | readonly s Chassis = '...'; | |
67 | readonly s Deployment = '...'; | |
68 | readonly s Location = '...'; | |
69 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
70 | readonly s KernelName = '...'; | |
71 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
72 | readonly s KernelRelease = '...'; | |
73 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
74 | readonly s KernelVersion = '...'; | |
75 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
76 | readonly s OperatingSystemPrettyName = '...'; | |
77 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
78 | readonly s OperatingSystemCPEName = '...'; | |
79 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
80 | readonly s HomeURL = '...'; | |
e09a36bd | 81 | }; |
4fb222c4 ZJS |
82 | interface org.freedesktop.DBus.Peer { ... }; |
83 | interface org.freedesktop.DBus.Introspectable { ... }; | |
84 | interface org.freedesktop.DBus.Properties { ... }; | |
e09a36bd ZJS |
85 | }; |
86 | </programlisting> | |
87 | ||
00bb75d7 ZJS |
88 | <!--Autogenerated cross-references for systemd.directives, do not edit--> |
89 | ||
90 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/> | |
91 | ||
92 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/> | |
93 | ||
94 | <variablelist class="dbus-method" generated="True" extra-ref="SetHostname()"/> | |
95 | ||
96 | <variablelist class="dbus-method" generated="True" extra-ref="SetStaticHostname()"/> | |
97 | ||
98 | <variablelist class="dbus-method" generated="True" extra-ref="SetPrettyHostname()"/> | |
99 | ||
100 | <variablelist class="dbus-method" generated="True" extra-ref="SetIconName()"/> | |
101 | ||
102 | <variablelist class="dbus-method" generated="True" extra-ref="SetChassis()"/> | |
103 | ||
104 | <variablelist class="dbus-method" generated="True" extra-ref="SetDeployment()"/> | |
105 | ||
106 | <variablelist class="dbus-method" generated="True" extra-ref="SetLocation()"/> | |
107 | ||
108 | <variablelist class="dbus-method" generated="True" extra-ref="GetProductUUID()"/> | |
109 | ||
110 | <variablelist class="dbus-property" generated="True" extra-ref="Hostname"/> | |
111 | ||
112 | <variablelist class="dbus-property" generated="True" extra-ref="StaticHostname"/> | |
113 | ||
114 | <variablelist class="dbus-property" generated="True" extra-ref="PrettyHostname"/> | |
115 | ||
116 | <variablelist class="dbus-property" generated="True" extra-ref="IconName"/> | |
117 | ||
118 | <variablelist class="dbus-property" generated="True" extra-ref="Chassis"/> | |
119 | ||
120 | <variablelist class="dbus-property" generated="True" extra-ref="Deployment"/> | |
121 | ||
122 | <variablelist class="dbus-property" generated="True" extra-ref="Location"/> | |
123 | ||
124 | <variablelist class="dbus-property" generated="True" extra-ref="KernelName"/> | |
125 | ||
126 | <variablelist class="dbus-property" generated="True" extra-ref="KernelRelease"/> | |
127 | ||
128 | <variablelist class="dbus-property" generated="True" extra-ref="KernelVersion"/> | |
129 | ||
130 | <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemPrettyName"/> | |
131 | ||
132 | <variablelist class="dbus-property" generated="True" extra-ref="OperatingSystemCPEName"/> | |
133 | ||
134 | <variablelist class="dbus-property" generated="True" extra-ref="HomeURL"/> | |
135 | ||
136 | <!--End of Autogenerated section--> | |
137 | ||
8024ac43 | 138 | <para>Whenever the hostname or other metadata is changed via the daemon, |
e09a36bd | 139 | <function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname |
98ab0dae ZJS |
140 | using this interface is authenticated via |
141 | <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para> | |
e09a36bd ZJS |
142 | </refsect1> |
143 | ||
144 | <refsect1> | |
145 | <title>Semantics</title> | |
146 | ||
8024ac43 | 147 | <para>The <emphasis>static (configured) hostname</emphasis> is the one configured in |
e09a36bd ZJS |
148 | <filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the |
149 | current hostname as returned by the | |
4fb222c4 | 150 | <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
8024ac43 ZJS |
151 | system call. If no hostname is configured this property will be the empty string. Setting this property |
152 | to the empty string will remove <filename>/etc/hostname</filename>. This property should be an | |
e09a36bd ZJS |
153 | internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para> |
154 | ||
8024ac43 | 155 | <para>The <emphasis>transient (dynamic) hostname</emphasis> is the one configured via the kernel's |
4fb222c4 | 156 | <citerefentry project="man-pages"><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
8024ac43 | 157 | It can be different from the static hostname if DHCP or mDNS have been configured to change the name |
e09a36bd ZJS |
158 | based on network information. <!-- FIXME: it's not DHCP that configures this... --> |
159 | This property is never empty. If no hostname is set this will default to | |
160 | <literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the | |
8024ac43 ZJS |
161 | empty string will reset the dynamic hostname to the static hostname. If no static hostname is |
162 | configured the dynamic hostname will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This property | |
e09a36bd ZJS |
163 | should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para> |
164 | ||
8024ac43 | 165 | <para>The <emphasis>pretty hostname</emphasis> is a free-form UTF-8 hostname for presentation to the |
e09a36bd ZJS |
166 | user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. |
167 | I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be | |
8024ac43 | 168 | <literal>lennarts-computer</literal>. If no pretty hostname is set this setting will be the empty |
e09a36bd ZJS |
169 | string. Applications should then find a suitable fallback, such as the dynamic hostname.</para> |
170 | ||
171 | <para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set, | |
172 | information such as the chassis type (see below) is used to find a suitable fallback icon name | |
173 | (i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the | |
8024ac43 | 174 | chassis information). If no such data is available, the empty string is returned. In that case an application |
e09a36bd | 175 | should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set |
8024ac43 | 176 | to the empty string, the automatic fallback name selection is enabled again.</para> |
e09a36bd | 177 | |
8024ac43 | 178 | <para>The <emphasis>chassis type</emphasis> should be one of the currently defined chassis types: |
e09a36bd ZJS |
179 | <literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>, |
180 | <literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types | |
181 | <literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases | |
182 | the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to | |
8024ac43 ZJS |
183 | this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if |
184 | it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of | |
e09a36bd ZJS |
185 | the chassis type from firmware information.</para> |
186 | ||
e09a36bd ZJS |
187 | <para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a |
188 | short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent | |
189 | out for changes made directly on the files (as in: administrator edits the files with vi). This is | |
8024ac43 | 190 | the intended behavior: manual configuration changes should require manual reloading.</para> |
e09a36bd | 191 | |
8024ac43 ZJS |
192 | <para>The transient (dynamic) hostname maps directly to the kernel hostname. This hostname should be |
193 | assumed to be highly dynamic, and hence should be watched directly, without depending on | |
194 | <function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. To accomplish | |
195 | this, open <filename>/proc/sys/kernel/hostname</filename> and | |
4fb222c4 | 196 | <citerefentry project="man-pages"><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
e09a36bd ZJS |
197 | for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again: |
198 | this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) | |
199 | hostname.</para> | |
200 | ||
8024ac43 | 201 | <para>Applications may read the hostname data directly if hostname change notifications |
e09a36bd | 202 | are not necessary. Use |
4fb222c4 | 203 | <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
e09a36bd ZJS |
204 | <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and |
205 | <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
206 | for that. For more information on these files and syscalls see the respective man pages.</para> | |
207 | ||
5d2262d7 ZJS |
208 | <refsect2> |
209 | <title>Methods and Properties</title> | |
210 | ||
211 | <para><function>SetHostname()</function> sets the transient (dynamic) hostname which is exposed by the | |
212 | <varname>Hostname</varname> property. If empty, the transient hostname is set to the static hostname. | |
213 | </para> | |
214 | ||
215 | <para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the | |
216 | <varname>StaticHostname</varname> property. If empty, the built-in default of | |
217 | <literal>&FALLBACK_HOSTNAME;</literal> is used.</para> | |
218 | ||
219 | <para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the | |
220 | <varname>PrettyHostname</varname> property.</para> | |
221 | ||
222 | <para><function>SetIconName()</function>, <function>SetChassis()</function>, | |
223 | <function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties | |
224 | <varname>IconName</varname> (the name of the icon representing for the machine), | |
225 | <varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system | |
226 | deployment environment), and <varname>Location</varname> (physical system location), respectively. | |
227 | </para> | |
228 | ||
229 | <para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>, | |
230 | <varname>Deployment</varname>, and <varname>Location</varname> are stored in | |
231 | <filename>/etc/machine-info</filename>. See | |
232 | <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
233 | the semantics of those settings.</para> | |
234 | ||
235 | <para><function>GetProductUUID()</function> returns the "product uuid" as exposed by the kernel based | |
236 | on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly | |
98ab0dae | 237 | requires root privileges, and this method allows access to unprivileged clients through the polkit |
5d2262d7 ZJS |
238 | framework.</para> |
239 | ||
240 | <para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and | |
241 | <varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release | |
f4e1a425 | 242 | (e.g. <literal>5.0.0-11</literal>), and version (i.e. the build number, e.g. <literal>#11</literal>) as |
5d2262d7 ZJS |
243 | reported by |
244 | <citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
245 | <varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and | |
246 | <varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and | |
247 | <varname>HOME_URL=</varname> fields from | |
248 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The | |
249 | purpose of those properties is to allow remote clients to access this information over D-Bus. Local | |
250 | clients can access the information directly.</para> | |
251 | </refsect2> | |
252 | ||
debf2ddd ZJS |
253 | <refsect2> |
254 | <title>Security</title> | |
255 | ||
98ab0dae | 256 | <para>The <varname>interactive</varname> boolean parameters can be used to control whether polkit |
debf2ddd ZJS |
257 | should interactively ask the user for authentication credentials if required.</para> |
258 | ||
98ab0dae | 259 | <para>The polkit action for <function>SetHostname()</function> is |
debf2ddd ZJS |
260 | <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For |
261 | <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is | |
262 | <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For | |
263 | <function>SetIconName()</function> and <function>SetChassis()</function> it is | |
264 | <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para> | |
265 | </refsect2> | |
266 | </refsect1> | |
e09a36bd | 267 | |
debf2ddd ZJS |
268 | <refsect1> |
269 | <title>Recommendations</title> | |
e09a36bd | 270 | |
debf2ddd | 271 | <para>Here are three examples that show how the pretty hostname and the icon name should be used: |
e09a36bd | 272 | <itemizedlist> |
debf2ddd ZJS |
273 | <listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass |
274 | the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon | |
275 | on each service. This is especially useful for WebDAV applications or UPnP media sharing. | |
8024ac43 | 276 | </para></listitem> |
e09a36bd | 277 | |
8024ac43 | 278 | <listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem> |
e09a36bd | 279 | |
debf2ddd ZJS |
280 | <listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname |
281 | if set, and the icon with the icon name, if it is set.</para></listitem> | |
e09a36bd ZJS |
282 | </itemizedlist></para> |
283 | ||
284 | <para>To properly handle name lookups with changing local hostnames without having to edit | |
debf2ddd ZJS |
285 | <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination |
286 | with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
e09a36bd ZJS |
287 | </para> |
288 | ||
debf2ddd ZJS |
289 | <para>A client that wants to change the local hostname for DHCP/mDNS should invoke |
290 | <code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via | |
291 | <code>SetHostname("")</code>.</para> | |
292 | ||
e09a36bd ZJS |
293 | <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty |
294 | name: | |
295 | <itemizedlist> | |
296 | <listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, | |
8024ac43 | 297 | or replace them with <literal>-</literal>.</para></listitem> |
e09a36bd | 298 | |
8024ac43 | 299 | <listitem><para>It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way |
e09a36bd ZJS |
300 | these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>. |
301 | Strip other chars, or try to replace them in some smart way with chars from this set, for example | |
8024ac43 ZJS |
302 | <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as the replacement for all |
303 | punctuation characters and whitespace.</para></listitem> | |
e09a36bd ZJS |
304 | |
305 | <listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as | |
306 | the first or last char.</para></listitem> | |
307 | ||
308 | <listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem> | |
309 | ||
310 | <listitem><para>If after stripping special chars the empty string is the result, you can pass this | |
8024ac43 ZJS |
311 | as-is to <filename>systemd-hostnamed</filename> in which case it will automatically use |
312 | <literal>&FALLBACK_HOSTNAME;</literal>.</para></listitem> | |
e09a36bd | 313 | |
8024ac43 ZJS |
314 | <listitem><para>Uppercase charaacters should be replaced with their lowercase equivalents. |
315 | </para></listitem> | |
e09a36bd ZJS |
316 | </itemizedlist></para> |
317 | ||
318 | <para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass | |
319 | they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename> | |
8024ac43 | 320 | will also accept <literal>_</literal> in the hostname, but we recommend not using this to avoid clashes |
e09a36bd | 321 | with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but |
8024ac43 | 322 | because of the DNS label limitations, we recommend not making use of this.</para> |
e09a36bd ZJS |
323 | |
324 | <para>Here are a couple of example conversions: | |
325 | <itemizedlist> | |
326 | <listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem> | |
327 | <listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem> | |
328 | <listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem> | |
329 | <listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem> | |
330 | <listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem> | |
331 | <listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem> | |
332 | <listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem> | |
333 | </itemizedlist></para> | |
334 | ||
8024ac43 | 335 | <para>Of course, an already valid internet hostname label you enter and pass through this |
debf2ddd | 336 | conversion should stay unmodified, so that users have direct control of it, if they want — by simply |
e09a36bd ZJS |
337 | ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet |
338 | name.</para> | |
339 | </refsect1> | |
340 | ||
341 | <refsect1> | |
342 | <title>Versioning</title> | |
343 | ||
344 | <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> | |
345 | the usual interface versioning guidelines</ulink>.</para> | |
346 | </refsect1> | |
347 | ||
48f99d7c ZJS |
348 | <refsect1> |
349 | <title>Examples</title> | |
350 | ||
351 | <example> | |
352 | <title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title> | |
353 | ||
354 | <programlisting>$ gdbus introspect --system \ | |
355 | --dest org.freedesktop.hostname1 \ | |
356 | --object-path /org/freedesktop/hostname1 | |
357 | </programlisting> | |
358 | </example> | |
359 | </refsect1> | |
360 | ||
e09a36bd ZJS |
361 | <refsect1> |
362 | <title>See also</title> | |
363 | ||
364 | <para>David Zeuthen's original Fedora | |
365 | <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para> | |
366 | </refsect1> | |
367 | </refentry> |