Improve man pages

[oddments/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>