HOWTO.mirrorcpan

   1 #!perl
   2
   3 =head1 HOW TO MIRROR CPAN
   4
   5 As of this writing the single purpose for this distribution is to
   6 provide a backbone for the CPAN.
   7
   8 The idea is to get a handful backbone nodes that mirror directly from
   9 PAUSE and a second layer that mirrors from them. Targetting at a
  10 mirroring interval of 20 seconds.
  11
  12 The rsync daemon on PAUSE runs on port 8732 and you need a password to
  13 access it. There is a second rsync daemon running on the standard port
  14 873 but it has very limited access policies to leave the bandwidth for
  15 the backbone.
  16
  17 If you have username and password you can mirror directly from PAUSE.
  18 If you haven't and maintain a public CPAN mirror, ask me for one.
  19 Otherwise pick your best CPAN mirror with an rsync server and try the
  20 same script below for getting the quickest update cycle possible.
  21
  22 You find a list of potential rsync servers at
  23 http://cpan.perl.org/SITES.html#RSYNC
  24
  25 The first thing you should prepare is the CPAN tree itself on your
  26 disk. The source where you take it from does not matter that much.
  27 Take it from where you always took it. The setup I suggest is to
  28 mirror authors/ and modules/ with this program.
  29
  30 The loop is something like this:
  31
  32 Short version:
  33
  34     #!/bin/sh
  35
  36     RSYNC_PASSWORD=secret
  37     export RSYNC_PASSWORD
  38
  39     for t in modules authors ; do
  40       rrr-client --source rsync://andk@pause.perl.org:8732/PAUSE/$t/ --target /home/ftp/pub/PAUSE/$t/ --tmpdir /home/tmp &
  41     done
  42
  43 Or if the short version is not sufficient for some reason:
  44
  45     $ENV{USER}="sandy"; # fill in your name
  46     $ENV{RSYNC_PASSWORD} = "secret"; # fill in your passwd
  47
  48     use File::Rsync::Mirror::Recent;
  49     my @rrr = map {
  50         File::Rsync::Mirror::Recent->new
  51                 (
  52                  localroot                  => "/home/ftp/pub/PAUSE/$_", # your local path
  53                  remote                     => "pause.perl.org::PAUSE/$_/RECENT.recent", # your upstream
  54                  max_files_per_connection   => 863,
  55                  tempdir                    => "/home/ftp/tmp", # optional tempdir to hide temporary files
  56                  ttl                        => 10,
  57                  rsync_options              =>
  58                  {
  59                   port              => 8732, # only for PAUSE
  60                   compress          => 1,
  61                   links             => 1,
  62                   times             => 1,
  63                   checksum          => 0,
  64                   'omit-dir-times'  => 1, # not available before rsync 3.0.3
  65                   timeout           => 300, # do not allow rsync to hang forever
  66                  },
  67                  verbose                    => 1,
  68                  verboselog                 => "/var/log/rmirror-pause.log",
  69                 )} "authors", "modules";
  70     die "directory $_ doesn't exist, giving up" for grep { ! -d $_->localroot } @rrr;
  71     while (){
  72         my $ttgo = time + 1200; # pick less if you have a password and/or consent from the upstream
  73         for my $rrr (@rrr){
  74             $rrr->rmirror ( "skip-deletes" => 1 );
  75         }
  76         my $sleep = $ttgo - time;
  77         if ($sleep >= 1) {
  78             print STDERR "sleeping $sleep ... ";
  79             sleep $sleep;
  80         }
  81     }
  82
  83 =pod
  84
  85 Don't forget to fill in your user name and password.
  86
  87 You see the 'skip-deletes' and guess, this is mirroring without doing
  88 deletes. You can do it with deletes or you can leave the deletion to
  89 the other, the traditional rsync loop. Worry about that later.
  90
  91 You see the option 'max_files_per_connection' which I filled with 863
  92 and you need to find your favorite number. The larger the number the
  93 faster the whole download goes. As you already have a mirror, you
  94 probably want to take 10 or 20 times times that much. CPAN's authors
  95 directory is at the moment (2010-10) consisting of 180000 files. This
  96 option chunks the downloads into piecemeal units and between these
  97 units the process takes a peek at the most recent files to download
  98 them with higher preference. That way we get the newest files
  99 immediately in sync while we are mirroring the long tail of old files.
 100
 101 The localroot parameter contains your target directory. Because only
 102 the authors/ and the modules/ directory are hosted by the PAUSE, you
 103 need the loop over two directories. The other directories of CPAN are
 104 currently not available for downloading with
 105 File::Rsync::Mirror::Recent.
 106
 107 The 'port' is only needed for users who have a password for PAUSE,
 108 other rsync servers listen on the rsync server port and the option can
 109 be omitted.
 110
 111 The timeslice in the while loop above needs to be large enough to let
 112 the rsync server survive. If you choose a random rsync server and are
 113 not an rsync server yourself please be modest and choose 1200. Choose
 114 less if you're offering rsync yourself and have a fat pipe, and
 115 especially if you know your upstream can manage it. If you have a
 116 PAUSE password choose 20 seconds. We will watch how well this works
 117 and will adjust this recommendation according to our findings.
 118
 119 Set the key 'verbose' to 0 if you have no debugging demands. In this
 120 case you want to omit the 'sleeping $sleep ...' noise further down the
 121 script as well.
 122
 123 Set the key 'verboselog' to your favorite progress watcher file. This
 124 option is underdeveloped and may later be replaced with something
 125 better. Note that the program still sends error messages to STDERR.
 126
 127 You can leave everything else as it stands. Start experimenting and
 128 let me know how it works out.
 129
 130 --
 131 andreas koenig
 132
 133 =cut