This is the command mirmon that can be run in the OnWorks free hosting provider using one of our multiple free online workstations such as Ubuntu Online, Fedora Online, Windows online emulator or MAC OS online emulator
mirmon - monitor the state of mirrors
mirmon [-v] [-q] [-t timeout] [-c conf] [-get all|update|url url]
-v Be verbose ; mirmon normally only reports errors and changes in the mirror list.
-q Be quiet.
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
Use config file name. The default list is
./mirmon.conf $HOME/.mirmon.conf /etc/mirmon.conf
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
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
that is, a line of text starting with a timestamp. The exit status of the probe is
A config file can be specified with the -c option. If -c is not used, the program looks
for a config file in
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'
|# lines starting with a '+' are concatenated
|# the next three lines mean 'somekey part1part2part3'
|# 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"
Specify a short plaintext name for the project.
Specify an url pointing to the 'home' of the project.
Specify the file containing the mirrors to probe.
If your mirror list is generated by a program, use
mirror_list /path/to/program arg1 ... |
Two formats are supported :
· plain : lines like
us http://www.tux.org/ [email] ...
nl http://apache.cs.uu.nl/dist/ [email] ...
nl rsync://archive.cs.uu.nl/apache-dist/ [email] ...
· apache : lines like those in the apache mirrors.list
ftp us ftp://ftp.tux.org/pub/net/apache/dist/ [email protected] ...
http nl http://apache.cs.uu.nl/dist/ [email protected] ...
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
Specify where the html report page is written.
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
If/when the icons live in "/path/to/DOCUMENTROOT/icons/mirmon/", specify
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 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.
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).
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.
Optionally specify the number of parallel probes (default 25).
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.
Optionally specify (the SRC of the IMG of) a logo to be placed top right on the page.
Optionally specify some HTML to be placed before </HEAD>.
<link REL=StyleSheet HREF="/style.css" TYPE="text/css">
Optionally specify some HTML to be placed near the top of the page.
htm_top testing 1, 2, 3
Optionally specify HTML to be placed near the bottom of the page.
<A HREF="..."><IMG SRC="..." BORDER=0></A>
Optionally specify where the age histogram must be placed. The default is 'top'.
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).
Optionally specify the maximum probe interval. When the program is called with option
'-get update', all sites are probed which are :
the site appears in the list, but there is no known state
the last probe of the site was unsuccessful
the last probe was more than 'max_poll' ago.
Sites are not probed if the last probe was less than 'min_poll' ago. So, if you
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).
Optionally specify how often the mirrors are required to make an update.
The default 'min_sync' is '1d' (1 day).
Optionally specify the maximum allowable sync interval.
Sites exceeding the limit will be considered 'old'. The default 'max_sync' is '2d' (2
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.
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.
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.
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.
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.
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
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 :
· field 1 : url
The url as given in the mirror list.
· field 2 : age
The mirror's timestamp found by the last successful probe, or 'undef' if no probe was
· field 3 : status last probe
The status of the last probe, or 'undef' if the mirror was never probed.
· field 4 : time last successful probe
The timestamp of the last successful probe or 'undef' if the mirror was never
· field 5 : probe history
The probe history is a list of 's' (for success) and 'f' (for failure) characters
indicating the result of the probe. New results are appended whenever the mirror is
· field 6 : state history
The state history consists of a timestamp, a '-' char, and a list of chars indicating
a past status: 's' (fresh), 'b' (oldish), 'f' (old), 'z' (bad) or 'x' (skip). The
timestamp indicates when the state history was last updated. The current status of
the mirror is determined by the mirror's age and a few configuration parameters
(min_sync, max_sync, max_poll). The state history is updated when the mirror is
probed. If the last update of the history was less than 24 hours ago, the last status
is replaced by the current status. If the last update of the history was more than 24
hours ago, the current status is appended to the history. One or more 'skip's is
inserted, if the timestamp is two or more days old (when mirmon hasn't run for more
than two days).
· field 7 : last probe
The timestamp of the last probe, or 'undef' if the mirror was never probed.
· Note: The (empty) state file must exist before mirmon runs.
· The mirmon repository is here :
· The mirmon tarball is here :
To install and configure mirmon, take the following steps :
· First, make the webdir :
For DOCUMENTROOT, substitute the full pathname of the document root of your webserver.
· Check out the mirmon repository :
svn checkout REPO mirmon
REPO = https://svn.science.uu.nl/repos/project.mirmon/trunk/
or download the package and unpack it.
· Chdir to directory mirmon :
· Create the (empty) state file :
· Install the icons in the webdir :
cp icons/* DOCUMENTROOT/mirmon/icons
· Create a mirror list "mirror_list" ;
Use your favorite editor, or genererate the list from an existing database.
nl http://archive.cs.uu.nl/your-project/ [email protected]
uk http://mirrors.this.org/your-project/ [email protected]
us http://mirrors.that.org/your-project/ [email protected]
The email addresses are optional.
· Create a mirmon config file "mirmon.conf" with your favorite editor.
# lines must start in the first column ; no leading white space
probe /usr/bin/wget -q -O - -T %TIMEOUT% -t 1 %URL%TIME.txt
This assumes the project's timestamp is in file "TIME.txt".
· If you have rsync urls, change the probe line to :
probe perl /usr/local/src/mirmon/probe -t %TIMEOUT% %URL%TIME.txt
· Run mirmon :
perl mirmon -v -get all
The mirmon report should now be in 'DOCUMENTROOT/mirmon/index.html'
· If/when, at a later date, you want to upgrade mirmon :
svn status -u
Use mirmon online using onworks.net services