Mercurial > projects > relmon
view relmon.1.xml @ 9:4ecf1408f04f default tip
Exclude "." from tarballs
author | Guido Berhoerster <guido+relmon@berhoerster.name> |
---|---|
date | Tue, 13 Sep 2016 18:21:47 +0200 |
parents | 86a0c5d11f05 |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) 2014 Guido Berhoerster <guido+relmon@berhoerster.name> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. --> <refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en"> <info> <author> <personname> <firstname>Guido</firstname> <surname>Berhoerster</surname> </personname> <email>guido+relmon@berhoerster.name</email> <personblurb/> </author> <date>24 October, 2014</date> </info> <refmeta> <refentrytitle>relmon</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class="source"/> <refmiscinfo class="version"/> <refmiscinfo class="manual">User Commands</refmiscinfo> </refmeta> <refnamediv> <refname>relmon</refname> <refpurpose>monitor websites of software projects for releases</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>relmon list</command> <arg choice="opt"> <option>-H</option> </arg> <arg choice="opt"> <option>-f</option> <group choice="plain"> <arg choice="plain">html</arg> <arg choice="plain">parseable</arg> <arg choice="plain">text</arg> </group> </arg> <arg choice="opt"> <option>-F</option> <replaceable>url</replaceable> </arg> <arg choice="opt"> <option>-n</option> <replaceable>number_items</replaceable> </arg> <arg choice="plain"> <replaceable>statefile</replaceable> </arg> </cmdsynopsis> <cmdsynopsis> <command>relmon list</command> <arg choice="plain"> <option>-f</option> <arg choice="plain">atom</arg> </arg> <arg choice="plain"> <option>-F</option> <arg choice="plain">url</arg> </arg> <arg choice="opt"> <option>-n</option> <replaceable>number_items</replaceable> </arg> <arg choice="plain"> <replaceable>statefile</replaceable> </arg> </cmdsynopsis> <cmdsynopsis> <command>relmon show</command> <arg choice="plain"> <replaceable>statefile</replaceable> </arg> <arg choice="plain" rep="repeat"> <replaceable>name</replaceable> </arg> </cmdsynopsis> <cmdsynopsis> <command>relmon update</command> <arg choice="opt"> <option>-d</option> </arg> <arg choice="opt"> <option>-e</option> </arg> <arg choice="opt"> <option>-v</option> </arg> <arg choice="opt"> <option>-c</option> <replaceable>max_connections</replaceable> </arg> <arg choice="opt"> <option>-C</option> <replaceable>ca_dir</replaceable> </arg> <arg choice="opt"> <option>-D</option> <replaceable>delay</replaceable> </arg> <arg choice="opt"> <option>-H</option> <replaceable>max_host_connections</replaceable> </arg> <arg choice="opt"><option>-i</option> <arg choice="plain"><replaceable>item</replaceable></arg> <arg choice="opt" rep="repeat"><replaceable>,</replaceable></arg> </arg> <arg choice="opt"> <option>-l</option> <replaceable>logfile</replaceable> </arg> <arg choice="opt"> <option>-r</option> <replaceable>retries</replaceable> </arg> <arg choice="opt"> <option>-t</option> <replaceable>min_time</replaceable> </arg> <arg choice="plain"> <replaceable>watchlist</replaceable> </arg> <arg choice="plain"> <replaceable>statefile</replaceable> </arg> </cmdsynopsis> <cmdsynopsis> <command>relmon discover</command> <arg choice="opt"> <option>-d</option> </arg> <arg choice="opt"> <option>-c</option> <replaceable>max_connections</replaceable> </arg> <arg choice="opt"> <option>-C</option> <replaceable>ca_dir</replaceable> </arg> <arg choice="opt"> <option>-D</option> <replaceable>delay</replaceable> </arg> <arg choice="opt"> <option>-H</option> <replaceable>max_host_connections</replaceable> </arg> <arg choice="opt"> <option>-r</option> <replaceable>retries</replaceable> </arg> <arg choice="opt"> <option>-t</option> <replaceable>min_time</replaceable> </arg> <arg choice="plain"> <replaceable>base_url</replaceable> </arg> <arg choice="opt"> <replaceable>pattern</replaceable> </arg> </cmdsynopsis> <cmdsynopsis> <command>relmon help</command> <arg choice="opt"> <replaceable>subcommand</replaceable> </arg> </cmdsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> <para><command>relmon</command> is a utility for monitoring websites of software projects for new releases. It can crawl websites via HTTP or HTTPS using a configurable number of simultaneous connections and parse HTML and XHTML documents as well as RSS 2.0 and Atom feeds. Software releases are detected by extracting the version numbers from links to distribution files from the parsed documents or feeds and comparing them to previously extracted version numbers.</para> <para>The crawling of the website of a software projects and the extraction of version numbers are controlled by an entry with directions in a watchlist file, see <citerefentry><refentrytitle>relmon_watchlist</refentrytitle> <manvolnum>4</manvolnum></citerefentry> for the exact format of watchlist entries and further details on the operation of <command>relmon</command>. In addition to the version numbers, the history of releases consisting of the times new release were initially discovered, any encountered errors and the time the version information was last updated are recorded in a statefile. <command>relmon</command> can selectively update explicitly specified items or on the basis of the time an item was last updated or whether any errors were encountered during the previous update of an item.</para> <para>The recorded information on each software project can be output in several different formats, including formatted text, machine-parseable text, and HTML, optionally with the history of releases in Atom feed format.</para> </refsect1> <refsect1> <title>Subcommands</title> <variablelist> <para><command>relmon</command> has the following subcommands:</para> <varlistentry> <term> <command>list</command> </term> <listitem> <para>List version information for each software project in the statefile in a tabular form and/or the history of releases in the specified output format</para> <variablelist> <para>The following options are supported:</para> <varlistentry> <term> <option>-f</option> <replaceable>format</replaceable> </term> <listitem> <para>Emit output in the specified format. Possible values for <replaceable>format</replaceable> are html, atom, parseable and text, the default output format is text. The parseable format consist of one line per software project with four fields seperated by a single tab containing the name, version, timestamp and status. If the atom format is selected, an Atom feed which only contains the history of releases is emitted. Otherwise version information for each software project in the statefile is emitted in a tabular form. </para> </listitem> </varlistentry> <varlistentry> <term> <option>-F</option> <replaceable>url</replaceable> </term> <listitem> <para>If the output format is set to html, add a link to an Atom feed with the specified URL. If the output format is atom, use the specified URL as the URL where the Atom feed is published. This option is mandatory if the atom ouput format is selected.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-H</option> </term> <listitem> <para>Include the history of released versions in the output. If the parseable ouput format was selected, the history is separated with a single blank line from the version information and consists of one line per history entry with three fields seperated by a single tab containing the times, name and version.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-n</option> <replaceable>number_items</replaceable> </term> <listitem> <para>If used in combination with the <option>-H</option> option or if the atom ouput format was selected, limit the output to the specified number of recent history entries.</para> </listitem> </varlistentry> </variablelist> </listitem> </varlistentry> <varlistentry> <term> <command>show</command> </term> <listitem> <para>The <command>show</command> subcommand shows the name, latest version, time of the last update, all known version nubers and links to the corresponding distribution files, any errors encountered during the last update operation, as well as the release history for each specified software project from the specified statefile.</para> </listitem> </varlistentry> <varlistentry> <term> <command>update</command> </term> <listitem> <para>The <command>update</command> subcommand gathers information on all or a specified subset of the software projects specified in the watchlist and updates or creates a new statefile. Before updating the statefile a backup copy is created using the current filename with a <literal>~</literal> suffix added to it.</para> <para>The following options are supported:</para> <variablelist> <varlistentry> <term> <option>-d</option> </term> <listitem> <para>Trace and log all transfers and parsing. This option is used for debugging purposes.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-e</option> </term> <listitem> <para>Only update version information for projects from the watchlist which were not successfully updated during the last update due to errors.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-v</option> </term> <listitem> <para>Increase logging verbosity and log information about each transfer.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-c</option> <replaceable>max_connections</replaceable> </term> <listitem> <para>Limit the number of simultaneous connections to the specified number. The default value is 16.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-C</option> <replaceable>ca_dir</replaceable> </term> <listitem> <para>Verify the validity of TLS certificates using the CA certificates in the specified directory.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-D</option> <replaceable>delay</replaceable> </term> <listitem> <para>Wait at least the specified number of seconds before making subsequent connections to the same host. The default value is 0.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-H</option> <replaceable>max_host_connections</replaceable> </term> <listitem> <para>Limit the number of simultaneous connections to a single host to the specified number. The default value is 4.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-i</option> <replaceable>items</replaceable> </term> <listitem> <para>Update only the specified items. Multiple items can be specifed in the form of a comma-sperated list.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-l</option> <replaceable>logfile</replaceable> </term> <listitem> <para>Log to the specified logfile instead of stderr.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-r</option> <replaceable>retries</replaceable> </term> <listitem> <para>Limit the number of retries in case of connection failures. The default value is 3.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-t</option> <replaceable>min_time</replaceable> </term> <listitem> <para>Only update version information for projects from the watchlist which have not been updated for the specified number of seconds.</para> </listitem> </varlistentry> </variablelist> </listitem> </varlistentry> <varlistentry> <term> <command>discover</command> </term> <listitem> <para>The <command>discover</command> subcommand assists with the creation of watchlist entries. The arguments to the <command>discover</command> subcommand correspond to the fields of a watchlist entry without the name field, see <citerefentry><refentrytitle>relmon_format</refentrytitle> <manvolnum>4</manvolnum></citerefentry> for details on the format. Only the <replaceable>base_url</replaceable> is mandatory and <command>relmon</command> will log all matching and non-matching links of each retrieved document or feed so that each step of an update operation for a watchlist entry can be reproduced.</para> <para>The following options are supported:</para> <variablelist> <varlistentry> <term> <option>-d</option> </term> <listitem> <para>Trace and log all transfers and parsing. This option is used for debugging purposes.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-c</option> <replaceable>max_connections</replaceable> </term> <listitem> <para>Limit the number of simultaneous connections to the specified number.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-C</option> <replaceable>ca_dir</replaceable> </term> <listitem> <para>Verify the validity of TLS certificates using the CA certificates in the specified directory.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-D</option> <replaceable>delay</replaceable> </term> <listitem> <para>Wait at least the specified number of seconds before making subsequent connections to the same host.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-H</option> <replaceable>max_host_connections</replaceable> </term> <listitem> <para>Limit the number of simultaneous connections to a single host to the specified number.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-r</option> <replaceable>retries</replaceable> </term> <listitem> <para>Limit the number of retries in case of connection failures.</para> </listitem> </varlistentry> <varlistentry> <term> <option>-t</option> <replaceable>min_time</replaceable> </term> <listitem> <para>Only update version information for projects from the watchlist which have not been updated for the specified number of seconds.</para> </listitem> </varlistentry> </variablelist> </listitem> </varlistentry> <varlistentry> <term> <command>help</command> </term> <listitem> <para>The <command>help</command> subcommand displays usage information about the specified subcommand or all subcommands and exits.</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Examples</title> <example> <title>Creating a new watchlist entry</title> <para>The following command displays all links found in the HTML document at <uri>http://example.net/foo/</uri>:</para> <screen> $ relmon discover http://example.net/foo/ </screen> <para>The following command tests whether the specified version-matching regular expression matches the distribution file linked from <uri>http://example.net/foo/</uri>:</para> <screen> $ relmon discover http://example.net/foo/ '/foo-([[:digit:].]+)\.tar\.gz' </screen> </example> <example> <title>Updating version information</title> <para>The following command retrieves the version information for the entries in the watchlist <filename>foo.watchlist</filename> and stores the results in the statefile <filename>foo.json</filename> using using up to 100 simultaneous connections and logging all output to <filename>relmon.log</filename>:</para> <screen> $ relmon update -c 100 foo.watchlist foo.json </screen> </example> <example> <title>Conditionally updating version information</title> <para>The following command updates version information in the statefile <filename>bar.json</filename> only for those entries in the watchlist <filename>foo.watchlist</filename> which either have not been updated for at least 48 hours or which could not be sucessfully updated during the last update operation due to errors:</para> <screen> $ relmon update -v -t 172800 -e -l relmon.log watchlist relmon.json </screen> </example> <example> <title>Displaying detailed information on a monitored project</title> <para>The following command displays all recorded information for the monitored project named foo from the statefile <filename>foo.json</filename>:</para> <screen> $ relmon show foo.json baz </screen> </example> <example> <title>Creating a HTML document with the version information on each of the monitored projects</title> <para>The following command sequence creates a HTML document containing a table with the version information of each monitored project as well as an associated Atom feed with the URL <uri>http://example.net/releases.xml</uri> containing the 100 most recently discovered releases from the statefile <filename>foo.json</filename>:</para> <screen> $ relmon list -f html -F 'http://example.net/releases.xml' foo.json > releases.html $ relmon list -f atom -F 'http://example.net/releases.xml' -n 100 foo.json </screen> </example> </refsect1> <refsect1> <title>Exit Status</title> <para>The following exit values are returned:</para> <variablelist> <varlistentry> <term>0</term> <listitem> <para>Command successfully executed.</para> </listitem> </varlistentry> <varlistentry> <term>> 0</term> <listitem> <para>An error has occured.</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>See Also</title> <para><citerefentry><refentrytitle>relmon_format</refentrytitle> <manvolnum>4</manvolnum></citerefentry></para> </refsect1> </refentry>