Improve man pages
[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
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</refentrytitle>
29                 <manvolnum>1</manvolnum>
30         </refmeta>
31
32         <refnamediv>
33                 <refname>ddns</refname>
34                 <refpurpose>Dynamic DNS update client</refpurpose>
35         </refnamediv>
36
37         <refsynopsisdiv>
38                 <cmdsynopsis>
39                         <command>ddns</command>
40                         <arg choice="opt" rep="repeat">OPTIONS</arg>
41                         <arg choice="plain">COMMAND</arg>
42                 </cmdsynopsis>
43         </refsynopsisdiv>
44
45         <refsect1>
46                 <title>Description</title>
47
48                 <para>
49                         <command>ddns</command> is a simple, extensible, cross-distribution,
50                         cross-platform dynamic DNS updater written in Python.
51                 </para>
52         </refsect1>
53
54         <refsect1>
55                 <title>Options</title>
56
57                 <para>
58                         The following options are understood:
59                 </para>
60
61                 <variablelist>
62                         <varlistentry>
63                                 <term>
64                                         <option>-c CONFIG</option>
65                                 </term>
66                                 <term>
67                                         <option>--config CONFIG</option>
68                                 </term>
69
70                                 <listitem>
71                                         <para>
72                                                 Load the specified configuration file.
73                                                 (Default: <filename>/etc/ddns/ddns.conf</filename>)
74                                         </para>
75
76                                         <para>
77                                                 For further details of the config file layout, please consult the
78                                                 <citerefentry>
79                                                         <refentrytitle>ddns.conf</refentrytitle>
80                                                         <manvolnum>5</manvolnum>
81                                                 </citerefentry>
82                                                 manual page.
83                                         </para>
84                                 </listitem>
85                         </varlistentry>
86
87                         <varlistentry>
88                                 <term>
89                                         <option>-d</option>
90                                 </term>
91                                 <term>
92                                         <option>--debug</option>
93                                 </term>
94
95                                 <listitem>
96                                         <para>
97                                                 Enables the debugging output.
98                                         </para>
99                                 </listitem>
100                         </varlistentry>
101
102                         <varlistentry>
103                                 <term>
104                                         <option>-h</option>
105                                 </term>
106                                 <term>
107                                         <option>--help</option>
108                                 </term>
109
110                                 <listitem>
111                                         <para>
112                                                 Shows the help message provided by the program and exit.
113                                         </para>
114                                 </listitem>
115                         </varlistentry>
116                 </variablelist>
117         </refsect1>
118
119         <refsect1>
120                 <title>Commands</title>
121
122                 <para>
123                         The following commands are understood:
124                 </para>
125
126                 <variablelist>
127
128                         <varlistentry>
129                                 <term>
130                                         <command>update <option>[--force]</option> <replaceable>HOSTNAME</replaceable></command>
131                                 </term>
132
133                                 <listitem>
134                                         <para>
135                                                 Perform an update for a single host, specified by the
136                                                 given hostname.
137                                         </para>
138
139                                         <para>
140                                                 When calling an update, the DDNS client automatically checks
141                                                 if this update is required by testing whether the hostname points
142                                                 to the current public IP address.
143                                                 Therefore it is not guaranteed than an update is performed.
144                                         </para>
145
146                                         <para>
147                                                 The <option>--force</option> switch can be used to skip that
148                                                 check and perform an update. Please note that some providers
149                                                 may block your account if unnecessary updates are repeatedly
150                                                 performed.
151                                         </para>
152                                 </listitem>
153                         </varlistentry>
154
155                         <varlistentry>
156                                 <term>
157                                         <command>update-all <option>[--force]</option></command>
158                                 </term>
159
160                                 <listitem>
161                                         <para>
162                                                 Update all configured dynamic DNS hosts when an update is necessary.
163                                         </para>
164
165                                         <para>
166                                                 The <option>--force</option> switch has the same effect as
167                                                 with the <command>update</command> command.
168                                         </para>
169                                 </listitem>
170                         </varlistentry>
171
172                         <varlistentry>
173                                 <term>
174                                         <command>guess-ip-addresses</command>
175                                 </term>
176
177                                 <listitem>
178                                         <para>
179                                                 Guesses the public IPv6 and IPv4 addresses with help of an
180                                                 external server and prints them on the conole.
181                                         </para>
182                                 </listitem>
183                         </varlistentry>
184
185                         <varlistentry>
186                                 <term>
187                                         <command>list-providers</command>
188                                 </term>
189
190                                 <listitem>
191                                         <para>
192                                                 This command will print out a list of all
193                                                 supported dynamic DNS providers.
194                                         </para>
195                                 </listitem>
196                         </varlistentry>
197                 </variablelist>
198         </refsect1>
199
200         <refsect1>
201                 <title>Exit Codes</title>
202
203                 <para>
204                         <command>ddns</command> will normally exit with code 0.
205                         If there has been a problem and the requested action could not be done,
206                         the exit code is unequal to zero.
207                 </para>
208         </refsect1>
209
210         <refsect1>
211                 <title>Bugs</title>
212
213                 <para>
214                         Please report all bugs to the official bugtracker at
215                         http://bugs.ipfire.org/.
216                 </para>
217         </refsect1>
218
219         <refsect1>
220                 <title>See Also</title>
221
222                 <para>
223                         <citerefentry>
224                                 <refentrytitle>ddns.conf</refentrytitle>
225                                 <manvolnum>5</manvolnum>
226                         </citerefentry>
227                 </para>
228         </refsect1>
229 </refentry>