just comments and debugging
[rersyncrecent.git] / HOWTO.mirrorcpan
bloba5b72c8a581102d87a427e4a628ffa87b0bcc266
1 #!perl
3 =head1 HOW TO MIRROR CPAN
5 As of this writing the single purpose for this distribution is to
6 provide a backbone for the CPAN.
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.
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.
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.
22 You find a list of potential rsync servers at
23 http://cpan.perl.org/SITES.html#RSYNC
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. And once per day or so
29 do a traditional rsync from that old school mirroring host, maybe
30 authors/ and modules/, something like:
32   rsync -av --delete --exclude "authors/" --exclude "modules/" \
33     ftp.funet.fi::CPAN /home/ftp/pub/CPAN
35 The loop is something like this:
37     $ENV{USER}="sandy"; # fill in your name
38     $ENV{RSYNC_PASSWORD} = "secret"; # fill in your passwd
40     use File::Rsync::Mirror::Recent;
41     my @rrr = map {
42         File::Rsync::Mirror::Recent->new
43                 (
44                  localroot                  => "/home/ftp/pub/PAUSE/$_", # your local path
45                  remote                     => "pause.perl.org::PAUSE/$_/RECENT.recent", # your upstream
46                  max_files_per_connection   => 863,
47                  tempdir                    => "/home/ftp/tmp", # optional tempdir to hide temporary files
48                  ttl                        => 10,
49                  rsync_options              =>
50                  {
51                   port              => 8732, # only for PAUSE
52                   compress          => 1,
53                   links             => 1,
54                   times             => 1,
55                   checksum          => 0,
56                   'omit-dir-times'  => 1, # not available before rsync 3.0.3
57                   timeout           => 300, # do not allow rsync to hang forever
58                  },
59                  verbose                    => 1,
60                  verboselog                 => "/var/log/rmirror-pause.log",
61                 )} "authors", "modules";
62     die "directory $_ doesn't exist, giving up" for grep { ! -d $_->localroot } @rrr;
63     while (){
64         my $ttgo = time + 1200; # pick less if you have a password and/or consent from the upstream
65         for my $rrr (@rrr){
66             $rrr->rmirror ( "skip-deletes" => 1 );
67         }
68         my $sleep = $ttgo - time;
69         if ($sleep >= 1) {
70             print STDERR "sleeping $sleep ... ";
71             sleep $sleep;
72         }
73     }
75 =pod
77 Don't forget to fill in your user name and password.
79 You see the 'skip-deletes' and guess, this is mirroring without doing
80 deletes. You can do it with deletes or you can leave the deletion to
81 the other, the traditional rsync loop. Worry about that later.
83 You see the option 'max_files_per_connection' which I filled with 863
84 and you need to find your favorite number. The larger the number the
85 faster the whole download goes. As you already have a mirror, you
86 probably want to take 10 or 20 times times that much. CPAN is at the
87 moment (2009-03) consisting of 142000 files. This option chunks the
88 downloads into piecemeal units and between these units the process
89 takes a peek at the most recent files to download them with higher
90 preference.
92 The localroot parameter contains your target directory. Because only
93 the authors/ and the modules/ directory are hosted by the PAUSE, you
94 need the loop over two directories. The other directories of CPAN are
95 currently not available for downloading with
96 File::Rsync::Mirror::Recent.
98 The 'port' is only needed for users who have a password for PAUSE,
99 other rsync servers listen on the rsync server port and the option can
100 be omitted.
102 The timeslice in the while loop above needs to be large enough to let
103 the rsync server survive. If you choose a random rsync server and are
104 not an rsync server yourself please be modest and choose 1200. Choose
105 less if you're offering rsync yourself and have a fat pipe, and
106 especially if you know your upstream can manage it. If you have a
107 PAUSE password choose 20 seconds. We will watch how well this works
108 and will adjust this recommendation according to our findings.
110 Set the key 'verbose' to 0 if you have no debugging demands. In this
111 case you want to omit the 'sleeping $sleep ...' noise further down the
112 script as well.
114 Set the key 'verboselog' to your favorite progress watcher file. This
115 option is underdeveloped and may later be replaced with something
116 better. Note that the program still sends error messages to STDERR.
118 You can leave everything else as it stands. Start experimenting and
119 let me know how it works out.
121 -- 
122 andreas koenig
124 =cut