Poster of Linux kernelThe best gift for a Linux geek
MIRMON

MIRMON

Section: User Contributed Perl Documentation (1) Updated: 2010-05-11
Local index Up
 

NAME

  mirmon - monitor the state of mirrors

 

SYNOPSIS

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

 

OPTIONS

  option v   : be verbose
  option q   : be quiet
  option t   : set timeout [ default 300 ] ;
  option get : 'all'    : probe all sites
             : 'update' : probe a selection of the sites (see doc)
  option c   : configuration file ; default list :
               ./mirmon.conf $HOME/.mirmon.conf /etc/mirmon.conf
  -------------------------------------------------------------------
  Documentation : the program contains 'pod' style documentation.
  Extract the doc with 'pod2text mirmon' or 'pod2html mirmon OUT', etc.
  -------------------------------------------------------------------

 

USAGE

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

    42 * * * * perl /path/to/mirmon -q -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\n",
  that is, a timestamp followed by a newline. 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
  -- /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
    +--------------------------------------------------

 

CONFIG FILE : 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.
  Two formats are supported :

  -- plain : lines like

       us http://www.tux.org/
       nl http://apache.cs.uu.nl/dist/

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

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

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

 

web_page <file name>

  Specify where the html report page is written.

 

icons <directory name>

  Specify the directory where the icons can be found.

 

probe <program + arguments>

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

    probe /sw/bin/wget -q -O - -T %TIMEOUT% -t 1 %URL%TIME

  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, for instance with
  a crontab entry like
  
    42 * * * * perl -e 'printf "%s\n", time' > /path/to/archive/TIME

  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

 

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.

 

CONFIG FILE : 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.
  The supplied text is placed between <P> and </P>.

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

 

no_randomize

  With a low probablility, mirmon probes mirrors that would
  otherwise not be probed. In the long run, this balances
  the number of mirror probes over the hourly mirmon runs.
  Specifically, if there are N mirrors in the list and some
  mirmon run would probe K sites, on average (N-K)/N extra
  sites will be probed.

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

 

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 age of the site, or 'undef' if no probe was ever successful.

 

field 3 : status last probe

  The status of the last probe.

 

field 4 : time last successful probe

  The timestamp of the last successful probe or 'undef'
  if the site 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 site 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)
  or 'z' (bad). The timestamp indicates when the state history was last
  updated. The state history is updated when the state file is updated
  and the last update of the history state was 24 (or more) hours ago.
  The status is determined by the site's age and a few configuration
  parameters. The details are explained in the legend of the report page.

 

field 7 : last probe

  The timestamp of the last probe.

 

INSTALLATION

  The '#!' path for perl is probably wrong.

 

AUTHOR


 

Index

NAME
SYNOPSIS
OPTIONS
USAGE
CONFIG FILE
location
syntax
CONFIG FILE : required entries
project_name <name>
project_url <url>
mirror_list <file name>
web_page <file name>
icons <directory name>
probe <program + arguments>
state <file name>
countries <file name>
CONFIG FILE : optional entries
max_probes <number>
timeout <seconds>
project_logo <logo>
htm_head <html>
htm_top <html>
htm_foot <html>
put_histo top|bottom|nowhere
min_poll <time spec>
max_poll <time spec>
min_sync <time spec>
max_sync <time spec>
no_randomize
list_style plain|apache
site_url <site> <url>
env <key> <value>
include <file name>
show
exit
STATE FILE FORMAT
field 1 : url
field 2 : age
field 3 : status last probe
field 4 : time last successful probe
field 5 : probe history
field 6 : state history
field 7 : last probe
INSTALLATION
AUTHOR

This document was created by man2html, using the manual pages.
Time: 21:23:54 GMT, April 16, 2011