code.guido-berhoerster.org Contact

relmon(1) Manual Page

Back to relmon

Name

relmon — monitor websites of software projects for releases

Synopsis

relmon list [ -H ] [ -f html | parseable | text ] [ -F url ] [ -n number_items ] statefile

relmon list -f atom -F url [ -n number_items ] statefile

relmon show statefile name ...

relmon update [ -d ] [ -e ] [ -v ] [ -c max_connections ] [ -C ca_dir ] [ -D delay ] [ -H max_host_connections ] [-i item [,...] ] [ -l logfile ] [ -r retries ] [ -t min_time ] watchlist statefile

relmon discover [ -d ] [ -c max_connections ] [ -C ca_dir ] [ -D delay ] [ -H max_host_connections ] [ -r retries ] [ -t min_time ] base_url [ pattern ]

relmon help [ subcommand ]

Description

relmon 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.

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 relmon_watchlist(4) for the exact format of watchlist entries and further details on the operation of relmon. 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. relmon 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.

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.

Subcommands

relmon has the following subcommands:

list

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

The following options are supported:

-f format

Emit output in the specified format. Possible values for format 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.

-F url

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.

-H

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.

-n number_items

If used in combination with the -H option or if the atom ouput format was selected, limit the output to the specified number of recent history entries.

show

The show 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.

update

The update 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 ~ suffix added to it.

The following options are supported:

-d

Trace and log all transfers and parsing. This option is used for debugging purposes.

-e

Only update version information for projects from the watchlist which were not successfully updated during the last update due to errors.

-v

Increase logging verbosity and log information about each transfer.

-c max_connections

Limit the number of simultaneous connections to the specified number. The default value is 16.

-C ca_dir

Verify the validity of TLS certificates using the CA certificates in the specified directory.

-D delay

Wait at least the specified number of seconds before making subsequent connections to the same host. The default value is 0.

-H max_host_connections

Limit the number of simultaneous connections to a single host to the specified number. The default value is 4.

-i items

Update only the specified items. Multiple items can be specifed in the form of a comma-sperated list.

-l logfile

Log to the specified logfile instead of stderr.

-r retries

Limit the number of retries in case of connection failures. The default value is 3.

-t min_time

Only update version information for projects from the watchlist which have not been updated for the specified number of seconds.

discover

The discover subcommand assists with the creation of watchlist entries. The arguments to the discover subcommand correspond to the fields of a watchlist entry without the name field, see relmon_format(4) for details on the format. Only the base_url is mandatory and relmon 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.

The following options are supported:

-d

Trace and log all transfers and parsing. This option is used for debugging purposes.

-c max_connections

Limit the number of simultaneous connections to the specified number.

-C ca_dir

Verify the validity of TLS certificates using the CA certificates in the specified directory.

-D delay

Wait at least the specified number of seconds before making subsequent connections to the same host.

-H max_host_connections

Limit the number of simultaneous connections to a single host to the specified number.

-r retries

Limit the number of retries in case of connection failures.

-t min_time

Only update version information for projects from the watchlist which have not been updated for the specified number of seconds.

help

The help subcommand displays usage information about the specified subcommand or all subcommands and exits.

Examples

Example 1. Creating a new watchlist entry

The following command displays all links found in the HTML document at http://example.net/foo/:

$ relmon discover http://example.net/foo/

The following command tests whether the specified version-matching regular expression matches the distribution file linked from http://example.net/foo/:

$ relmon discover http://example.net/foo/ '/foo-([[:digit:].]+)\.tar\.gz'

Example 2. Updating version information

The following command retrieves the version information for the entries in the watchlist foo.watchlist and stores the results in the statefile foo.json using using up to 100 simultaneous connections and logging all output to relmon.log:

$ relmon update -c 100 foo.watchlist foo.json

Example 3. Conditionally updating version information

The following command updates version information in the statefile bar.json only for those entries in the watchlist foo.watchlist 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:

$ relmon update -v -t 172800 -e -l relmon.log watchlist relmon.json

Example 4. Displaying detailed information on a monitored project

The following command displays all recorded information for the monitored project named foo from the statefile foo.json:

$ relmon show foo.json baz

Example 5. Creating a HTML document with the version information on each of the monitored projects

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 http://example.net/releases.xml containing the 100 most recently discovered releases from the statefile foo.json:

$ 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

Exit Status

The following exit values are returned:

0

Command successfully executed.

> 0

An error has occured.

See Also

relmon_format(4)