.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IIM 1"
.TH IIM 1 "2013-05-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
iim \- an instant mirroring client for CPAN
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  iim [-v] [-q] [-d] [-t] [-f] [-m] [-daemon tag] [-e e] [-c conf] [config-options]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Program \fBiim\fR mirrors \s-1CPAN\s0 based on a set of \fI\s-1RECENT\s0\fR (\f(CW\*(C`RECENT\-*.json\*(C'\fR)
files provided in \s-1CPAN\s0.
.PP
On start\-up, \fBiim\fR compares the state of the local copy of \s-1CPAN\s0 with
the master archive.
If the \fI\s-1RECENT\s0\fR files in the local copy indicate that it is incomplete or
too much out\-of\-date, \fBiim\fR does a full sync first.
.PP
Then,  \fBiim\fR periodically reads the relevant \fI\s-1RECENT\s0\fR files from the
master archive.
These files contain information about recent updates.
Program \fBiim\fR uses this information to fetch new files from the master,
and delete obsolete files in the local copy.
.PP
Program \fBiim\fR is controlled by a small configuration file ;
see section \*(L"\s-1CONFIG\s0 \s-1FILE\s0\*(R"
\&\-> required entries.
.PP
In \fIdaemon mode\fR, \fBiim\fR is properly backgrounded and all output
is written to a log file.
Some effort is made to ensure that only one daemon is active
at any given time.
.PP
The scoreboard facility
provides more information about the running program ;
it is updated after every run of the main loop.
.PP
The config can be \fIhot\fR or \fInot\fR ; if \fIhot\fR, \fBiim\fR will reload
the config file when you change it.
.PP
By default logging is terse ; \fBiim\fR only shows errors and
relevant (non\-periodic) updates.
With option \f(CW\*(C`\-v\*(C'\fR it reports on all events and gives some
state information when new events were found.
With option \f(CW\*(C`\-d\*(C'\fR it reports on internal actions as well.
For more information, see also config entry
loglevel.
.PP
As an option, \fBiim\fR can schedule periodic full rsyncs ; they are
not necessary even when there are many and/or prolongued network
failures.
.PP
By default, \fBiim\fR will periodically rotate
the logfile.
.PP
For more information on \fI\s-1RECENT\s0\fR files and instant mirroring, see
.IP "* www.cpan.org" 4
.IX Item "www.cpan.org"
<http://www.cpan.org/misc/how\-to\-mirror.html#Instant_mirroring>
.IP "* search.cpan.org" 4
.IX Item "search.cpan.org"
<http://search.cpan.org/>
.Sp
Look for \f(CW\*(C`File::Rsync::Mirror::Recent\*(C'\fR
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-q\fR" 4
.IX Item "-q"
be quiet ;
see also config entry loglevel
.IP "\fB\-v\fR" 4
.IX Item "-v"
be verbose ;
see also config entry loglevel
.IP "\fB\-d\fR" 4
.IX Item "-d"
show debug info ;
see also config entry loglevel
.IP "\fB\-t\fR" 4
.IX Item "-t"
only test the config
.IP "\fB\-f\fR" 4
.IX Item "-f"
on startup, do a full sync ; commandline option \f(CW\*(C`\-f\*(C'\fR overrides
config entry allow_full_syncs ; so,
\&\f(CW\*(C`iim \-f\*(C'\fR will do a full sync even if \fIallow_full_syncs\fR is \fI0\fR.
.IP "\fB\-daemon\fR \fItag\fR" 4
.IX Item "-daemon tag"
run \fBiim\fR in \fIdaemon\fR mode :
A daemon-like \fBiim\fR process is started,
unless an other \fBiim\fR daemon (with the same \fItag\fR)
is already running.
The process is properly backgrounded.
.Sp
The daemon uses the current directory as it's working directory.
It creates a directory \fI\f(CI\*(C`tag\*(C'\fI\fR containing :
.RS 4
.ie n .IP "* a log-file : ""iim.log""" 4
.el .IP "* a log-file : \f(CWiim.log\fR" 4
.IX Item "a log-file : iim.log"
.PD 0
.ie n .IP "* a pid file : ""iim.pid""" 4
.el .IP "* a pid file : \f(CWiim.pid\fR" 4
.IX Item "a pid file : iim.pid"
.ie n .IP "* a lock-file : ""iim.lck""" 4
.el .IP "* a lock-file : \f(CWiim.lck\fR" 4
.IX Item "a lock-file : iim.lck"
.RE
.RS 4
.PD
.Sp
All commandline arguments (except \f(CW\*(C`\-daemon\*(C'\fR) are passed to the daemon.
All (error) output is written to the log \fI\f(CI\*(C`tag\*(C'\fI\fR\f(CW\*(C`/iim.log\*(C'\fR.
The log is re-opened approximately every 5 minutes,
to make log-rotation easier.
.Sp
The daemon is best killed with
.Sp
.Vb 1
\&  kill -9 `cat tag/iim.pid`
.Ve
.Sp
Daemon mode uses \f(CW\*(C`Proc::Daemon\*(C'\fR.
.RE
.IP "\fB\-e\fR \fIepoch\fR" 4
.IX Item "-e epoch"
init with epoch \fIepoch\fR ; \fIepoch\fR may be given as an \fIinterval-spec\fR
(see option sleep_main_loop).
.Sp
If \fIepoch\fR is \f(CW\*(C`negative\*(C'\fR then the epoch is set to "time \- \fIepoch\fR".
.Sp
.Vb 3
\&  -e 1307687587.89889
\&  -e -30m             # set the epoch to 30 minutes ago
\&  -e -2h              # set the epoch to two hours ago
.Ve
.Sp
If \f(CW\*(C`\-e\*(C'\fR is set, \fBiim\fR does no full sync on start-up ;
it just processes the update events that happened since \fIepoch\fR.
.Sp
This option is for testing only.
.IP "\fB\-c\fR \fIconfig-file\fR" 4
.IX Item "-c config-file"
use configuration file \fIconfig-file\fR
.IP "\fB\-m\fR" 4
.IX Item "-m"
compare the local archive with the master ; \fBiim\fR exec's an \f(CW\*(C`rsync \-n\*(C'\fR.
.IP "\fIconfig options\fR" 4
.IX Item "config options"
All config entries can be set on the commandline :
.Sp
.Vb 1
\&  --entry value
.Ve
.Sp
for example
.Sp
.Vb 1
\&  --sleep_main_loop 5m
.Ve
.Sp
Note that the config file must still be \fIcomplete\fR (entries for all
required keys) and \fIcorrect\fR (directory \f(CW\*(C`local\*(C'\fR must exists).
.SH "CONFIG FILE"
.IX Header "CONFIG FILE"
.Sh "location"
.IX Subsection "location"
The default locations of the config file are :
.IP "* \fB./iim.conf\fR" 4
.IX Item "./iim.conf"
.PD 0
.IP "* \fB$HOME/.iim.conf\fR" 4
.IX Item "$HOME/.iim.conf"
.IP "* \fB/etc/iim.conf\fR" 4
.IX Item "/etc/iim.conf"
.PD
.Sh "syntax"
.IX Subsection "syntax"
A config file looks like this :
.PP
.Vb 34
\&  +--------------------------------------------------
\&  |# 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  part1 part2 part3 ...
\&  |otherkey part1 part2 part3 ...
\&  |
\&  |# keyword EMPTY represents the empty string ;
\&  |# in the next line some_key's part2 is set to ''
\&  |somekey part1 EMPTY part3 ...
\&  |
\&  |# 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\en part2\en part3"
\&  |somekey part1
\&  |. part2
\&  |. part3
\&  +--------------------------------------------------
.Ve
.Sh "config file : required entries"
.IX Subsection "config file : required entries"
.IP "local \fIpath\fR" 4
.IX Item "local path"
Specify the (full, absolute) path to the local copy of \s-1CPAN\s0.
.Sp
.Vb 1
\&  local /path/to/your/cpan-archive
.Ve
.Sh "config file : optional entries"
.IX Subsection "config file : optional entries"
.IP "temp \fIpath\fR" 4
.IX Item "temp path"
This config entry is now \fBobsolete\fR ;
please remove it from config file \f(CW\*(C`iim.conf\*(C'\fR.
.IP "remote \fIsome.host.org::module\fR" 4
.IX Item "remote some.host.org::module"
Optionally specify the rsync-module of the remote server.
The default is :
.Sp
.Vb 1
\&  remote cpan-rsync.perl.org::CPAN
.Ve
.Sp
If you are testing for \fI\s-1CPAN\s0 tier1\fR, set
.Sp
.Vb 1
\&  remote cpan-rsync-master.perl.org::CPAN
.Ve
.Sp
Also set config entries \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`passwd\*(C'\fR.
.IP "user \fIlogin\fR" 4
.IX Item "user login"
Optionally specify the login name to be used in rsync connections.
The default is \s-1EMPTY\s0 ; that is, the empty string :
.Sp
.Vb 1
\&  user EMPTY
.Ve
.IP "passwd \fIpw\fR" 4
.IX Item "passwd pw"
Optionally specify the password to be used in rsync connections.
The default is \s-1EMPTY\s0 ; that is, the empty string :
.Sp
.Vb 1
\&  passwd EMPTY
.Ve
.Sp
The password is passed to \f(CW\*(C`rsync\*(C'\fR in environment-variable
\&\f(CW\*(C`RSYNC_PASSWORD\*(C'\fR.
.IP "sleep_main_loop \fIinterval-spec\fR" 4
.IX Item "sleep_main_loop interval-spec"
Optionally specify the interval between runs of the main\-loop.
The default is 1 minute :
.Sp
.Vb 1
\&  sleep_main_loop 1m
.Ve
.Sp
and five minutes in \fIdaemon\fR mode.
.Sp
An \fBinterval-spec\fR can be given in seconds (as in \fB22\fR or \fB22s\fR),
minutes [\fBm\fR],
hours [\fBh\fR],
days [\fBd\fR] and/or
weeks [\fBw\fR].
.Sp
The \fIinterval-specs\fR can be combined in any order :
.Sp
.Vb 4
\&  dw      # a day and a week
\&  7d+24h  # same thing
\&  w-0.5h  # a week minus half an hour
\&  hm6     # 3666 seconds
.Ve
.IP "sleep_init_epoch \fIinterval-spec\fR" 4
.IX Item "sleep_init_epoch interval-spec"
Optionally specify the interval between retries during start\-up.
The default is fifteen minutes :
.Sp
.Vb 1
\&  sleep_init_epoch 15m
.Ve
.Sp
A start-up is \fIretried\fR if the start-up requires a full sync
and that sync somehow fails.
.IP "max_run_time \fIinterval-spec\fR" 4
.IX Item "max_run_time interval-spec"
To avoid memory leaks from becoming a problem, by default \fBiim\fR runs
for a limited time.
.Sp
Optionally specify the maximum time \fBiim\fR may run.
The default is \fIone week minus 15 minutes\fR :
.Sp
.Vb 1
\&  max_run_time 1w-15m
.Ve
.Sp
Setting \f(CW\*(C`max_run_time\*(C'\fR to \fI0\fR means \fIno limit\fR.
.Sp
Make sure there is a cronjob in place to start an \fBiim\fR daemon
after \fBiim\fR exits or the mirror host is rebooted.
.Sp
.Vb 1
\&  MIN * * * * ( cd /your/path/to/iim ; perl iim -q -daemon production )
.Ve
.Sp
where \fI\s-1MIN\s0\fR (minute) is some (randomly chosen) number between 0 and 59.
.IP "scoreboard_file \fIpath/to/file\fR" 4
.IX Item "scoreboard_file path/to/file"
In each run of the main loop, \fBiim\fR writes the \fIscoreboard_file\fR ;
it shows the current status of \fBiim\fR, various timers, counters etc.
The defaul is :
.Sp
.Vb 1
\&  scoreboard_file /path/to/CPAN/local/iim/iim-scb.html
.Ve
.Sp
Actually, you can specify more than one file :
.Sp
.Vb 3
\&  scoreboard_file
\&    /path-to-some-dir/iim-scb.html
\&    /path-to-some-dir/iim-scb.json
.Ve
.Sp
Depending on the suffix of \fIfile\fR (\f(CW\*(C`.html\*(C'\fR, \f(CW\*(C`.php\*(C'\fR, \f(CW\*(C`.json\*(C'\fR),
\&\fBiim\fR writes a \fIhtml\fR page, a \fIphp\fR fragament or a \fIjson\fR file ;
plain text is the default.
.Sp
The \fIhtml\fR pages are generated using a template \fIscoreboard_template\fR
(see next item).
.Sp
The \fIjson\fR files (also) contain the values of config entries and defaults.
.Sp
The \fIscoreboard_template\fR (see next item) contains \s-1CSS\s0 to properly
format the scoreboard.
.IP "scoreboard_template \fIpath/to/file\fR" 4
.IX Item "scoreboard_template path/to/file"
Optionally specify the path to the template for a html scoreboard.
.Sp
The default is :
.Sp
.Vb 1
\&  scoreboard_template iim-scb-tmpl.html
.Ve
.Sp
If that's missing, the template in the distro is used :
.Sp
.Vb 1
\&  scoreboard_template iim-scb-tmpl.html.sample
.Ve
.IP "hot_config 0|1" 4
.IX Item "hot_config 0|1"
Optionally specify if the config is \fIhot\fR or not. The default is \fInot hot\fR :
.Sp
.Vb 1
\&  hot_config 0
.Ve
.Sp
If/when the config is \fIhot\fR, \fBiim\fR checks the config file for changes :
if the (timestamp of the) config file changes, it is reloaded unless an
error is detected.
.Sp
Use this option with care ; watch the log!
.IP "loglevel quiet|terse|verbose|debug" 4
.IX Item "loglevel quiet|terse|verbose|debug"
Optionally specify the level of logging ; the default is :
.Sp
.Vb 1
\&  loglevel terse
.Ve
.Sp
If the loglevel is \fIterse\fR, \fBiim\fR logs all events except updates
of files that change very often like \f(CW\*(C`indices/timestamp.txt\*(C'\fR,
\&\f(CW\*(C`RECENT\-1h.json\*(C'\fR etc.
.Sp
If the loglevel is \fIverbose\fR, \fBiim\fR reports on all events.
.Sp
If the loglevel is \fIdebug\fR, \fBiim\fR reports on internal actions as well.
.Sp
Loglevel \fIquiet\fR does not affect event logging ; it is only used
to let \fBiim\fR quietly attempt to (re)start a daemon.
.Sp
Precedence : \f(CW\*(C`\-d\*(C'\fR, \f(CW\*(C`\-v\*(C'\fR, \f(CW\*(C`\-q\*(C'\fR, commandline option \f(CW\*(C`\-\-loglevel\*(C'\fR,
config entry \f(CW\*(C`loglevel\*(C'\fR.
.Sp
Option \f(CW\*(C`\-q\*(C'\fR isn't passed to the \fIdaemon\fR, so config entry \f(CW\*(C`loglevel\*(C'\fR
(or \f(CW\*(C`\-\-loglevel\*(C'\fR) can be effective.
.IP "rotate count [interval]" 4
.IX Item "rotate count [interval]"
Optionally specify logfile rotation ; the default is
.Sp
.Vb 1
\&  rotate 8 1w
.Ve
.Sp
Logfile rotation only applies in \fIdaemon mode\fR.
Logfiles are not rotated if \fIcount\fR == 0.
.Sp
If a non-zero \fIcount\fR is specified, \fIcount\fR logfiles
are rotated on start\-up, and again after \fIinterval\fR, etc.
.IP "full_sync_interval \fIinterval-spec\fR" 4
.IX Item "full_sync_interval interval-spec"
Optionally specify the interval between full rsyncs.
The default is \fI0\fR, which means \fIdon't schedule full syncs\fR.
.Sp
.Vb 1
\&  full_sync_interval 0
.Ve
.Sp
If a full sync fails, a new full sync is scheduled to take place
\&\fIsleep_init_epoch\fR later.
.Sp
If everything works as advertized, full syncs are not necessary.
.IP "allow_full_syncs 0|1" 4
.IX Item "allow_full_syncs 0|1"
Optionally specify if full syncs are allowed or not.
The default is \fI1\fR, which means that full syncs \fIare\fR allowed.
.Sp
.Vb 1
\&  allow_full_syncs 1
.Ve
.Sp
On startup, a full sync is required if the local archive is
inconsistent (\fI\s-1RECENT\s0 files\fR are missing) or older than one day.
.Sp
After startup, \fBiim\fR will do (scheduled) full syncs if,
and only if, \fIfull_sync_interval\fR is set.
.Sp
\&\fBIim\fR will exit if it can't proceed without a full sync,
and \fIallow_full_syncs\fR is \fI0\fR.
.Sp
This option is for \fItesting\fR ; it is used to ensure that no full syncs
will be done in a test environment created by \f(CW\*(C`setup\-test\*(C'\fR.
.IP "prog_rsync \fIpath/to/file\fR" 4
.IX Item "prog_rsync path/to/file"
Optionally specify where your \f(CW\*(C`rsync\*(C'\fR lives ; the default is :
.Sp
.Vb 1
\&  prog_rsync /usr/bin/rsync
.Ve
.IP "timeout \fIinterval-spec\fR" 4
.IX Item "timeout interval-spec"
Optionally specify the default for rsync's \f(CW\*(C`\-\-timeout\*(C'\fR ; the default is :
.Sp
.Vb 1
\&  timeout 300s
.Ve
.Sp
The value is also used to set rsync's \f(CW\*(C`\-\-contimeout\*(C'\fR.
.IP "iim_umask \fIoct-integer\fR" 4
.IX Item "iim_umask oct-integer"
Optionally specify the \fIumask\fR \fBiim\fR should use ; in octal, as is usual.
The default is :
.Sp
.Vb 1
\&  iim_umask 022
.Ve
.Sp
Umask \f(CW022\fR allows rsync to create world readable files and directories.
Often \f(CW\*(C`cron\*(C'\fR runs with a more restrictive umask (\f(CW077\fR).
This leads to permission problems in the archive.
.IP "include \fIpath/to/file\fR" 4
.IX Item "include path/to/file"
Include another \fBiim\fR config file in situ. It is a fatal error
to include the same file twice.
.SH "INSTALL"
.IX Header "INSTALL"
.Sh "requirements"
.IX Subsection "requirements"
\&\fBIim\fR requires Perl modules \f(CW\*(C`JSON\*(C'\fR and \f(CW\*(C`Proc::Daemon\*(C'\fR.
You may want to install these modules as \fBroot\fR.
.ie n .IP "* get ""cpanm"" :" 4
.el .IP "* get \f(CWcpanm\fR :" 4
.IX Item "get cpanm :"
.Vb 2
\&  # curl --compressed -LO http://xrl.us/cpanm
\&  # chmod +x ./cpanm
.Ve
.ie n .IP "* install Perl modules ""JSON""\fR (or \f(CW""JSON::PP""\fR) and \f(CW""Proc::Daemon"" :" 4
.el .IP "* install Perl modules \f(CWJSON\fR (or \f(CWJSON::PP\fR) and \f(CWProc::Daemon\fR :" 4
.IX Item "install Perl modules JSON (or JSON::PP) and Proc::Daemon :"
.Vb 2
\&  # ./cpanm JSON
\&  # ./cpanm Proc::Daemon
.Ve
.Sp
If installing \f(CW\*(C`JSON\*(C'\fR fails, install \f(CW\*(C`JSON::PP\*(C'\fR (Pure Perl) instead.
.PP
\&\fBIim\fR requires that your \s-1CPAN\s0 archive is either empty or complete :
the last rsync (if any) completed successfully.
The archive doesn't have to be up\-to\-date.
If you are not sure, run rsyncs until one succeeds.
.PP
.Vb 1
\&  rsync -av --delete cpan-rsync.perl.org::CPAN/ /path/to/CPAN/
.Ve
.PP
Later, such full rsyncs aren't necessary because \fBiim\fR makes sure
the archive is always (in some sense) \fIcomplete\fR.
.Sh "installation"
.IX Subsection "installation"
Installation is simple :
.IP "* fetch the source" 4
.IX Item "fetch the source"
Checkout the svn repository :
.Sp
.Vb 1
\&  svn co https://svn.science.uu.nl/repos/sci.penni101.iim/trunk/ iim
.Ve
.Sp
or get the package (same stuff) :
.Sp
.Vb 1
\&  http://people.cs.uu.nl/henkp/iim/iim.tar.gz
.Ve
.Sp
or get the bleeding edge :
.Sp
.Vb 1
\&  wget -r -l 1 --cut-dirs=2 -nH -R 'README*' ftp://ftp.cs.uu.nl/pub/PERL/iim/
.Ve
.IP "* make a configuration file" 4
.IX Item "make a configuration file"
Create a file \f(CW\*(C`iim.conf\*(C'\fR ; a sample is in \f(CW\*(C`iim.conf.sample\*(C'\fR :
.Sp
.Vb 1
\&  local  /path/to/CPAN
.Ve
.Sp
Point \fIlocal\fR to your \s-1CPAN\s0 archive.
.Sp
Specify a full (not relative) pathname like \f(CW\*(C`/path/to/CPAN/\*(C'\fR.
.Sp
If you are using \f(CW\*(C`cpan\-rsync\-master.perl.org\*(C'\fR, add
.Sp
.Vb 3
\&  remote cpan-rsync-master.perl.org::CPAN
\&  user   your-cpan-username
\&  passwd your-cpan-password
.Ve
.IP "* check the config" 4
.IX Item "check the config"
.Vb 1
\&  perl iim -t
.Ve
.IP "* run" 4
.IX Item "run"
You may want to do some testing, or simply run \fBiim\fR with :
.Sp
.Vb 1
\&  perl iim -v
.Ve
.Sp
\&\fBIim\fR immediately starts tracking the changes in the
\&\s-1CPAN\s0 master, picking up where the last sync left off.
.Sp
Only if your \s-1CPAN\s0 archive is more than 2 days old,
a full sync is done first.
.IP "* scoreboard" 4
.IX Item "scoreboard"
The \fIscoreboard\fR is in
.Sp
.Vb 1
\&  /path/to/CPAN/local/iim/iim-scb.html
.Ve
.IP "* daemon mode" 4
.IX Item "daemon mode"
\&\fBIim\fR is intended to run in the background, as a daemon process.
Try \fIdaemon mode\fR with :
.Sp
.Vb 1
\&  perl iim -daemon production
.Ve
.Sp
Watch the logfile with :
.Sp
.Vb 1
\&  tail -f production/iim.log
.Ve
.IP "* production" 4
.IX Item "production"
Configure more options
that fit your situation.
See the next section for more tips on using \fBiim\fR
in production.
.Sp
Make sure you have a cronjob in place to start a fresh \fBiim\fR daemon.
.Sh "production"
.IX Subsection "production"
Here are some things to keep in mind when you use \fBiim\fR in production :
.IP "\(bu" 4
\&\fBiim\fR is meant to be used from the installation directory.
.IP "\(bu" 4
\&\fBiim\fR is meant to be used in \f(CW\*(C`\-daemon\*(C'\fR mode.
.IP "\(bu" 4
To prevent memory leaks from becoming a problem,
\&\fBiim\fR runs for a limited time (one week) by default.
.Sp
To ensure that \fBiim\fR is always running, install a cronjob like :
.Sp
.Vb 1
\&  MIN * * * * ( cd /your/path/to/iim ; perl iim -q -daemon production )
.Ve
.Sp
where \fI\s-1MIN\s0\fR (minute) is some (randomly chosen) number between 0 and 59.
.Sp
The cronjob will try to start a fresh \fBiim\fR daemon ; it will quietly
exit if another daemon is already running.
.Sp
Adding \f(CW\*(C`\-f\*(C'\fR will force a full sync on startup, even if your mirror
is reasonable up to date.
.Sp
Use \f(CW\*(C`crontab \-l\*(C'\fR to list your cronjobs.
.IP "\(bu" 4
If you make \s-1CPAN\s0 available by rsync, please add
.Sp
.Vb 1
\&  excludes = /local/
.Ve
.Sp
to your [\s-1CPAN\s0] module in your \f(CW\*(C`rsyncd.conf\*(C'\fR file.
.Sh "testing"
.IX Subsection "testing"
Testing \fBiim\fR doesn't touch your \s-1CPAN\s0 archive, and doesn't require
(or make) a copy of \s-1CPAN\s0.
.PP
You set up a little test environment with :
.PP
.Vb 1
\&  perl -w setup-test [testenv]
.Ve
.PP
Basicly, \fBsetup-test\fR does :
.PP
.Vb 2
\&  mkdir testenv
\&  mkdir testenv/CPAN
.Ve
.PP
.Vb 1
\&  # makes "testenv/iim.conf" containing :
.Ve
.PP
.Vb 4
\&    include iim.conf
\&    local testenv/CPAN
\&    sleep_main_loop 15s
\&    allow_full_syncs 0
.Ve
.PP
.Vb 2
\&  # seed the test-archive
\&  cp -p /path_to_CPAN/RECENT-*.json testenv/CPAN
.Ve
.PP
You can check the test-config with :
.PP
.Vb 1
\&  perl iim -t -c testenv/iim.conf
.Ve
.PP
\&... and run the test with :
.PP
.Vb 1
\&  perl iim -c testenv/iim.conf -v
.Ve
.PP
\&... or try daemon mode with :
.PP
.Vb 1
\&  perl iim -c testenv/iim.conf -v -daemon testenv
.Ve
.PP
If your local \s-1CPAN\s0 archive is a little oldish, \fBsetup-test\fR
seeds the test-archive with
.PP
.Vb 8
\&  RECENT-1h.json
\&  RECENT-6h.json
\&  RECENT-1d.json
\&  RECENT-1W.json
\&  RECENT-1M.json
\&  RECENT-1Q.json
\&  RECENT-1Y.json
\&  RECENT-Z.json
.Ve
.PP
from the public \s-1CPAN\s0 archive \f(CW\*(C`cpan\-rsync.perl.org::CPAN\*(C'\fR.
.PP
The test never does a full rsync ; it just picks up the
\&\s-1CPAN\s0 updates and applies them to \f(CW\*(C`testenv/CPAN/\*(C'\fR.
.PP
If you kill (or suspend) \fBiim\fR and restart (or resume)
it later (say afer an hour), you can see that \fBiim\fR
picks up where it was when you stopped it.
.PP
If/when you test \fBiim\fR with a full \s-1CPAN\s0 archive, you can
use \f(CW\*(C`iim \-m\*(C'\fR to do a full compare of the local archive
and the master ; \f(CW\*(C`iim \-m\*(C'\fR just exec's the proper \f(CW\*(C`rsync \-n\*(C'\fR.
.SH "UPGRADE"
.IX Header "UPGRADE"
.IP "\(bu" 4
Before upgrading, check the RELEASE-NOTES in
svn
or the
bleeding edge.
.IP "\(bu" 4
It is safe to do an svn update :
.Sp
.Vb 1
\&  svn up
.Ve
.Sp
or download the package and copy everything to your \fBiim\fR directory.
.SH "TODO"
.IX Header "TODO"
.IP "* randomize full_sync_interval, sleep_init_epoch" 4
.IX Item "randomize full_sync_interval, sleep_init_epoch"
.PD 0
.IP "* switch to git" 4
.IX Item "switch to git"
.PD
.SH "THANKS"
.IX Header "THANKS"
A big thanks to Andreas J. König for patiently explaining the details
of \fI\s-1RECENT\s0\fR files to the author.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 4
\&  (c) 2011-2013 Henk P. Penning
\&  Faculty of Science, Utrecht University
\&  http://www.staff.science.uu.nl/~penni101/ -- penning@uu.nl
\&  iim version 0.4.5 - Sat May 18 10:55:02 2013 - dev revision 71
.Ve