Improve man pages
[ddns.git] / man / ddns.conf.xml
CommitLineData
3c5ba60d
SS
1<?xml version="1.0"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5<refentry id="ddns.conf">
6 <refentryinfo>
7 <title>ddns.conf</title>
8 <productname>ddns</productname>
9
10 <authorgroup>
11 <author>
12 <contrib>Developer</contrib>
13 <firstname>Stefan</firstname>
14 <surname>Schantl</surname>
15 <email>stefan.schantl@ipfire.org</email>
16 </author>
f6719cee
MT
17
18 <author>
19 <contrib>Developer</contrib>
20 <firstname>Michael</firstname>
21 <surname>Tremer</surname>
22 <email>michael.tremer@ipfire.org</email>
23 </author>
3c5ba60d
SS
24 </authorgroup>
25 </refentryinfo>
26
27 <refmeta>
28 <refentrytitle>ddns.conf</refentrytitle>
29 <manvolnum>5</manvolnum>
30 </refmeta>
31
32 <refnamediv>
33 <refname>ddns.conf</refname>
f6719cee 34 <refpurpose>Configuration file for the DDNS update client</refpurpose>
3c5ba60d
SS
35 </refnamediv>
36
37 <refsect1>
38 <title>Description</title>
39
40 <para>
f6719cee
MT
41 The <filename>ddns.conf</filename> file is the main configuration file of the
42 <command>ddns</command> update client.
43 This file specifies runtime configuration parameters for the programm and
44 contains configurations for dynamic host entries that are managed by
45 <command>ddns</command>.
3c5ba60d
SS
46 </para>
47
48 <para>
f6719cee
MT
49 The syntax of the configuration file is based on the INI configuration
50 file format. Lines starting with hash (#) or semi-colon (;)
51 are ignored.
3c5ba60d
SS
52 </para>
53 </refsect1>
54
55 <refsect1>
56 <title>Options</title>
57
58 <para>
59 The following options can be configured:
60 </para>
61
62 <variablelist>
63 <varlistentry>
64 <term>
65 <option>proxy = http://IP:PORT</option>
66 </term>
67
68 <listitem>
69 <para>
f6719cee
MT
70 This option will configure the HTTP proxy server that is used to
71 communicate with the providers HTTP APIs.
3c5ba60d
SS
72 </para>
73
74 <para>
75 The proxy only can be contacted by using the HTTP protocol. The
f6719cee
MT
76 server has to be specified by using its IP address and port.
77 For example: <option>proxy = http://192.168.180.1:800</option>
3c5ba60d
SS
78 </para>
79 </listitem>
80 </varlistentry>
81
82 <varlistentry>
83 <term>
f6719cee 84 <option>guess_external_ip = [true|<emphasis>false</emphasis>]</option>
3c5ba60d
SS
85 </term>
86
87 <listitem>
88 <para>
89 Determine the public IP addresses by using external servers.
90 </para>
91
92 <para>
f6719cee
MT
93 By default, this option is disabled and automatically enabled
94 if the client has only IP addresses defined in RFC1918 or
95 other reserved address space.
3c5ba60d
SS
96 </para>
97 </listitem>
98 </varlistentry>
99 </variablelist>
100 </refsect1>
101
102 <refsect1>
103 <title>Provider Configuration</title>
104
105 <para>
f6719cee
MT
106 The DDNS client supports the configuration of an unlimited amount of entries for different providers.
107 Each entry has to be configured as an own section named by the FQDN (Fully Qualified Domain Name)
108 inside squared brackets.
3c5ba60d
SS
109 </para>
110
111 <variablelist>
112 <varlistentry>
113 <term>
114 <command>[hostname.someprovider.com]</command>
115 </term>
116
117 <listitem>
118 <para>
f6719cee
MT
119 The FQDN of the dynamic host. This name will be resolved
120 by <command>ddns</command> and therfore must not be a handle or something
121 other than a FQDN.
3c5ba60d
SS
122 </para>
123 </listitem>
124 </varlistentry>
125
126 <varlistentry>
127 <term>
128 <command>handle = someprovider.com</command>
129 </term>
130
131 <listitem>
132 <para>
f6719cee 133 The provider which is responsible for this host.
3c5ba60d
SS
134 </para>
135
136 <para>
f6719cee
MT
137 A list of all supported providers can be looked up by running
138 <command>ddns list-providers</command>.
3c5ba60d
SS
139 </para>
140 </listitem>
141 </varlistentry>
142
143 <varlistentry>
144 <term>
145 <command>username = user</command>
146 </term>
147
148 <listitem>
149 <para>
f6719cee 150 The username to authenticate against the provider's update service.
3c5ba60d
SS
151 </para>
152
153 <para>
154 In most cases this will be the same username which can be used to login on
f6719cee 155 your provider's web page.
3c5ba60d
SS
156 </para>
157 </listitem>
158 </varlistentry>
159
160 <varlistentry>
161 <term>
f6719cee 162 <command>password = password</command>
3c5ba60d
SS
163 </term>
164
165 <listitem>
166 <para>
167 The choosen password for the specified username.
168 </para>
169 </listitem>
170 </varlistentry>
171
172 <varlistentry>
173 <term>
174 <command>token = token</command>
175 </term>
176
177 <listitem>
178 <para>
f6719cee 179 An authentication token.
3c5ba60d
SS
180 </para>
181
182 <para>
f6719cee
MT
183 If your dynamic DNS provider supports token-based authentication,
184 this method should be prefered.
185 You do not need to specify the username if token-based authentication
186 is used.
3c5ba60d
SS
187 </para>
188 </listitem>
189 </varlistentry>
190 </variablelist>
191 </refsect1>
192
193 <refsect1>
194 <title>Examples</title>
195
196 <example>
f6719cee 197 <title>For providers which use username and password for client authentication</title>
3c5ba60d
SS
198
199 <simplelist>
200 <member>[somehost.provider.com]</member>
201 <member>handle = provider.com</member>
202 <member>username = username</member>
203 <member>password = password</member>
204 </simplelist>
205 </example>
206
207 <example>
f6719cee 208 <title>For providers which supports token-based authentication</title>
3c5ba60d
SS
209
210 <simplelist>
211 <member>[anotherhost.provider.com]</member>
212 <member>handle = provider.com</member>
213 <member>token = token</member>
214 </simplelist>
215 </example>
216 </refsect1>
217
218 <refsect1>
219 <title>Bugs</title>
220
221 <para>
222 Please report all bugs to the official bugtracker at
223 http://bugs.ipfire.org/.
224 </para>
225 </refsect1>
226
227 <refsect1>
228 <title>See Also</title>
229
230 <para>
231 <citerefentry>
232 <refentrytitle>ddns</refentrytitle>
233 <manvolnum>1</manvolnum>
234 </citerefentry>
3c5ba60d
SS
235 </para>
236 </refsect1>
237</refentry>