MIRMON(1)            User Contributed Perl Documentation            MIRMON(1)



NNAAMMEE
       mirmon - monitor the state of mirrors

SSYYNNOOPPSSIISS
         mirmon [ -v ] [ -q ] [ -t timeout ] [ -get opt ] [ -c conf ]

OOPPTTIIOONNSS
       --vv  Be verbose ; mmiirrmmoonn normally only reports errors and changes in
           the mirror list.

       --qq  Be quiet.

       --tt _t_i_m_e_o_u_t
           Set the timeout ; the default is _3_0_0.

       --ggeett _a_l_l | _u_p_d_a_t_e
           With _a_l_l, probe all sites ; with _u_p_d_a_t_e, probe a selection of the
           sites ; see option "max_poll" below.

       --cc _n_a_m_e
           Use config file _n_a_m_e. The default list is

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

UUSSAAGGEE
       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.

CCOONNFFIIGG FFIILLEE
   llooccaattiioonn
       A config file can be specified with the -c option.  If -c is not used,
       the program looks for a config file in

       ·   ..//mmiirrmmoonn..ccoonnff

       ·   $$HHOOMMEE//..mmiirrmmoonn..ccoonnff

       ·   //eettcc//mmiirrmmoonn..ccoonnff

   ssyynnttaaxx
       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
         +--------------------------------------------------

   rreeqquuiirreedd eennttrriieess
       project_name _n_a_m_e
           Specify a short plaintext name for the project.

             project_name Apache
             project_name CTAN

       project_url _u_r_l
           Specify an url pointing to the ’home’ of the project.

             project_url http://www.apache.org/

       mirror_list _f_i_l_e_-_n_a_m_e
           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 _f_i_l_e_-_n_a_m_e
           Specify where the html report page is written.

       icons _d_i_r_e_c_t_o_r_y_-_n_a_m_e
           Specify the directory where the icons can be found, relative to
           the _w_e_b___p_a_g_e, or relative to the DOCUMENTROOT of the web server.

           If/when the _w_e_b___p_a_g_e 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 _p_r_o_g_r_a_m _+ _a_r_g_u_m_e_n_t_s
           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 _f_i_l_e_-_n_a_m_e
           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 _f_i_l_e_-_n_a_m_e
           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.

           _F_a_k_e domains like _B_a_c_k_u_p, _M_a_s_t_e_r are allowed, and are listed first
           in the report ; lowercase-first fake domains (like _b_a_c_k_u_p) are
           listed last.

   ooppttiioonnaall eennttrriieess
       max_probes _n_u_m_b_e_r
           Optionally specify the number of parallel probes (default 25).

       timeout _s_e_c_o_n_d_s
           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 _l_o_g_o
           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 _h_t_m_l
           Optionally specify some HTML to be placed before </HEAD>.

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

       htm_top _h_t_m_l
           Optionally specify some HTML to be placed near the top of the
           page.

             htm_top testing 1, 2, 3

       htm_foot _h_t_m_l
           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 _t_i_m_e_-_s_p_e_c
           For ’min_poll’ see next item. A _t_i_m_e_-_s_p_e_c 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 _t_i_m_e_-_s_p_e_c
           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 _t_i_m_e_-_s_p_e_c
           Optionally specify how often the mirrors are required to make an
           update.

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

       max_sync _t_i_m_e_-_s_p_e_c
           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 _r_e_g_i_o_n _._._.
           Optionally specify a list of regions that must be probed always.

             always_get Master Tier1

           This is intended for _f_a_k_e _r_e_g_i_o_n_s like _M_a_s_t_e_r 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 nnoo__rraannddoommiizzee.

       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 nnoo__aadddd__ssllaasshh.

       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 _s_i_t_e _u_r_l
           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 _k_e_y _v_a_l_u_e
           Optionally specify an environment variable.

       include _f_i_l_e_-_n_a_m_e
           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.

SSTTAATTEE FFIILLEE FFOORRMMAATT
       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.

IINNSSTTAALLLLAATTIIOONN
   ggeenneerraall
       ·   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

   iinnssttaallllaattiioonn ssuuggggeessttiioonnss
       To install and configure mirmon, take the following steps :

       · First, make the webdir :

           cd DOCUMENTROOT
           mkdir mirmon

         For _D_O_C_U_M_E_N_T_R_O_O_T, 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

SSEEEE AALLSSOO
       mirmon.pm(3)

AAUUTTHHOORR
         (c) 2003-2013 Henk P. Penning
         Faculty of Science, Utrecht University
         http://www.staff.science.uu.nl/~penni101/ -- penning@uu.nl
         mirmon-2.9 - Tue Aug 13 06:48:23 2013 ; henkp



perl v5.8.5                       2013-08-13                        MIRMON(1)
