a00ccc61747348a68830b90c9176833f29ea5ed9
[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                 </authorgroup>
18         </refentryinfo>
19
20         <refmeta>
21                 <refentrytitle>ddns.conf</refentrytitle>
22                 <manvolnum>5</manvolnum>
23         </refmeta>
24
25         <refnamediv>
26                 <refname>ddns.conf</refname>
27                 <refpurpose>Configuration file for the DDNS update client.</refpurpose>
28         </refnamediv>
29
30         <refsect1>
31                 <title>Description</title>
32
33                 <para>
34                         The <filename>ddns.conf</filename> file is the main configuration file for the
35                         <command>ddns</command> update client. This file specifies some basic options
36                         for the programm and contain multiple sections which imply hostname and auth information
37                         for each used provider.
38                 </para>
39
40                 <para>
41                         Lines starting with a hash mark (''#'') and empty lines are ignored.
42                 </para>
43         </refsect1>
44
45         <refsect1>
46                 <title>Options</title>
47
48                 <para>
49                         The following options can be configured:
50                 </para>
51
52                 <variablelist>
53                         <varlistentry>
54                                 <term>
55                                         <option>proxy = http://IP:PORT</option>
56                                 </term>
57
58                                 <listitem>
59                                         <para>
60                                                 Using this option allows the usage of a proxy server while
61                                                 performing updates.
62                                         </para>
63
64                                         <para>
65                                                 The proxy only can be contacted by using the HTTP protocol. The
66                                                 server has to be specified by using its IP address and the used port.
67                                         </para>
68
69                                         <para>
70                                                 Example: proxy = http://192.168.180.1:800
71                                         </para>
72                                 </listitem>
73                         </varlistentry>
74
75                         <varlistentry>
76                                 <term>
77                                         <option>guess_external_ip = [<emphasis>true</emphasis>|false]</option>
78                                 </term>
79
80                                 <listitem>
81                                         <para>
82                                                 Determine the public IP addresses by using external servers.
83                                         </para>
84
85                                         <para>
86                                                 The default value if this setting is not configured is
87                                                 <emphasis>true</emphasis>.
88                                         </para>
89                                 </listitem>
90                         </varlistentry>
91                 </variablelist>
92         </refsect1>
93
94         <refsect1>
95                 <title>Provider Configuration</title>
96
97                 <para>
98                         The DDNS client supports the configuration of an unlimited amount of entries on different providers.
99                         Each entry has to be configured as an own section which has to be initiated with the choosen FQDN
100                         (Fully Qualified Domain Name) inside of squared brackets.
101                 </para>
102
103                 <variablelist>
104                         <varlistentry>
105                                 <term>
106                                         <command>[hostname.someprovider.com]</command>
107                                 </term>
108
109                                 <listitem>
110                                         <para>
111                                                 Specifies the choosen FQDN composed of the hostname and the selected domain from the
112                                                 desired dynamic DNS provider.
113                                         </para>
114                                 </listitem>
115                         </varlistentry>
116
117                         <varlistentry>
118                                 <term>
119                                         <command>handle = someprovider.com</command>
120                                 </term>
121
122                                 <listitem>
123                                         <para>
124                                                 The provider which is responsible for the configured FQDN.
125                                         </para>
126
127                                         <para>
128                                                 A list of all supported providers can be found in the <filename>ddns.conf.sample</filename>
129                                                 or the <filename>README</filename> file shipped by the source code.
130                                         </para>
131                                 </listitem>
132                         </varlistentry>
133
134                         <varlistentry>
135                                 <term>
136                                         <command>username = user</command>
137                                 </term>
138
139                                 <listitem>
140                                         <para>
141                                                 The used username to authenticate against your providers update service.
142                                         </para>
143
144                                         <para>
145                                                 In most cases this will be the same username which can be used to login on
146                                                 your providers webpage.
147                                         </para>
148                                 </listitem>
149                         </varlistentry>
150
151                         <varlistentry>
152                                 <term>
153                                         <command>password = pass</command>
154                                 </term>
155
156                                 <listitem>
157                                         <para>
158                                                 The choosen password for the specified username.
159                                         </para>
160                                 </listitem>
161                         </varlistentry>
162
163                         <varlistentry>
164                                 <term>
165                                         <command>token = token</command>
166                                 </term>
167
168                                 <listitem>
169                                         <para>
170                                                 Just the authentication token.
171                                         </para>
172
173                                         <para>
174                                                 If your dynamic DNS provider supports token-based auth, this method should
175                                                 be prefered.
176                                         </para>
177                                 </listitem>
178                         </varlistentry>
179                 </variablelist>
180         </refsect1>
181
182         <refsect1>
183                 <title>Examples</title>
184
185                 <example>
186                         <title>A provider which uses username and password for client authentication.</title>
187
188                         <simplelist>
189                                 <member>[somehost.provider.com]</member>
190                                 <member>handle = provider.com</member>
191                                 <member>username = username</member>
192                                 <member>password = password</member>
193                         </simplelist>
194                 </example>
195
196                 <example>
197                         <title>Provider which supports token based auth.</title>
198
199                         <simplelist>
200                                 <member>[anotherhost.provider.com]</member>
201                                 <member>handle = provider.com</member>
202                                 <member>token = token</member>
203                         </simplelist>
204                 </example>
205         </refsect1>
206
207         <refsect1>
208                 <title>Bugs</title>
209
210                 <para>
211                         Please report all bugs to the official bugtracker at
212                         http://bugs.ipfire.org/.
213                 </para>
214         </refsect1>
215
216         <refsect1>
217                 <title>See Also</title>
218
219                 <para>
220                         <citerefentry>
221                                 <refentrytitle>ddns</refentrytitle>
222                                 <manvolnum>1</manvolnum>
223                         </citerefentry>
224                         <citerefentry>
225                                 <refentrytitle>ddns-devel</refentrytitle>
226                                 <manvolnum>7</manvolnum>
227                         </citerefentry>
228                 </para>
229         </refsect1>
230 </refentry>