path: root/docs/xdg-hostname-docs.xml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
  <bookinfo>
    <title>xdg-hostname Reference Manual</title>
    <releaseinfo>Version &version;</releaseinfo>
    <authorgroup>
      <author>
        <firstname>David</firstname>
        <surname>Zeuthen</surname>
        <affiliation>
          <address>
            <email>davidz@redhat.com</email>
          </address>
        </affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2008</year>
      <holder>The xdg-hostname Authors</holder>
    </copyright>

    <legalnotice>
      <para>
        Permission is granted to copy, distribute and/or modify this
        document under the terms of the <citetitle>GNU Free
        Documentation License</citetitle>, Version 1.1 or any later
        version published by the Free Software Foundation with no
        Invariant Sections, no Front-Cover Texts, and no Back-Cover
        Texts. You may obtain a copy of the <citetitle>GNU Free
        Documentation License</citetitle> from the Free Software
        Foundation by visiting <ulink type="http"
        url="http://www.fsf.org">their Web site</ulink> or by writing
        to:

        <address>
          The Free Software Foundation, Inc.,
          <street>59 Temple Place</street> - Suite 330,
          <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
          <country>USA</country>
        </address>
      </para>

      <para>
        Many of the names used by companies to distinguish their
        products and services are claimed as trademarks. Where those
        names appear in any freedesktop.org documentation, and those trademarks
        are made aware to the members of the freedesktop.org
        Project, the names have been printed in caps or initial caps.
      </para>
    </legalnotice>
  </bookinfo>

  <reference id="overview">
    <title>Overview</title>
    <chapter id="overview-introduction">
      <title>Introduction</title>
      <para>
        The <literal>xdg-hostname</literal> project provides a
        mechanism to get, set and monitor changes for hostname
        data. Hostname data is defined to include more than just the
        regular hostname, it also includes a display hostname, an icon
        and possibly more items in the future. Hostname data is
        usually a user preference and is stored in a persistent local
        database.
      </para>
      <para>
        In addition, the <literal>xdg-hostname</literal> project
        provides a facility for network configuration software to
        inject transient hostname data that, according to user
        preference, can take precedence over local configuration data.
        For example, when a system obtains network configuration
        data via
        <ulink url="http://en.wikipedia.org/wiki/Dhcp">DHCP</ulink>,
        auxiliary data as defined by
        <ulink url="http://tools.ietf.org/rfc/rfc2132.txt">RFC 2132</ulink>
        may specify what hostname to use.
      </para>
      <para>
        The main audience for the <literal>xdg-hostname</literal>
        project include
        <itemizedlist>
          <listitem>
            <para>
              Desktop environments - for displaying and allowing
              the user to configure hostname data.
            </para>
          </listitem>
          <listitem>
            <para>
              Applications exporting named services on the
              network. Such applications can consume hostname
              data to provide a more useful name for the service
              they export.
            </para>
          </listitem>
        </itemizedlist>
        The main benefit from using hostname data provided by the
        <literal>xdg-hostname</literal> project is the display
        hostname. Compared to the traditional hostname (which
        normally conforms to section 3.5 of
        <ulink url="http://www.ietf.org/rfc/rfc1034.txt">RFC 1034</ulink>
        with the hostname being a label: 7 bit ASCII without special characters,
        whitespace or dots) the display hostname is UTF-8.
      </para>
      <para>
        Applications can use the display hostname announcing
        services via e.g.
        <ulink url="http://en.wikipedia.org/wiki/DNS-SD">DNS-SD</ulink>.
        For example, a file sharing application may use set the service name to
        "David's files on Kitchen Computer" (or in Chinese "David' 在厨
        房计算机上的s文件") instead of the uglier
        and less meaningful name  "David's files on localhost".
      </para>
      <para>
        In addition, this service introduces the concept of
        associating an icon with a system. This is useful for
        applications announcing services on the network. For example,
        for DNS-SD, a TXT record may be set to the icon name. Icon
        names are designed to conform to the freedesktop.org
        <ulink url="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon Theme Specification</ulink>
        and
        <ulink url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon Naming Specification</ulink>
        specifications.
      </para>
      <para>
        It is important to understand that the display hostname and
        hostname are different on a conceptual level; many of the
        the observations in section 4.4 of the
        <ulink url="http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt">DNS-SD
        Draft</ulink> applies here. Specifically, the display hostname is,
        among other things, intended to be used for naming services
        (e.g. "Recipes on Kitchen Computer") announced via e.g. DNS-SD
        and the hostname (e.g. "t41-davidz") is for identifying the
        system on which software providing the service runs. One way
        to think about this is that the display hostname represents what
        the system <emphasis>does</emphasis> while the hostname
        represents what the system <emphasis>is</emphasis>.
      </para>
      <para>
        For example, if the system with the hostname "t41-davidz" is
        replaced by a another system with the hostname "x61-davidz" it
        is useful to keep the display hostname the same ("Kitchen
        Computer") such that users on the network consuming services
        ("Recipes on Kitchen Computer") won't need to be reconfigured.
      </para>
      <para>
        The display hostname is what should be presented in the user
        interface; users (who are not administrators) should never ever
        need to see the hostname.
      </para>
    </chapter>

    <chapter id="overview-reading">
      <title>Reading hostname data</title>
      <para>
        Hostname data exported by the <literal>xdg-hostname</literal>
        project is available via a D-Bus service on the system message
        bus. To access the D-Bus service, use the well-known
        name <literal>org.freedesktop.Hostname1</literal> on the D-Bus
        system message bus and connect to the
        interface
        <xref linkend="Hostname1"/>
        for the
        object at the
        path <literal>/org/freedesktop/hostname1</literal>.
      </para>
      <para>
        For reading hostname data, simply read the D-Bus properties, e.g.
        <link linkend="Hostname1:display-hostname">display-hostname</link>,
        <link linkend="Hostname1:hostname">hostname</link> and
        <link linkend="Hostname1:icon-name">icon-name</link>. To listen for changes,
        connect to the
        <link linkend="Hostname1::Changed">Changed()</link> signal.
      </para>
      <para>
        The value of these properties are usually computed using the following algorithm:
        <itemizedlist>
          <listitem>
            <para>
              For
              <link linkend="Hostname1:hostname">hostname</link>,
              if
              <link linkend="Hostname1:use-transient-data">use-transient-data</link>
              data is <literal>TRUE</literal> and a live transient data provider
              is registered (see <xref linkend="overview-providing-transient-data"/>), then
              <link linkend="Hostname1:transient-hostname">transient-hostname</link> is returned
              if the property is not the empty string.
              Otherwise
              <link linkend="Hostname1:configured-hostname">configured-hostname</link>
              is returned.
            </para>
          </listitem>
        </itemizedlist>
        Likewise for the
        <link linkend="Hostname1:display-hostname">display-hostname</link> and
        <link linkend="Hostname1:icon-name">icon-name</link> properties.
      </para>
      <para>
        Applications MUST NOT assume this algorithm is used. An
        implementation of the <literal>org.freedesktop.Hostname1</literal>
        D-Bus service MAY use another algorithm to return hostname
        data (for example, an implementation may read the hostname
        data from e.g. a
        <ulink url="http://en.wikipedia.org/wiki/LDAP">LDAP</ulink>,
        another implementation may read it from
        <ulink url="http://en.wikipedia.org/wiki/Vital_Product_Data">Vital Product Data</ulink>
        etc.)
      </para>
    </chapter>

    <chapter id="overview-configuring">
      <title>Configuring hostname data</title>
      <para>
        System configuration tools should use the methods
        <link linkend="Hostname1.SetDisplayHostname">SetDisplayHostname()</link>,
        <link linkend="Hostname1.SetHostname">SetHostname()</link>,
        <link linkend="Hostname1.SetIconName">SetIconName()</link> and
        <link linkend="Hostname1.SetUseTransientData">SetUseTransientData()</link>,
        method to set data.
      </para>
      <para>
        Graphical user interfaces would also use the
        <link linkend="Hostname1:configured-display-hostname">configured-display-hostname</link>,
        <link linkend="Hostname1:configured-hostname">configured-hostname</link>,
        <link linkend="Hostname1:configured-icon-name">configured-icon-name</link> and
        <link linkend="Hostname1:use-transient-data">use-transient-data</link>
        properties to initialize the user interface with currently configured values.
        The
        <link linkend="Hostname1:can-set-data">can-set-data</link>
        property can be used to determine if the user interface is sensitive e.g
        whether data can be changed.
      </para>
      <para>
        As an example, one user interface could look like this
        <informalexample>
          <programlisting>
  +---------+
  |  Icon   | Computer Name:   [David's Kitchen Computer___________]
  | Chooser |
  +---------+
                To access this computer from the network use the name
                davids-kitchen-computer.local

  [>] Advanced

  [Revert]                                          [Cancel] [Apply]
          </programlisting>
        </informalexample>
        where the hostname is automatically computed from the display
        hostname. If the user wants to explicitly set the hostname
        he can expand the dialog:
        <informalexample>
          <programlisting>
  +---------+
  |  Icon   | Computer Name:   [David's Kitchen Computer___________]
  | Chooser |
  +---------+
                To access this computer from the network use the name
                x61-davidz.local

  [V] Advanced

     Hostname:      [x61-davidz_________________________]

     [ ] Always change hostname if provided by network connections

  [Revert]                                          [Cancel] [Apply]
          </programlisting>
        </informalexample>
        In addition, the "Always change hostname if provided by
        network connections" element represents the
        <link linkend="Hostname1:use-transient-data">use-transient-data</link>
        property.
      </para>
    </chapter>

    <chapter id="overview-providing-transient-data">
      <title>Providing transient data</title>
      <para>
        Networking configuration tools should use the
        <link linkend="Hostname1.RegisterTransientDataProvider">RegisterTransientDataProvider()</link>
        method when connecting to a network where a hostname is provided as part of the
        connection setup.
      </para>
      <para>
        Using the obtained cookie, the network configuration tool
        can invoke methods such as
        <link linkend="Hostname1.SetTransientHostname">SetTransientHostname()</link>
        to e.g. set the hostname.
        If hostname data changes over time (for example, when renewing a DHCP lease), the
        network configuration tool can simply call
        <link linkend="Hostname1.SetTransientHostname">SetTransientHostname()</link>
        again.
      </para>
      <para>
        When disconnecting from the network, the networking configuration tool must call
        <link linkend="Hostname1.UnregisterTransientDataProvider">UnregisterTransientDataProvider()</link>.
      </para>
      <para>
        A provider of transient hostname data should ALWAYS supply
        data this way even
        if <link linkend="Hostname1:use-transient-data">use-transient-data</link>
        is <literal>FALSE</literal>.
      </para>
    </chapter>

    <chapter id="overview-implementation-details">
      <title>Implementation Details</title>
      <para>
        This section describes implementation details about the software
        shipped as part of the <literal>xdg-hostname</literal> project. Applications
        MUST NOT rely on these implementation details as other software
        may provide <literal>org.freedesktop.Hostname1</literal> D-Bus service.
        This information is provided only to make it easier for vendors
        to integrate the <literal>xdg-hostname</literal> project into
        operating system products.
      </para>
      <para>
        The <literal>org.freedesktop.Hostname1</literal> D-Bus service
        is designed to be implemented by a process launched on demand
        using D-Bus system bus activation. In addition, after 30
        seconds of inactivity (e.g. no method calls or transient data providers), the process
        providing the D-Bus service will automatically exit and
        release resources. The
        <xref linkend="xdg-hostnamed-1.8"/>
        daemon is used to provide
        the <literal>org.freedesktop.Hostname1</literal> D-Bus
        service.
      </para>
      <para>
        For easy access to the <literal>org.freedesktop.Hostname1</literal>
        D-Bus service, the
        <xref linkend="xdg-hostname-1.1"/>
        program is provided.
        In addition to configuring hostname data, this program
        provides direct access to the local configuration database
        without using D-Bus. This is useful in sitations where no
        system bus is available, for example early user space or when
        configuring a system or image in
        a <literal>chroot(1)</literal> environment.
      </para>
      <para>
        If the hostname is manually set (e.g. not using the
        <literal>org.freedesktop.Hostname1</literal> D-Bus service),
        the
        <xref linkend="xdg-hostname-1.1"/>
        program should be used to update the local database of the
        <literal>xdg-hostname</literal> project:
        <informalexample>
<programlisting>
xdg-hostname-1 --set-hostname `/bin/hostname`
</programlisting>
        </informalexample>
      </para>
      <para>
        If even this doesn't happen,
        <xref linkend="xdg-hostnamed-1.8"/>
        will always compare the result
        of <literal>gethostname(2)</literal>
        with what's in the local database before every operation
        (e.g. setting or returning
        <link linkend="Hostname1:hostname">hostname</link> and other
        properties).
        If there's a mismatch it means the hostname was manually changed
        without invoking
        <xref linkend="xdg-hostname-1.1"/>
        as described above.
        As a result,
        <xref linkend="xdg-hostnamed-1.8"/>
        will update the local database to match the current
        hostname as returned by <literal>gethostname(2)</literal>.
        The only change is that change notifications on
        the D-Bus interface are delayed.
      </para>
      <para>
        Changing the hostname on a <literal>UNIX</literal> system
        can a bit more work than just invoking the
        the <literal>sethostname(2)</literal> system call.
        Depending on the operating system, other actions,
        such as updating one or more configuration files, may need to
        happen. To accommodate this, all executable programs in the
        <literal>/etc/xdg-hostname-1/run.d</literal>
        directory with the extension <literal>.run</literal>
        will be invoked (sequentially, in the C locale's alphabetical order)
        by
        <xref linkend="xdg-hostnamed-1.8"/>
        whenever one of the
        <link linkend="Hostname1:display-hostname">display-hostname</link>,
        <link linkend="Hostname1:hostname">hostname</link> and
        <link linkend="Hostname1:icon-name">icon-name</link>
        properties change. Two positional parameters will be supplied,
        the first is the name of the property (e.g: <literal>display-hostname</literal>),
        the second being it's value (e.g.: <literal>Jukebox ♫♫♫</literal>).
        The exit code of the programs are ignored. If a program invoked
        this way hasn't exited within 5 seconds, it will be silently
        killed and an error will be logged. While the <literal>.run</literal>
        programs are being run,
        <xref linkend="xdg-hostnamed-1.8"/>
        will not service requests on the D-Bus interface (requests will be queued
        up for processing when all the <literal>.run</literal> programs have run).
      </para>
      <para>
        A number of applications require that the name returned by
        <literal>gethostname(2)</literal> resolves to the local
        machine (typically 127.0.0.1). This can be achieved via
        either using a <literal>.run</literal> script in <literal>/etc/xdg-hostname-1/run.d</literal> that updates
        the <literal>/etc/hosts</literal> file
        or through a
        <ulink url="http://en.wikipedia.org/wiki/GNU_C_Library">GNU C Library</ulink>
        extension such as
        <ulink url="http://0pointer.de/lennart/projects/nss-myhostname/README.txt">nss-myhostname</ulink>.
      </para>
      <para>
        Typically, when booting a <literal>UNIX</literal> system the
        hostname needs to be set as early as possible. As an implementation
        detail,
        <xref linkend="xdg-hostnamed-1.8"/>
        will always attempt write the current hostname (e.g. the value
        of the
        <link linkend="Hostname1:hostname">hostname</link>
        property) to the <literal>/etc/xdg-hostname-1/hostname</literal>
        file (specifically this file may be a symlink to e.g. the
        <literal>/etc/hostname</literal> file).
        Operating system boot scripts may use the contents of this
        file to set the hostname when booting.
      </para>
    </chapter>

  </reference>

  <reference id="ref-dbus">
    <title>D-Bus API Reference</title>
    <partintro>
      <para>
        This part documents the D-Bus interface used to access the
        <literal>xdg-hostname</literal> project.
      </para>
    </partintro>
    <xi:include href="dbus/org.freedesktop.Hostname1.ref.xml"/>
  </reference>

  <reference id="ref-gobject">
    <title>GObject API Reference</title>
    <partintro>
      <para>
        This part documents a GObject library used to access the
        <literal>xdg-hostname</literal> project.
      </para>
    </partintro>
    <xi:include href="xml/xdg-hostname-monitor.xml"/>
    <xi:include href="xml/xdg-hostname-error.xml"/>
  </reference>

  <reference id="ref-tools">
    <title>Tools</title>
    <partintro>
      <para>
        This part presents the tools distributed with the.
        <literal>xdg-hostname</literal> project.
      </para>
    </partintro>
    <xi:include href="man/xdg-hostname-1.xml"/>
    <xi:include href="man/xdg-hostnamed-1.xml"/>
  </reference>

  <index>
    <title>Index</title>
  </index>

  <!-- License -->

  <appendix id="license">
    <title>License</title>
    <para>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../COPYING" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
    </para>
  </appendix>
</book>