05f429a29f9eabcb941dbc6cc1c3143c43c75adb
[ddns.git] / man / ddns.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">
6         <refentryinfo>
7                 <title>ddns</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</refentrytitle>
22                 <manvolnum>1</manvolnum>
23         </refmeta>
24
25         <refnamediv>
26                 <refname>ddns</refname>
27                 <refpurpose>Dynamic DNS update client</refpurpose>
28         </refnamediv>
29
30         <refsynopsisdiv>
31                 <cmdsynopsis>
32                         <command>ddns</command>
33                         <arg choice="opt" rep="repeat">OPTIONS</arg>
34                         <arg choice="plain">COMMAND</arg>
35                 </cmdsynopsis>
36         </refsynopsisdiv>
37
38         <refsect1>
39                 <title>Description</title>
40
41                 <para>
42                         <command>ddns</command> is a simple, extensible, cross-distribution,
43                         cross-platform dynamic DNS updater written in Python.
44                 </para>
45         </refsect1>
46
47         <refsect1>
48                 <title>Options</title>
49
50                 <para>
51                         The following options are understood:
52                 </para>
53
54                 <variablelist>
55                         <varlistentry>
56                                 <term>
57                                         <option>-c CONFIG</option>
58                                 </term>
59                                 <term>
60                                         <option>--config CONFIG</option>
61                                 </term>
62
63                                 <listitem>
64                                         <para>
65                                                 Load the specified configuration file.
66                                                 (Default: <filename>/etc/ddns/ddns.conf</filename>)
67                                         </para>
68
69                                         <para>
70                                                 For further details of the config file layout, please consult the
71                                                 <citerefentry>
72                                                         <refentrytitle>ddns.conf</refentrytitle>
73                                                         <manvolnum>5</manvolnum>
74                                                 </citerefentry>
75                                                 manual page.
76                                         </para>
77                                 </listitem>
78                         </varlistentry>
79
80                         <varlistentry>
81                                 <term>
82                                         <option>-d</option>
83                                 </term>
84                                 <term>
85                                         <option>--debug</option>
86                                 </term>
87
88                                 <listitem>
89                                         <para>
90                                                 Enables the debugging mode.
91                                                 In this mode, there will be debug output on
92                                                 the console and written to the log.
93                                         </para>
94                                 </listitem>
95                         </varlistentry>
96
97                         <varlistentry>
98                                 <term>
99                                         <option>-h</option>
100                                 </term>
101                                 <term>
102                                         <option>--help</option>
103                                 </term>
104
105                                 <listitem>
106                                         <para>
107                                                 Shows the help message provided by the program and exit.
108                                         </para>
109                                 </listitem>
110                         </varlistentry>
111                 </variablelist>
112         </refsect1>
113
114         <refsect1>
115                 <title>Commands</title>
116
117                 <para>
118                         The following commands are understood:
119                 </para>
120
121                 <variablelist>
122                         <varlistentry>
123                                 <term>
124                                         <command>update-all</command>
125                                 </term>
126
127                                 <listitem>
128                                         <para>
129                                                 Update all configured dynamic DNS hosts.
130                                         </para>
131                                 </listitem>
132                         </varlistentry>
133
134                         <varlistentry>
135                                 <term>
136                                         <command>update <replaceable>HOSTNAME</replaceable></command>
137                                 </term>
138
139                                 <listitem>
140                                         <para>
141                                                 Perform an update for a single host, specified by the
142                                                 given hostname.
143                                         </para>
144
145                                         <para>
146                                                 Example: <command>ddns update somehost.provider.com</command>
147                                         </para>
148                                 </listitem>
149                         </varlistentry>
150
151                         <varlistentry>
152                                 <term>
153                                         <option>--force</option>
154                                 </term>
155
156                                 <listitem>
157                                         <para>
158                                                 When calling an update, the DDNS client automatically checks
159                                                 if this update is required by testing whether the hostname points
160                                                 to the current public IP address. If this test returns true, the call
161                                                 can be droped and no request will be sent to the provider.
162                                         </para>
163
164                                         <para>
165                                                 In cases an update request should be send nevertheless, the update can be
166                                                 forced by using this switch.
167                                         </para>
168
169                                         <para>
170                                                 Example: <command>ddns update somehost.provider.com --force</command> or
171                                                 <command>ddns update-all --force</command>
172                                         </para>
173                                 </listitem>
174                         </varlistentry>
175
176                         <varlistentry>
177                                 <term>
178                                         <command>guess-ip-addresses</command>
179                                 </term>
180
181                                 <listitem>
182                                         <para>
183                                                 Try to guess and print the hosts IPv4 and IPv6 addresses
184                                                 based on the choosen method in the used config file.
185                                         </para>
186
187                                         <para>
188                                                 The addresses can be obtained from the system or by
189                                                 help of an external server. For systems behind a NAT the
190                                                 second method is recommended.
191                                         </para>
192
193                                         <para>
194                                                 For further details, please consult the
195                                                 <citerefentry>
196                                                         <refentrytitle>ddns.conf</refentrytitle>
197                                                         <manvolnum>5</manvolnum>
198                                                 </citerefentry>
199                                                 manual page.
200                                         </para>
201                                 </listitem>
202                         </varlistentry>
203
204                         <varlistentry>
205                                 <term>
206                                         <command>list-providers</command>
207                                 </term>
208
209                                 <listitem>
210                                         <para>
211                                                 This command will print out a list of all
212                                                 supported dynamic DNS providers.
213                                         </para>
214
215                                         <para>
216                                                 For details how to add support for new providers,
217                                                 please consult the
218                                                 <citerefentry>
219                                                         <refentrytitle>ddns-devel</refentrytitle>
220                                                         <manvolnum>7</manvolnum>
221                                                 </citerefentry>
222                                                 manual page.
223                                         </para>
224                                 </listitem>
225                         </varlistentry>
226                 </variablelist>
227         </refsect1>
228
229         <refsect1>
230                 <title>Exit Codes</title>
231
232                 <para>
233                         <command>ddns</command> will normally exit with code 0.
234                         If there has been a problem and the requested action could not be done,
235                         the exit code is unequal to zero.
236                 </para>
237         </refsect1>
238
239         <refsect1>
240                 <title>Bugs</title>
241
242                 <para>
243                         Please report all bugs to the official bugtracker at
244                         http://bugs.ipfire.org/.
245                 </para>
246         </refsect1>
247
248         <refsect1>
249                 <title>See Also</title>
250
251                 <para>
252                         <citerefentry>
253                                 <refentrytitle>ddns.conf</refentrytitle>
254                                 <manvolnum>5</manvolnum>
255                         </citerefentry>, 
256                         <citerefentry>
257                                 <refentrytitle>ddns-devel</refentrytitle>
258                                 <manvolnum>7</manvolnum>
259                         </citerefentry>
260                 </para>
261         </refsect1>
262 </refentry>