Improve man pages
[ddns.git] / man / ddns.conf.xml
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>
17
18                         <author>
19                                 <contrib>Developer</contrib>
20                                 <firstname>Michael</firstname>
21                                 <surname>Tremer</surname>
22                                 <email>michael.tremer@ipfire.org</email>
23                         </author>
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>
34                 <refpurpose>Configuration file for the DDNS update client</refpurpose>
35         </refnamediv>
36
37         <refsect1>
38                 <title>Description</title>
39
40                 <para>
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>.
46                 </para>
47
48                 <para>
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.
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>
70                                                 This option will configure the HTTP proxy server that is used to
71                                                 communicate with the providers HTTP APIs.
72                                         </para>
73
74                                         <para>
75                                                 The proxy only can be contacted by using the HTTP protocol. The
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>
78                                         </para>
79                                 </listitem>
80                         </varlistentry>
81
82                         <varlistentry>
83                                 <term>
84                                         <option>guess_external_ip = [true|<emphasis>false</emphasis>]</option>
85                                 </term>
86
87                                 <listitem>
88                                         <para>
89                                                 Determine the public IP addresses by using external servers.
90                                         </para>
91
92                                         <para>
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.
96                                         </para>
97                                 </listitem>
98                         </varlistentry>
99                 </variablelist>
100         </refsect1>
101
102         <refsect1>
103                 <title>Provider Configuration</title>
104
105                 <para>
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.
109                 </para>
110
111                 <variablelist>
112                         <varlistentry>
113                                 <term>
114                                         <command>[hostname.someprovider.com]</command>
115                                 </term>
116
117                                 <listitem>
118                                         <para>
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.
122                                         </para>
123                                 </listitem>
124                         </varlistentry>
125
126                         <varlistentry>
127                                 <term>
128                                         <command>handle = someprovider.com</command>
129                                 </term>
130
131                                 <listitem>
132                                         <para>
133                                                 The provider which is responsible for this host.
134                                         </para>
135
136                                         <para>
137                                                 A list of all supported providers can be looked up by running
138                                                 <command>ddns list-providers</command>.
139                                         </para>
140                                 </listitem>
141                         </varlistentry>
142
143                         <varlistentry>
144                                 <term>
145                                         <command>username = user</command>
146                                 </term>
147
148                                 <listitem>
149                                         <para>
150                                                 The username to authenticate against the provider's update service.
151                                         </para>
152
153                                         <para>
154                                                 In most cases this will be the same username which can be used to login on
155                                                 your provider's web page.
156                                         </para>
157                                 </listitem>
158                         </varlistentry>
159
160                         <varlistentry>
161                                 <term>
162                                         <command>password = password</command>
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>
179                                                 An authentication token.
180                                         </para>
181
182                                         <para>
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.
187                                         </para>
188                                 </listitem>
189                         </varlistentry>
190                 </variablelist>
191         </refsect1>
192
193         <refsect1>
194                 <title>Examples</title>
195
196                 <example>
197                         <title>For providers which use username and password for client authentication</title>
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>
208                         <title>For providers which supports token-based authentication</title>
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>
235                 </para>
236         </refsect1>
237 </refentry>