<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>
<refnamediv>
<refname>ddns.conf</refname>
- <refpurpose>Configuration file for the DDNS update client.</refpurpose>
+ <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 for the
- <command>ddns</command> update client. This file specifies some basic options
- for the programm and contain multiple sections which imply hostname and auth information
- for each used provider.
+ 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>
- Lines starting with a hash mark (''#'') and empty lines are ignored.
+ 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>
<listitem>
<para>
- Using this option allows the usage of a proxy server while
- performing updates.
+ 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 the used port.
- </para>
-
- <para>
- Example: proxy = http://192.168.180.1:800
+ 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 = [<emphasis>true</emphasis>|false]</option>
+ <option>guess_external_ip = [true|<emphasis>false</emphasis>]</option>
</term>
<listitem>
</para>
<para>
- The default value if this setting is not configured is
- <emphasis>true</emphasis>.
+ 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>
<title>Provider Configuration</title>
<para>
- The DDNS client supports the configuration of an unlimited amount of entries on different providers.
- Each entry has to be configured as an own section which has to be initiated with the choosen FQDN
- (Fully Qualified Domain Name) inside of squared brackets.
+ 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>
<listitem>
<para>
- Specifies the choosen FQDN composed of the hostname and the selected domain from the
- desired dynamic DNS provider.
+ 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>
<listitem>
<para>
- The provider which is responsible for the configured FQDN.
+ The provider which is responsible for this host.
</para>
<para>
- A list of all supported providers can be found in the <filename>ddns.conf.sample</filename>
- or the <filename>README</filename> file shipped by the source code.
+ A list of all supported providers can be looked up by running
+ <command>ddns list-providers</command>.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
- The used username to authenticate against your providers update service.
+ 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 providers webpage.
+ your provider's web page.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <command>password = pass</command>
+ <command>password = password</command>
</term>
<listitem>
<listitem>
<para>
- Just the authentication token.
+ An authentication token.
</para>
<para>
- If your dynamic DNS provider supports token-based auth, this method should
- be prefered.
+ 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>
<title>Examples</title>
<example>
- <title>A provider which uses username and password for client authentication.</title>
+ <title>For providers which use username and password for client authentication</title>
<simplelist>
<member>[somehost.provider.com]</member>
</example>
<example>
- <title>Provider which supports token based auth.</title>
+ <title>For providers which supports token-based authentication</title>
<simplelist>
<member>[anotherhost.provider.com]</member>
<refentrytitle>ddns</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
- <citerefentry>
- <refentrytitle>ddns-devel</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
</para>
</refsect1>
</refentry>
<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>
<listitem>
<para>
- Enables the debugging mode.
- In this mode, there will be debug output on
- the console and written to the log.
+ Enables the debugging output.
</para>
</listitem>
</varlistentry>
</para>
<variablelist>
- <varlistentry>
- <term>
- <command>update-all</command>
- </term>
-
- <listitem>
- <para>
- Update all configured dynamic DNS hosts.
- </para>
- </listitem>
- </varlistentry>
<varlistentry>
<term>
- <command>update <replaceable>HOSTNAME</replaceable></command>
+ <command>update <option>[--force]</option> <replaceable>HOSTNAME</replaceable></command>
</term>
<listitem>
</para>
<para>
- Example: <command>ddns update somehost.provider.com</command>
+ When calling an update, the DDNS client automatically checks
+ if this update is required by testing whether the hostname points
+ to the current public IP address.
+ Therefore it is not guaranteed than an update is performed.
+ </para>
+
+ <para>
+ The <option>--force</option> switch can be used to skip that
+ check and perform an update. Please note that some providers
+ may block your account if unnecessary updates are repeatedly
+ performed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <option>--force</option>
+ <command>update-all <option>[--force]</option></command>
</term>
<listitem>
<para>
- When calling an update, the DDNS client automatically checks
- if this update is required by testing whether the hostname points
- to the current public IP address. If this test returns true, the call
- can be droped and no request will be sent to the provider.
- </para>
-
- <para>
- In cases an update request should be send nevertheless, the update can be
- forced by using this switch.
+ Update all configured dynamic DNS hosts when an update is necessary.
</para>
<para>
- Example: <command>ddns update somehost.provider.com --force</command> or
- <command>ddns update-all --force</command>
+ The <option>--force</option> switch has the same effect as
+ with the <command>update</command> command.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
- Try to guess and print the hosts IPv4 and IPv6 addresses
- based on the choosen method in the used config file.
+ Guesses the public IPv6 and IPv4 addresses with help of an
+ external server and prints them on the conole.
</para>
-
- <para>
- The addresses can be obtained from the system or by
- help of an external server. For systems behind a NAT the
- second method is recommended.
- </para>
-
- <para>
- For further details, please consult the
- <citerefentry>
- <refentrytitle>ddns.conf</refentrytitle>
- <manvolnum>5</manvolnum>
- </citerefentry>
- manual page.
- </para>
</listitem>
</varlistentry>
This command will print out a list of all
supported dynamic DNS providers.
</para>
-
- <para>
- For details how to add support for new providers,
- please consult the
- <citerefentry>
- <refentrytitle>ddns-devel</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- manual page.
- </para>
</listitem>
</varlistentry>
</variablelist>
<citerefentry>
<refentrytitle>ddns.conf</refentrytitle>
<manvolnum>5</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>ddns-devel</refentrytitle>
- <manvolnum>7</manvolnum>
</citerefentry>
</para>
</refsect1>
projects / oddments / ddns.git / commitdiff
