]>
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> | |
32 | is a system service that can be used to control the host name and related machine meta data from user | |
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 | ||
41 | <programlisting> | |
42 | $ gdbus introspect --system \ | |
43 | --dest org.freedesktop.hostname1 \ | |
44 | --object-path /org/freedesktop/hostname1 | |
45 | ||
46 | node /org/freedesktop/hostname1 { | |
47 | interface org.freedesktop.hostname1 { | |
48 | methods: | |
49 | SetHostname(in s name, | |
50 | in b user_interaction); | |
51 | SetStaticHostname(in s name, | |
52 | in b user_interaction); | |
53 | SetPrettyHostname(in s name, | |
54 | in b user_interaction); | |
55 | SetIconName(in s name, | |
56 | in b user_interaction); | |
57 | SetChassis(in s name, | |
58 | in b user_interaction); | |
59 | signals: | |
60 | properties: | |
61 | readonly s Hostname = 'dhcp-192-168-47-11'; | |
62 | readonly s StaticHostname = 'lennarts-computer'; | |
63 | readonly s PrettyHostname = 'Lennart’s Computer'; | |
64 | readonly s IconName = 'computer-laptop'; | |
65 | readonly s Chassis = 'laptop'; | |
66 | }; | |
67 | interface org.freedesktop.DBus.Properties { | |
68 | }; | |
69 | interface org.freedesktop.DBus.Introspectable { | |
70 | }; | |
71 | interface org.freedesktop.DBus.Peer { | |
72 | }; | |
73 | }; | |
74 | </programlisting> | |
75 | ||
76 | <para>Whenever the hostname or other meta data is changed via the daemon, | |
77 | <function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname | |
78 | using this interface is authenticated via PolicyKit.</para> | |
79 | </refsect1> | |
80 | ||
81 | <refsect1> | |
82 | <title>Semantics</title> | |
83 | ||
84 | <para>The <emphasis>static (configured) host name</emphasis> is the one configured in | |
85 | <filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the | |
86 | current hostname as returned by the | |
87 | <citerefentry project='man-pages'><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
88 | system call. If no host name is configured this property will be the empty string. Setting this property | |
89 | to the empty string will remove <filename>/etc/hostname</filename>. This hostname should be an | |
90 | internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para> | |
91 | ||
92 | <para>The <emphasis>transient (dynamic) host name</emphasis> is the one configured via the kernel's | |
93 | <citerefentry project='man-pages'><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
94 | It can be different from the static hostname in case DHCP or mDNS have been configured to change the name | |
95 | based on network information. <!-- FIXME: it's not DHCP that configures this... --> | |
96 | This property is never empty. If no hostname is set this will default to | |
97 | <literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the | |
98 | empty string will reset the dynamic hostname to the static host name. If no static host name is | |
99 | configured the dynamic host name will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This hostname | |
100 | should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para> | |
101 | ||
102 | <para>The <emphasis>pretty host name</emphasis> is a free-form UTF-8 host name for presentation to the | |
103 | user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. | |
104 | I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be | |
105 | <literal>lennarts-computer</literal>. If no pretty host name is set this setting will be the empty | |
106 | string. Applications should then find a suitable fallback, such as the dynamic hostname.</para> | |
107 | ||
108 | <para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set, | |
109 | information such as the chassis type (see below) is used to find a suitable fallback icon name | |
110 | (i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the | |
111 | chassis information). If no such data is available, returns the empty string. In that case an application | |
112 | should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set | |
113 | to the empty string, this automatic fallback name selection is enabled again.</para> | |
114 | ||
115 | <para>The <emphasis>chassis type</emphasis> should be one of the following that are currently defined: | |
116 | <literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>, | |
117 | <literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types | |
118 | <literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases | |
119 | the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to | |
120 | this setting is hence useful only to override misdetected chassis types, or configure a chassis type if | |
121 | none could be auto-detected. Set this property to the empty string to reenable the automatic detection of | |
122 | the chassis type from firmware information.</para> | |
123 | ||
124 | <para>A client which wants to change the local host name for DHCP/mDNS should invoke | |
125 | <code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via | |
126 | <code>SetHostname("")</code>.</para> | |
127 | ||
128 | <para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a | |
129 | short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent | |
130 | out for changes made directly on the files (as in: administrator edits the files with vi). This is | |
131 | actually intended behavior: manual configuration changes should require manual reloading of them.</para> | |
132 | ||
133 | <para>The transient (dynamic) hostname directly maps to the kernel hostname. This hostname should be | |
134 | assumed to be highly dynamic, and hence should be watched directly, without involving | |
135 | <function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. For that, open | |
136 | <filename>/proc/sys/kernel/hostname</filename> and | |
137 | <citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
138 | for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again: | |
139 | this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) | |
140 | hostname.</para> | |
141 | ||
142 | <para>Applications may bypass the daemon to read the hostname data if notifications of host name changes | |
143 | are not necessary. Use | |
144 | <citerefentry project='man-pages'><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
145 | <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and | |
146 | <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
147 | for that. For more information on these files and syscalls see the respective man pages.</para> | |
148 | ||
149 | <para>The user_interaction boolean parameters can be used to control whether PolicyKit should | |
150 | interactively ask the user for authentication credentials if it needs to.</para> | |
151 | ||
152 | <para>The PolicyKit action for <function>SetHostname()</function> is | |
153 | <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For | |
154 | <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is | |
155 | <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For | |
156 | <function>SetIconName()</function> and <function>SetChassis()</function> it is | |
157 | <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para> | |
158 | ||
159 | <para>Here are three examples how the pretty hostname and the icon name should be used: | |
160 | <itemizedlist> | |
161 | <listitem><para>When registering DNS-SD services: use the pretty host name in the service name, and | |
162 | pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server | |
163 | icon on each service. Especially useful for WebDAV stuff. Similar for UPnP media | |
164 | sharing.</para></listitem> | |
165 | ||
166 | <listitem><para>Set the bluetooth name to the pretty host name.</para></listitem> | |
167 | ||
168 | <listitem><para>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.</para></listitem> | |
169 | </itemizedlist></para> | |
170 | ||
171 | <para>To properly handle name lookups with changing local hostnames without having to edit | |
172 | <filename>/etc/hosts</filename> for them, we recommend using <filename>systemd-hostnamed</filename> in | |
173 | combination with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
174 | </para> | |
175 | ||
176 | <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty | |
177 | name: | |
178 | <itemizedlist> | |
179 | <listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, | |
180 | or replace them by <literal>-</literal>.</para></listitem> | |
181 | ||
182 | <listitem><para>It's probably safer not to use any non-ASCII chars, even if DNS allows this in some way | |
183 | these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>. | |
184 | Strip other chars, or try to replace them in some smart way with chars from this set, for example | |
185 | <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as replacement for all kinds | |
186 | of punctuation chars or spaces.</para></listitem> | |
187 | ||
188 | <listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as | |
189 | the first or last char.</para></listitem> | |
190 | ||
191 | <listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem> | |
192 | ||
193 | <listitem><para>If after stripping special chars the empty string is the result, you can pass this | |
194 | as-is to <filename>systemd-hostnamed</filename> in which case it will automatically make | |
195 | <literal>&FALLBACK_HOSTNAME;</literal> out of this.</para></listitem> | |
196 | ||
197 | <listitem><para>It probably is a good idea to replace uppercase by lowercase chars.</para></listitem> | |
198 | </itemizedlist></para> | |
199 | ||
200 | <para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass | |
201 | they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename> | |
202 | will also accept <literal>_</literal> in the hostname, but I'd recommend not using this to avoid clashes | |
203 | with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but | |
204 | because of the DNS label limitations, I'd recommend not making use of this.</para> | |
205 | ||
206 | <para>Here are a couple of example conversions: | |
207 | <itemizedlist> | |
208 | <listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem> | |
209 | <listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem> | |
210 | <listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem> | |
211 | <listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem> | |
212 | <listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem> | |
213 | <listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem> | |
214 | <listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem> | |
215 | </itemizedlist></para> | |
216 | ||
217 | <para>Oh, and of course, an already valid internet hostname label you enter and pass through this | |
218 | conversion should stay unmodified, so that users have direct control of it, if they want -- by simply | |
219 | ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet | |
220 | name.</para> | |
221 | </refsect1> | |
222 | ||
223 | <refsect1> | |
224 | <title>Versioning</title> | |
225 | ||
226 | <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> | |
227 | the usual interface versioning guidelines</ulink>.</para> | |
228 | </refsect1> | |
229 | ||
230 | <refsect1> | |
231 | <title>See also</title> | |
232 | ||
233 | <para>David Zeuthen's original Fedora | |
234 | <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para> | |
235 | </refsect1> | |
236 | </refentry> |