Add domains.google.com as provider.

[ddns.git] / man / ddns.conf.xml

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="ddns.conf">
        <refentryinfo>
                <title>ddns.conf</title>
                <productname>ddns</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Stefan</firstname>
                                <surname>Schantl</surname>
                                <email>stefan.schantl@ipfire.org</email>
                        </author>

                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Michael</firstname>
                                <surname>Tremer</surname>
                                <email>michael.tremer@ipfire.org</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>ddns.conf</refentrytitle>
                <manvolnum>5</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>ddns.conf</refname>
                <refpurpose>Configuration file for the DDNS update client</refpurpose>
        </refnamediv>

        <refsect1>
                <title>Description</title>

                <para>
                        The <filename>ddns.conf</filename> file is the main configuration file of the
                        <command>ddns</command> update client.
                        This file specifies runtime configuration parameters for the programm and
                        contains configurations for dynamic host entries that are managed by
                        <command>ddns</command>.
                </para>

                <para>
                        The syntax of the configuration file is based on the INI configuration
                        file format. Lines starting with hash (#) or semi-colon (;)
                        are ignored.
                </para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>
                        The following options can be configured:
                </para>

                <variablelist>
                        <varlistentry>
                                <term>
                                        <option>proxy = http://IP:PORT</option>
                                </term>

                                <listitem>
                                        <para>
                                                This option will configure the HTTP proxy server that is used to
                                                communicate with the providers HTTP APIs.
                                        </para>

                                        <para>
                                                The proxy only can be contacted by using the HTTP protocol. The
                                                server has to be specified by using its IP address and port.
                                                For example: <option>proxy = http://192.168.180.1:800</option>
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>
                                        <option>guess_external_ip = [true|<emphasis>false</emphasis>]</option>
                                </term>

                                <listitem>
                                        <para>
                                                Determine the public IP addresses by using external servers.
                                        </para>

                                        <para>
                                                By default, this option is disabled and automatically enabled
                                                if the client has only IP addresses defined in RFC1918 or
                                                other reserved address space.
                                        </para>
                                </listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                <title>Provider Configuration</title>

                <para>
                        The DDNS client supports the configuration of an unlimited amount of entries for different providers.
                        Each entry has to be configured as an own section named by the FQDN (Fully Qualified Domain Name)
                        inside squared brackets.
                </para>

                <variablelist>
                        <varlistentry>
                                <term>
                                        <command>[hostname.someprovider.com]</command>
                                </term>

                                <listitem>
                                        <para>
                                                The FQDN of the dynamic host. This name will be resolved
                                                by <command>ddns</command> and therfore must not be a handle or something
                                                other than a FQDN.
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>
                                        <command>handle = someprovider.com</command>
                                </term>

                                <listitem>
                                        <para>
                                                The provider which is responsible for this host.
                                        </para>

                                        <para>
                                                A list of all supported providers can be looked up by running
                                                <command>ddns list-providers</command>.
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>
                                        <command>username = user</command>
                                </term>

                                <listitem>
                                        <para>
                                                The username to authenticate against the provider's update service.
                                        </para>

                                        <para>
                                                In most cases this will be the same username which can be used to login on
                                                your provider's web page.
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>
                                        <command>password = password</command>
                                </term>

                                <listitem>
                                        <para>
                                                The choosen password for the specified username.
                                        </para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>
                                        <command>token = token</command>
                                </term>

                                <listitem>
                                        <para>
                                                An authentication token.
                                        </para>

                                        <para>
                                                If your dynamic DNS provider supports token-based authentication,
                                                this method should be prefered.
                                                You do not need to specify the username if token-based authentication
                                                is used.
                                        </para>
                                </listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                <title>Examples</title>

                <example>
                        <title>For providers which use username and password for client authentication</title>

                        <simplelist>
                                <member>[somehost.provider.com]</member>
                                <member>handle = provider.com</member>
                                <member>username = username</member>
                                <member>password = password</member>
                        </simplelist>
                </example>

                <example>
                        <title>For providers which supports token-based authentication</title>

                        <simplelist>
                                <member>[anotherhost.provider.com]</member>
                                <member>handle = provider.com</member>
                                <member>token = token</member>
                        </simplelist>
                </example>
        </refsect1>

        <refsect1>
                <title>Bugs</title>

                <para>
                        Please report all bugs to the official bugtracker at
                        http://bugs.ipfire.org/.
                </para>
        </refsect1>

        <refsect1>
                <title>See Also</title>

                <para>
                        <citerefentry>
                                <refentrytitle>ddns</refentrytitle>
                                <manvolnum>1</manvolnum>
                        </citerefentry>
                </para>
        </refsect1>
</refentry>