MIRMON(1)

NAME
Mirmon - OO interface for mirmon objects

SYNOPSIS
  use Mirmon ;

  $m = Mirmon -> new ( [ $path-to-config ] )

  $conf  = $m -> conf  ; # a Mirmon::Conf object
  $state = $m -> state ; # the mirmon state

  for my $url ( keys %$state )
    { $mirror = $state -> { $url } ; # a Mirmon::Mirror object
      $mail = $mirror -> mail ;      # contact address
      $mirror -> age ( time ) ;      # set mirror age
    }

Many class and object methods can be used to get or set attributes :

  $object -> attribute           # get an atttibute
  $object -> attribute ( $attr ) # set an atttibute

Mirmon class methods

new ( [$path] )
    Create a Mirmon object from a config file found in $path, or (by default) in the default list of possible config files. Related objects (config, state) are created and initialised.

verbosity
    Mirmon always reports errors. Normally it only reports changes (inserts/deletes) found in the mirror_list ; in quiet mode, it doesn't. In verbose mode, it reports progress: the startup and finishing of probes.

      Mirmon::verbose ( [ $bool ] ) # get/set verbose
      Mirmon::quiet   ( [ $bool ] ) # get/set quiet
      Mirmon::debug   ( [ $bool ] ) # get/set debug

Mirmon object methods

conf
    Returns Mirmon's Mirmon::Conf object.

state
    Returns a hashref "{ url => mirror, ... }", where url is as specified in the mirror list and mirror is a Mirmon::Mirror object.

regions
    Returns a hashref "{ country_code => country_name, ... }".

config_list
    Returns the list of default locations for config files.

get_dates ( $get )
    Probes all mirrors if $get is "all" ; or a subset if $get is "update".

Mirmon::Conf object methods
A Mirmon::Conf object represents a mirmon conguration. It is normaly created by Mirmon::new(). A specified (or default) config file is read and interpreted.

attribute methods
    For every config file entry, there is an attribute method : web_page, state, countries, mirror_list, probe, project_name, project_url, icons, project_logo, timeout, max_probes, min_poll, max_poll, min_sync, max_sync, list_style, put_histo, randomize, add_slash.

root
    Returns the file name of (the root of) the configuration file(s).

site_url
    Returns a hashref "{ site => url, ... }", as specified in the mirmon config file.

Mirmon::Mirror object methods
A Mirmon::Mirror object represents the last known state of a mirror. It is normaly created by Mirmon::new() from the state file, as specified in the mirmon config file. Mirmon::Mirror objects can be used to probe mirrors.

  attribute methods

url The url as given in the mirror list.

age The mirror's timestamp found by the last successful probe, or 'undef' if no probe was ever successful.

last_status
    The status of the last probe, or 'undef' if the mirror was never probed.

last_ok_probe
    The timestamp of the last successful probe or 'undef' if the mirror was never successfully probed.

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

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 are inserted, if the timestamp is two or more days old (when mirmon hasn't run for more than two days).

last_probe
    The timestamp of the last probe, or 'undef' if the mirror was never probed.

  object methods

mirmon
    Returns the parent Mirmon object.

state_history_time
    Returns the time part of the state_history attribute.

state_history_hist
    Returns the history part of the state_history attribute.

type, site, home
    For an url like ftp://www.some.org/path/to/home, the type is ftp, the site is www.some.org, and home is ftp://www.some.org/.

age_in_days
    Returns the mirror's age (in fractional days), based on the mirror's timestamp as found by the last successful probe ; or based on the length of the state history if no probe was ever successful. Returns 'undef' if the mirror was never probed.

mail
    Returns the mirror's contact address as specified in the mirror list.

region
    Returns the mirror's country code as specified in the mirror list.

start_probe
    Start a probe for the mirror in non-blocking mode ; returns the associated (IO::Handle) file handle. The caller must maintain an association between the handles and the mirror objects.

finish_probe ( $handle )
    Sets the (IO::Handle) $handle to blocking IO ; reads a result from the handle, and updates the state of the mirror.

SEE ALSO
mirmon(1)

AUTHOR
  (c) 2003-2013 Henk P. Penning
  Faculty of Science, Utrecht University
  http://www.staff.science.uu.nl/~penni101/ -- penning@uu.nl
  mirmon-2.8 - Sat Jan 5 15:09:55 2013 ; henkp

NAME
mirmon - monitor the state of mirrors

SYNOPSIS
  mirmon [ -v ] [ -q ] [ -t timeout ] [ -get opt ] [ -c conf ]

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
    With all, probe all sites ; with update, probe a selection of the sites ; see option "max_poll" below.

-c name
    Use config file name. The default list is

      ./mirmon.conf $HOME/.mirmon.conf /usr/pkg/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

•   ./mirmon.conf

•   $HOME/.mirmon.conf

•   /usr/pkg/etc/mirmon.conf

  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 :

    •   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/ user@tux.org ...
          http nl http://apache.cs.uu.nl/dist/ user@cs.uu.nl ...

    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 :

    •   new

        the site appears in the list, but there is no known state

    •   bad

        the last probe of the site was unsuccessful

    •   old

        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 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 :

•   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 ever successful.

•   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 successfully probed.

•   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 probed.

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

INSTALLATION

  general

•   Note: The (empty) state file must exist before mirmon runs.

•   The mirmon repository is here :

      https://svn.science.uu.nl/repos/project.mirmon/trunk/

•   The mirmon tarball is here :

      http://www.staff.science.uu.nl/~penni101/mirmon/mirmon.tar.gz

  installation suggestions
To install and configure mirmon, take the following steps :

•   First, make the webdir :

      cd DOCUMENTROOT
      mkdir mirmon

    For DOCUMENTROOT, substitute the full pathname of the document root of your webserver.

•   Check out the mirmon repository :

      cd /usr/local/src
      svn checkout REPO mirmon

    where

      REPO = https://svn.science.uu.nl/repos/project.mirmon/trunk/

    or download the package and unpack it.

•   Chdir to directory mirmon :

      cd mirmon

•   Create the (empty) state file :

      touch state.txt

•   Install the icons in the webdir :

      mkdir DOCUMENTROOT/mirmon/icons
      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/ contact@cs.uu.nl
      uk http://mirrors.this.org/your-project/ mirrors@this.org
      us http://mirrors.that.org/your-project/ mirrors@that.org

    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
      project_name ....
      project_url  ....
      mirror_list mirror_list
      state state.txt
      countries countries.list
      web_page DOCUMENTROOT/mirmon/index.html
      icons /mirmon/icons
      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'

      http://www.your.project.org/mirmon/

•   If/when, at a later date, you want to upgrade mirmon :

      cd /usr/local/src/mirmon
      svn status -u
      svn up

SEE ALSO
mirmon.pm(3)

AUTHOR
  (c) 2003-2013 Henk P. Penning
  Faculty of Science, Utrecht University
  http://www.staff.science.uu.nl/~penni101/ -- penning@uu.nl
  mirmon-2.8 - Sat Jan 5 15:09:55 2013 ; henkp