diff options
-rw-r--r-- | man/custom-entities.ent.in | 1 | ||||
-rw-r--r-- | man/org.freedesktop.hostname1.xml | 236 | ||||
-rw-r--r-- | man/rules/meson.build | 1 | ||||
-rw-r--r-- | man/systemd-hostnamed.service.xml | 34 |
4 files changed, 263 insertions, 9 deletions
diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in index 84a29f5de4..03fe05f1bc 100644 --- a/man/custom-entities.ent.in +++ b/man/custom-entities.ent.in @@ -6,6 +6,7 @@ <!ENTITY systemenvgeneratordir @SYSTEM_ENV_GENERATOR_DIR@> <!ENTITY userenvgeneratordir @USER_ENV_GENERATOR_DIR@> <!ENTITY CERTIFICATE_ROOT @CERTIFICATE_ROOT@> +<!ENTITY FALLBACK_HOSTNAME @FALLBACK_HOSTNAME@> <!ENTITY MEMORY_ACCOUNTING_DEFAULT @MEMORY_ACCOUNTING_DEFAULT_YES_NO@> <!ENTITY KILL_USER_PROCESSES @KILL_USER_PROCESSES_YES_NO@> <!ENTITY DEBUGTTY @DEBUGTTY@> diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml new file mode 100644 index 0000000000..a381cb8239 --- /dev/null +++ b/man/org.freedesktop.hostname1.xml @@ -0,0 +1,236 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="org.freedesktop.hostname1" conditional='ENABLE_HOSTNAMED' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>org.freedesktop.hostname1</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>org.freedesktop.hostname1</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>org.freedesktop.hostname1</refname> + <refpurpose>The D-Bus interface of systemd-hostnamed</refpurpose> + </refnamediv> + + <refsect1> + <title>Introduction</title> + + <para> + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is a system service that can be used to control the host name and related machine meta data from user + programs. This page describes the hostname semantics and the D-Bus interface.</para> + </refsect1> + + <refsect1> + <title>The D-Bus API</title> + + <para>The service exposes the following interfaces on the bus:</para> + + <programlisting> +$ gdbus introspect --system \ + --dest org.freedesktop.hostname1 \ + --object-path /org/freedesktop/hostname1 + +node /org/freedesktop/hostname1 { + interface org.freedesktop.hostname1 { + methods: + SetHostname(in s name, + in b user_interaction); + SetStaticHostname(in s name, + in b user_interaction); + SetPrettyHostname(in s name, + in b user_interaction); + SetIconName(in s name, + in b user_interaction); + SetChassis(in s name, + in b user_interaction); + signals: + properties: + readonly s Hostname = 'dhcp-192-168-47-11'; + readonly s StaticHostname = 'lennarts-computer'; + readonly s PrettyHostname = 'Lennart’s Computer'; + readonly s IconName = 'computer-laptop'; + readonly s Chassis = 'laptop'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; + </programlisting> + + <para>Whenever the hostname or other meta data is changed via the daemon, + <function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname + using this interface is authenticated via PolicyKit.</para> + </refsect1> + + <refsect1> + <title>Semantics</title> + + <para>The <emphasis>static (configured) host name</emphasis> is the one configured in + <filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the + current hostname as returned by the + <citerefentry project='man-pages'><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry> + system call. If no host name is configured this property will be the empty string. Setting this property + to the empty string will remove <filename>/etc/hostname</filename>. This hostname should be an + internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para> + + <para>The <emphasis>transient (dynamic) host name</emphasis> is the one configured via the kernel's + <citerefentry project='man-pages'><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + It can be different from the static hostname in case DHCP or mDNS have been configured to change the name + based on network information. <!-- FIXME: it's not DHCP that configures this... --> + This property is never empty. If no hostname is set this will default to + <literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the + empty string will reset the dynamic hostname to the static host name. If no static host name is + configured the dynamic host name will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This hostname + should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para> + + <para>The <emphasis>pretty host name</emphasis> is a free-form UTF-8 host name for presentation to the + user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. + I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be + <literal>lennarts-computer</literal>. If no pretty host name is set this setting will be the empty + string. Applications should then find a suitable fallback, such as the dynamic hostname.</para> + + <para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set, + information such as the chassis type (see below) is used to find a suitable fallback icon name + (i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the + chassis information). If no such data is available, returns the empty string. In that case an application + should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set + to the empty string, this automatic fallback name selection is enabled again.</para> + + <para>The <emphasis>chassis type</emphasis> should be one of the following that are currently defined: + <literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>, + <literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types + <literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases + the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to + this setting is hence useful only to override misdetected chassis types, or configure a chassis type if + none could be auto-detected. Set this property to the empty string to reenable the automatic detection of + the chassis type from firmware information.</para> + + <para>A client which wants to change the local host name for DHCP/mDNS should invoke + <code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via + <code>SetHostname("")</code>.</para> + + <para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a + short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent + out for changes made directly on the files (as in: administrator edits the files with vi). This is + actually intended behavior: manual configuration changes should require manual reloading of them.</para> + + <para>The transient (dynamic) hostname directly maps to the kernel hostname. This hostname should be + assumed to be highly dynamic, and hence should be watched directly, without involving + <function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. For that, open + <filename>/proc/sys/kernel/hostname</filename> and + <citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again: + this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) + hostname.</para> + + <para>Applications may bypass the daemon to read the hostname data if notifications of host name changes + are not necessary. Use + <citerefentry project='man-pages'><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for that. For more information on these files and syscalls see the respective man pages.</para> + + <para>The user_interaction boolean parameters can be used to control whether PolicyKit should + interactively ask the user for authentication credentials if it needs to.</para> + + <para>The PolicyKit action for <function>SetHostname()</function> is + <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For + <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is + <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For + <function>SetIconName()</function> and <function>SetChassis()</function> it is + <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para> + + <para>Here are three examples how the pretty hostname and the icon name should be used: + <itemizedlist> + <listitem><para>When registering DNS-SD services: use the pretty host name in the service name, and + pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server + icon on each service. Especially useful for WebDAV stuff. Similar for UPnP media + sharing.</para></listitem> + + <listitem><para>Set the bluetooth name to the pretty host name.</para></listitem> + + <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> + </itemizedlist></para> + + <para>To properly handle name lookups with changing local hostnames without having to edit + <filename>/etc/hosts</filename> for them, we recommend using <filename>systemd-hostnamed</filename> in + combination with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty + name: + <itemizedlist> + <listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, + or replace them by <literal>-</literal>.</para></listitem> + + <listitem><para>It's probably safer not to use any non-ASCII chars, even if DNS allows this in some way + these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>. + Strip other chars, or try to replace them in some smart way with chars from this set, for example + <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as replacement for all kinds + of punctuation chars or spaces.</para></listitem> + + <listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as + the first or last char.</para></listitem> + + <listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem> + + <listitem><para>If after stripping special chars the empty string is the result, you can pass this + as-is to <filename>systemd-hostnamed</filename> in which case it will automatically make + <literal>&FALLBACK_HOSTNAME;</literal> out of this.</para></listitem> + + <listitem><para>It probably is a good idea to replace uppercase by lowercase chars.</para></listitem> + </itemizedlist></para> + + <para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass + they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename> + will also accept <literal>_</literal> in the hostname, but I'd recommend not using this to avoid clashes + with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but + because of the DNS label limitations, I'd recommend not making use of this.</para> + + <para>Here are a couple of example conversions: + <itemizedlist> + <listitem><para><literal>Lennart's PC</literal> → <literal>lennarts-pc</literal></para></listitem> + <listitem><para><literal>Müllers Computer</literal> → <literal>muellers-computer</literal></para></listitem> + <listitem><para><literal>Voran!</literal> → <literal>voran</literal></para></listitem> + <listitem><para><literal>Es war einmal ein Männlein</literal> → <literal>es-war-einmal-ein-maennlein</literal></para></listitem> + <listitem><para><literal>Jawoll. Ist doch wahr!</literal> → <literal>jawoll-ist-doch-wahr</literal></para></listitem> + <listitem><para><literal>レナート</literal> → <literal>localhost</literal></para></listitem> + <listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem> + </itemizedlist></para> + + <para>Oh, and of course, an already valid internet hostname label you enter and pass through this + conversion should stay unmodified, so that users have direct control of it, if they want -- by simply + ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet + name.</para> + </refsect1> + + <refsect1> + <title>Versioning</title> + + <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> + the usual interface versioning guidelines</ulink>.</para> + </refsect1> + + <refsect1> + <title>See also</title> + + <para>David Zeuthen's original Fedora + <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para> + </refsect1> +</refentry> diff --git a/man/rules/meson.build b/man/rules/meson.build index 6beed3f6dd..d69286301b 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -44,6 +44,7 @@ manpages = [ ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], + ['org.freedesktop.hostname1', '5', [], 'ENABLE_HOSTNAMED'], ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml index 19bd4c06f2..185e038809 100644 --- a/man/systemd-hostnamed.service.xml +++ b/man/systemd-hostnamed.service.xml @@ -18,7 +18,7 @@ <refnamediv> <refname>systemd-hostnamed.service</refname> <refname>systemd-hostnamed</refname> - <refpurpose>Host name bus mechanism</refpurpose> + <refpurpose>Daemon to control system hostname from programs</refpurpose> </refnamediv> <refsynopsisdiv> @@ -29,19 +29,35 @@ <refsect1> <title>Description</title> - <para><filename>systemd-hostnamed</filename> is a system service - that may be used as a mechanism to change the system's hostname. - <filename>systemd-hostnamed</filename> is automatically activated - on request and terminates itself when it is unused.</para> + <para><filename>systemd-hostnamed.service</filename> is a system service that may be used to change the + system's hostname and related machine meta data from user programs. It is automatically activated on + request and terminates itself when unused.</para> + + <para>It currently offers access to five variables: + <itemizedlist> + <listitem><para>The current host name (Example: <literal>dhcp-192-168-47-11</literal>)</para> + </listitem> + + <listitem><para>The static (configured) host name (Example: + <literal>lennarts-computer</literal>)</para></listitem> + + <listitem><para>The pretty host name (Example: <literal>Lennart's Computer</literal>)</para> + </listitem> + + <listitem><para>A suitable icon name for the local host (Example: + <literal>computer-laptop</literal>)</para></listitem> + + <listitem><para>A chassis type (Example: <literal>tablet</literal>)</para> + </listitem> + </itemizedlist></para> <para>The tool <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> is a command line client to this service.</para> - <para>See the <ulink - url="https://www.freedesktop.org/wiki/Software/systemd/hostnamed"> - developer documentation</ulink> for information about the APIs - <filename>systemd-hostnamed</filename> provides.</para> + <para>See the + <citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for a description of the D-Bus API.</para> </refsect1> <refsect1> |