<?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>&gt; 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>