Mercurial > projects > relmon

comparison relmon.1.xml @ 4:f28486666a4f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add manpages for relmon and relmon_watchlist
author Guido Berhoerster <guido+relmon@berhoerster.name>
date Fri, 24 Oct 2014 22:44:39 +0200
parents
children 86a0c5d11f05
comparison
equal deleted inserted replaced
3:6d87242c537e 4:f28486666a4f
1 <?xml version="1.0"?>
2 <!--
3
4 Copyright (C) 2014 Guido Berhoerster <guido+relmon@berhoerster.name>
5
6 Permission is hereby granted, free of charge, to any person obtaining
7 a copy of this software and associated documentation files (the
8 "Software"), to deal in the Software without restriction, including
9 without limitation the rights to use, copy, modify, merge, publish,
10 distribute, sublicense, and/or sell copies of the Software, and to
11 permit persons to whom the Software is furnished to do so, subject to
12 the following conditions:
13
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24
25 -->
26 <refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
27 <info>
28 <author>
29 <personname>
30 <firstname>Guido</firstname>
31 <surname>Berhoerster</surname>
32 </personname>
33 <email>guido+relmon@berhoerster.name</email>
34 <personblurb/>
35 </author>
36 <date>24 October, 2014</date>
37 </info>
38 <refmeta>
39 <refentrytitle>relmon</refentrytitle>
40 <manvolnum>1</manvolnum>
41 <refmiscinfo class="source"/>
42 <refmiscinfo class="version"/>
43 <refmiscinfo class="manual">User Commands</refmiscinfo>
44 </refmeta>
45 <refnamediv>
46 <refname>relmon</refname>
47 <refpurpose>monitor websites of software projects for releases</refpurpose>
48 </refnamediv>
49 <refsynopsisdiv>
50 <cmdsynopsis>
51 <command>relmon list</command>
52 <arg choice="opt">
53 <option>-H</option>
54 </arg>
55 <arg choice="opt">
56 <option>-f</option>
57 <group choice="plain">
58 <arg choice="plain">html</arg>
59 <arg choice="plain">parseable</arg>
60 <arg choice="plain">text</arg>
61 </group>
62 </arg>
63 <arg choice="opt">
64 <option>-F</option>
65 <replaceable>url</replaceable>
66 </arg>
67 <arg choice="opt">
68 <option>-n</option>
69 <replaceable>number_items</replaceable>
70 </arg>
71 <arg choice="plain">
72 <replaceable>statefile</replaceable>
73 </arg>
74 </cmdsynopsis>
75 <cmdsynopsis>
76 <command>relmon list</command>
77 <arg choice="plain">
78 <option>-f</option>
79 <arg choice="plain">atom</arg>
80 </arg>
81 <arg choice="plain">
82 <option>-F</option>
83 <arg choice="plain">url</arg>
84 </arg>
85 <arg choice="opt">
86 <option>-n</option>
87 <replaceable>number_items</replaceable>
88 </arg>
89 <arg choice="plain">
90 <replaceable>statefile</replaceable>
91 </arg>
92 </cmdsynopsis>
93 <cmdsynopsis>
94 <command>relmon show</command>
95 <arg choice="plain">
96 <replaceable>statefile</replaceable>
97 </arg>
98 <arg choice="plain" rep="repeat">
99 <replaceable>name</replaceable>
100 </arg>
101 </cmdsynopsis>
102 <cmdsynopsis>
103 <command>relmon update</command>
104 <arg choice="opt">
105 <option>-d</option>
106 </arg>
107 <arg choice="opt">
108 <option>-e</option>
109 </arg>
110 <arg choice="opt">
111 <option>-v</option>
112 </arg>
113 <arg choice="opt">
114 <option>-c</option>
115 <replaceable>max_connections</replaceable>
116 </arg>
117 <arg choice="opt">
118 <option>-C</option>
119 <replaceable>ca_dir</replaceable>
120 </arg>
121 <arg choice="opt">
122 <option>-D</option>
123 <replaceable>delay</replaceable>
124 </arg>
125 <arg choice="opt">
126 <option>-H</option>
127 <replaceable>max_host_connections</replaceable>
128 </arg>
129 <arg choice="opt"><option>-i</option>
130 <arg choice="plain"><replaceable>item</replaceable></arg>
131 <arg choice="opt" rep="repeat"><replaceable>,</replaceable></arg>
132 </arg>
133 <arg choice="opt">
134 <option>-l</option>
135 <replaceable>logfile</replaceable>
136 </arg>
137 <arg choice="opt">
138 <option>-r</option>
139 <replaceable>retries</replaceable>
140 </arg>
141 <arg choice="opt">
142 <option>-t</option>
143 <replaceable>min_time</replaceable>
144 </arg>
145 <arg choice="plain">
146 <replaceable>watchlist</replaceable>
147 </arg>
148 <arg choice="plain">
149 <replaceable>statefile</replaceable>
150 </arg>
151 </cmdsynopsis>
152 <cmdsynopsis>
153 <command>relmon help</command>
154 <arg choice="opt">
155 <replaceable>subcommand</replaceable>
156 </arg>
157 </cmdsynopsis>
158 </refsynopsisdiv>
159 <refsect1>
160 <title>Description</title>
161 <para><command>relmon</command> is a utility for monitoring websites of
162 software projects for new releases. It can crawl websites via HTTP or
163 HTTPS using a configurable number of simultaneous connections and parse
164 HTML and XHTML documents as well as RSS 2.0 and Atom feeds. Software
165 releases are detected by extracting the version numbers from links to
166 distribution files from the parsed documents or feeds and comparing them
167 to previously extracted version numbers.</para>
168 <para>The crawling of the website of a software projects and the extraction
169 of version numbers are controlled by an entry with directions in a
170 watchlist file, see
171 <citerefentry><refentrytitle>relmon_watchlist</refentrytitle>
172 <manvolnum>4</manvolnum></citerefentry> for the exact format of
173 watchlist entries and further details on the operation of
174 <command>relmon</command>. In addition to the version numbers, the
175 history of releases consisting of the times new release were initially
176 discovered, any encountered errors and the time the version information
177 was last updated are recorded in a statefile. <command>relmon</command>
178 can selectively update explicitly specified items or on the basis of the
179 time an item was last updated or whether any errors were encountered
180 during the previous update of an item.</para>
181 <para>The recorded information on each software project can be output in
182 several different formats, including formatted text, machine-parseable
183 text, and HTML, optionally with the history of releases in Atom feed
184 format.</para>
185 </refsect1>
186 <refsect1>
187 <title>Subcommands</title>
188 <variablelist>
189 <para><command>relmon</command> has the following subcommands:</para>
190 <varlistentry>
191 <term>
192 <command>list</command>
193 </term>
194 <listitem>
195 <para>List version information for each software project in the
196 statefile in a tabular form and/or the history of releases in the
197 specified output format</para>
198 <variablelist>
199 <para>The following options are supported:</para>
200 <varlistentry>
201 <term>
202 <option>-f</option>
203 <replaceable>format</replaceable>
204 </term>
205 <listitem>
206 <para>Emit output in the specified format. Possible values for
207 <replaceable>format</replaceable> are html, atom, parseable
208 and text, the default output format is text. The parseable
209 format consist of one line per software project with four
210 fields seperated by a single tab containing the name,
211 version, timestamp and status. If the atom format is
212 selected, an Atom feed which only contains the history of
213 releases is emitted. Otherwise version information for each
214 software project in the statefile is emitted in a tabular
215 form.
216 </para>
217 </listitem>
218 </varlistentry>
219 <varlistentry>
220 <term>
221 <option>-F</option>
222 <replaceable>url</replaceable>
223 </term>
224 <listitem>
225 <para>If the output format is set to html, add a link to an
226 Atom feed with the specified URL. If the output format is
227 atom, use the specified URL as the URL where the Atom feed is
228 published. This option is mandatory if the atom ouput format
229 is selected.</para>
230 </listitem>
231 </varlistentry>
232 <varlistentry>
233 <term>
234 <option>-H</option>
235 </term>
236 <listitem>
237 <para>Include the history of released versions in the output.
238 If the parseable ouput format was selected, the history is
239 separated with a single blank line from the version
240 information and consists of one line per history entry with
241 three fields seperated by a single tab containing the times,
242 name and version.</para>
243 </listitem>
244 </varlistentry>
245 <varlistentry>
246 <term>
247 <option>-n</option>
248 <replaceable>number_items</replaceable>
249 </term>
250 <listitem>
251 <para>If used in combination with the <option>-H</option>
252 option or if the atom ouput format was selected, limit the
253 output to the specified number of recent history
254 entries.</para>
255 </listitem>
256 </varlistentry>
257 </variablelist>
258 </listitem>
259 </varlistentry>
260 <varlistentry>
261 <term>
262 <command>show</command>
263 </term>
264 <listitem>
265 <para>The <command>show</command> subcommand shows the name, latest
266 version, time of the last update, all known version nubers and
267 links to the corresponding distribution files, any errors
268 encountered during the last update operation, as well as the
269 release history for each specified software project from the
270 specified statefile.</para>
271 </listitem>
272 </varlistentry>
273 <varlistentry>
274 <term>
275 <command>update</command>
276 </term>
277 <listitem>
278 <para>The <command>update</command> subcommand gathers information
279 on all or a specified subset of the software projects specified in
280 the watchlist and updates or creates a new statefile. Before
281 updating the statefile a backup copy is created using the current
282 filename with a <literal>~</literal> suffix added to it.</para>
283 <para>The following options are supported:</para>
284 <variablelist>
285 <varlistentry>
286 <term>
287 <option>-d</option>
288 </term>
289 <listitem>
290 <para>Trace and log all transfers and parsing. This option is
291 used for debugging purposes.</para>
292 </listitem>
293 </varlistentry>
294 <varlistentry>
295 <term>
296 <option>-e</option>
297 </term>
298 <listitem>
299 <para>Only update version information for projects from the
300 watchlist which were not successfully updated during the last
301 update due to errors.</para>
302 </listitem>
303 </varlistentry>
304 <varlistentry>
305 <term>
306 <option>-v</option>
307 </term>
308 <listitem>
309 <para>Increase logging verbosity and log information about each
310 transfer.</para>
311 </listitem>
312 </varlistentry>
313 <varlistentry>
314 <term>
315 <option>-c</option>
316 <replaceable>max_connections</replaceable>
317 </term>
318 <listitem>
319 <para>Limit the number of simultaneous connections to the
320 specified number. The default value is 16.</para>
321 </listitem>
322 </varlistentry>
323 <varlistentry>
324 <term>
325 <option>-C</option>
326 <replaceable>ca_dir</replaceable>
327 </term>
328 <listitem>
329 <para>Verify the validity of TLS certificates using the CA
330 certificates in the specified directory.</para>
331 </listitem>
332 </varlistentry>
333 <varlistentry>
334 <term>
335 <option>-D</option>
336 <replaceable>delay</replaceable>
337 </term>
338 <listitem>
339 <para>Wait at least the specified number of seconds before
340 making subsequent connections to the same host. The default
341 value is 0.</para>
342 </listitem>
343 </varlistentry>
344 <varlistentry>
345 <term>
346 <option>-H</option>
347 <replaceable>max_host_connections</replaceable>
348 </term>
349 <listitem>
350 <para>Limit the number of simultaneous connections to a single
351 host to the specified number. The default value is 4.</para>
352 </listitem>
353 </varlistentry>
354 <varlistentry>
355 <term>
356 <option>-i</option>
357 <replaceable>items</replaceable>
358 </term>
359 <listitem>
360 <para>Update only the specified items. Multiple items can be
361 specifed in the form of a comma-sperated list.</para>
362 </listitem>
363 </varlistentry>
364 <varlistentry>
365 <term>
366 <option>-l</option>
367 <replaceable>logfile</replaceable>
368 </term>
369 <listitem>
370 <para>Log to the specified logfile instead of stderr.</para>
371 </listitem>
372 </varlistentry>
373 <varlistentry>
374 <term>
375 <option>-r</option>
376 <replaceable>retries</replaceable>
377 </term>
378 <listitem>
379 <para>Limit the number of retries in case of connection
380 failures. The default value is 3.</para>
381 </listitem>
382 </varlistentry>
383 <varlistentry>
384 <term>
385 <option>-t</option>
386 <replaceable>min_time</replaceable>
387 </term>
388 <listitem>
389 <para>Only update version information for projects from the
390 watchlist which have not been updated for the specified
391 number of seconds.</para>
392 </listitem>
393 </varlistentry>
394 </variablelist>
395 </listitem>
396 </varlistentry>
397 <varlistentry>
398 <term>
399 <command>help</command>
400 </term>
401 <listitem>
402 <para>The <command>help</command> subcommand displays usage
403 information about the specified subcommand or all subcommands and
404 exits.</para>
405 </listitem>
406 </varlistentry>
407 </variablelist>
408 </refsect1>
409 <refsect1>
410 <title>Examples</title>
411 <example>
412 <title>Updating version information</title>
413 <para>The following command retrieves the version information for the
414 entries in the watchlist <filename>foo.watchlist</filename> and stores
415 the results in the statefile <filename>foo.json</filename> using using
416 up to 100 simultaneous connections and logging all output to
417 <filename>relmon.log</filename>:</para>
418 <screen>
419 $ relmon update -c 100 foo.watchlist foo.json
420 </screen>
421 </example>
422 <example>
423 <title>Conditionally updating version information</title>
424 <para>The following command updates version information in the statefile
425 <filename>bar.json</filename> only for those entries in the watchlist
426 <filename>foo.watchlist</filename> which either have not been updated
427 for at least 48 hours or which could not be sucessfully updated during
428 the last update operation due to errors:</para>
429 <screen>
430 $ relmon update -v -t 172800 -e -l relmon.log watchlist relmon.json
431 </screen>
432 </example>
433 <example>
434 <title>Displaying detailed information on a monitored project</title>
435 <para>The following command displays all recorded information for the
436 monitored project named foo from the statefile
437 <filename>foo.json</filename>:</para>
438 <screen>
439 $ relmon show foo.json baz
440 </screen>
441 </example>
442 <example>
443 <title>Creating a HTML document with the version information on each
444 of the monitored projects</title>
445 <para>The following command sequence creates a HTML document containing a
446 table with the version information of each monitored project as well as
447 an associated Atom feed with the URL
448 <uri>http://example.net/releases.xml</uri> containing the 100 most
449 recently discovered releases from the statefile
450 <filename>foo.json</filename>:</para>
451 <screen>
452 $ relmon list -f html -F 'http://example.net/releases.xml' foo.json > releases.html
453 $ relmon list -f atom -F 'http://example.net/releases.xml' -n 100 foo.json
454 </screen>
455 </example>
456 </refsect1>
457 <refsect1>
458 <title>Exit Status</title>
459 <para>The following exit values are returned:</para>
460 <variablelist>
461 <varlistentry>
462 <term>0</term>
463 <listitem>
464 <para>Command successfully executed.</para>
465 </listitem>
466 </varlistentry>
467 <varlistentry>
468 <term>&gt; 0</term>
469 <listitem>
470 <para>An error has occured.</para>
471 </listitem>
472 </varlistentry>
473 </variablelist>
474 </refsect1>
475 <refsect1>
476 <title>See Also</title>
477 <para><citerefentry><refentrytitle>relmon_format</refentrytitle>
478 <manvolnum>4</manvolnum></citerefentry></para>
479 </refsect1>
480 </refentry>