NAME

mirmon - monitor the state of mirrors


SYNOPSIS

  mirmon [-v] [-q] [-t timeout] [-c conf] [-get all|update|url url]


OPTIONS

-v

Be verbose ; mirmon normally only reports errors and changes in the mirror list.

-q

Be quiet.

-t timeout

Set the timeout ; the default is 300.

-get all | update | url <url>

With all, probe all sites. With update, probe a selection of the sites ; see option max_poll below. With url, probe only the given url, which must appear in the mirror-list.

-c name

Use config file name. The default list is

  ./mirmon.conf $HOME/.mirmon.conf /etc/mirmon.conf


USAGE

The program is intended to be run by cron every hour.

  42 * * * * perl /path/to/mirmon -get update

It quietly probes a subset of the sites in a given list, writes the results in the 'state' file and generates a web page with the results. The subset contains the sites that are new, bad and/or not probed for a specified time.

When no 'get' option is specified, the program just generates a new web page from the last known state.

The program checks the mirrors by running a (user specified) program on a pipe. A (user specified) number of probes is run in parallel using nonblocking IO. When something can be read from the pipe, it switches the pipe to blocking IO and reads one line from the pipe. Then it flushes and closes the pipe. No attempt is made to kill the probe.

The probe should return something that looks like

  1043625600 ...

that is, a line of text starting with a timestamp. The exit status of the probe is ignored.


CONFIG FILE

location

A config file can be specified with the -c option. If -c is not used, the program looks for a config file in

syntax

A config file looks like this :

  +--------------------------------------------------
  |# lines that start with '#' are comment
  |# blank lines are ignored too
  |# tabs are replaced by a space
  |
  |# the config entries are 'key' and 'value' pairs
  |# a 'key' begins in column 1
  |# the 'value' is the rest of the line
  |somekey  A_val B_val ...
  |otherkey X_val Y_val ...
  |
  |# indented lines are glued
  |# the next three lines mean 'somekey part1 part2 part3'
  |somekey part1
  |  part2
  |  part3
  |
  |# lines starting with a '+' are concatenated
  |# the next three lines mean 'somekey part1part2part3'
  |somekey part1
  |+ part2
  |+ part3
  |
  |# lines starting with a '.' are glued too
  |# don't use a '.' on a line by itself
  |# 'somekey' gets the value "part1\n part2\n part3"
  |somekey part1
  |. part2
  |. part3
  +--------------------------------------------------

required entries

project_name name

Specify a short plaintext name for the project.

  project_name Apache
  project_name CTAN
project_url url

Specify an url pointing to the 'home' of the project.

  project_url http://www.apache.org/
mirror_list file-name

Specify the file containing the mirrors to probe.

  mirror_list /path/to/mirror-list

If your mirror list is generated by a program, use

  mirror_list /path/to/program arg1 ... |

Two formats are supported :

Note that in style 'plain' the third item is reserved for an optional email address : the site's contact address.

Specify the required format with option list_style (see below). The default style is 'plain'.

web_page file-name

Specify where the html report page is written.

icons directory-name

Specify the directory where the icons can be found, relative to the web_page, or relative to the DOCUMENTROOT of the web server.

If/when the web_page lives in directory .../mirmon/ and the icons live in directory .../mirmon/icons/, specify

  icons icons

If/when the icons live in /path/to/DOCUMENTROOT/icons/mirmon/, specify

  icons /icons/mirmon
probe program + arguments

Specify the program+args to probe the mirrors. Example:

  probe /usr/bin/wget -q -O - -T %TIMEOUT% -t 1 %URL%TIME.txt

Before the program is started, %TIMEOUT% and %URL% are substituted with the proper timeout and url values.

Here it is assumed that each hour the root server writes a timestamp in /path/to/archive/TIME.txt, for instance with a crontab entry like

  42 * * * * perl -e 'print time, "\n"' > /path/to/archive/TIME.txt

Mirmon reads one line of output from the probe and interprets the first word on that line as a timestamp ; for example :

  1043625600
  1043625600 Mon Jan 27 00:00:00 2003
  1043625600 www.apache.org Mon Jan 27 00:00:00 2003

Mirmon is distributed with a program probe that handles ftp, http and rsync urls.

state file-name

Specify where the file containing the state is written.

The program reads this file on startup and writes the file when mirrors are probed (-get is specified).

countries file-name

Specify the file containing the country codes; The file should contain lines like

  us - United States
  nl - Netherlands

The mirmon package contains a recent ISO list.

Fake domains like Backup, Master are allowed, and are listed first in the report ; lowercase-first fake domains (like backup) are listed last.

optional entries

max_probes number

Optionally specify the number of parallel probes (default 25).

timeout seconds

Optionally specify the timeout for the probes (default 300).

After the last probe is started, the program waits for <timeout> + 10 seconds, cleans up and exits.

project_logo logo

Optionally specify (the SRC of the IMG of) a logo to be placed top right on the page.

  project_logo /icons/apache.gif
  project_logo http://www.apache.org/icons/...
htm_head html

Optionally specify some HTML to be placed before </HEAD>.

  htm_head
    <link REL=StyleSheet HREF="/style.css" TYPE="text/css">
htm_top html

Optionally specify some HTML to be placed near the top of the page.

  htm_top testing 1, 2, 3
htm_foot html

Optionally specify HTML to be placed near the bottom of the page.

  htm_foot
    <HR>
    <A HREF="..."><IMG SRC="..." BORDER=0></A>
    <HR>
put_histo top|bottom|nowhere

Optionally specify where the age histogram must be placed. The default is 'top'.

min_poll time-spec

For 'min_poll' see next item. A time-spec is a number followed by a unit 's' (seconds), or 'm' (minutes), or 'h' (hours), or 'd' (days). For example '3d' (three days) or '36h' (36 hours).

max_poll time-spec

Optionally specify the maximum probe interval. When the program is called with option '-get update', all sites are probed which are :

Sites are not probed if the last probe was less than 'min_poll' ago. So, if you specify

  min_poll 4h
  max_poll 12h

the 'reachable' sites are probed twice daily and the 'unreachable' sites are probed at most six times a day.

The default 'min_poll' is '1h' (1 hour). The default 'max_poll' is '4h' (4 hours).

min_sync time-spec

Optionally specify how often the mirrors are required to make an update.

The default 'min_sync' is '1d' (1 day).

max_sync time-spec

Optionally specify the maximum allowable sync interval.

Sites exceeding the limit will be considered 'old'. The default 'max_sync' is '2d' (2 days).

always_get region ...

Optionally specify a list of regions that must be probed always.

  always_get Master Tier1

This is intended for fake regions like Master etc.

no_randomize

Mirmon tries to balance the probe load over the hourly mirmon runs. If the current run has a below average number of mirrors to probe, mirmon probes a few extra, randomly chosen mirrors, picked from the runs that have the highest load.

If you don't want this behaviour, use no_randomize.

no_add_slash

If the url part of a line in the mirror_list doesn't end in a slash ('/'), mirmon adds a slash and issues a warning unless it is in quiet mode.

If you don't want this behaviour, use no_add_slash.

list_style plain|apache

Optionally specify the format ('plain' or 'apache') of the mirror-list.

See the description of 'mirror_list' above. The default list_style is 'plain'.

site_url site url

Optionally specify a substitute url for a site.

When access to a site is restricted (in Australia, for instance), another (sometimes secret) url can be used to probe the site. The <site> of an url is the part between '://' and the first '/'.

env key value

Optionally specify an environment variable.

include file-name

Optionally specify a file to include.

The specified file is processed 'in situ'. After the specified file is read and processed, config processing is resumed in the file where the include was encountered. The include depth is unlimited. However, it is a fatal error to include a file twice under the same name.

show

When the config processor encounters the 'show' command, it dumps the content of the current config to standout, if option -v is specified. This is intented for debugging.

exit

When the config processor encounters the 'exit' command, it terminates the program. This is intented for debugging.


STATE FILE FORMAT

The state file consists of lines; one line per site. Each line consists of white space separated fields. The seven fields are :


INSTALLATION

general

installation suggestions

To install and configure mirmon, take the following steps :


SEE ALSO

mirmon.pm(3)


AUTHOR

© 2003-2014 Henk P. Penning, Faculty of Science, Utrecht University
mirmon-2.10 - Fri Aug 15 12:26:55 2014 ; henkp ; verify html