These are instructions how to install mod_zrkadlo, the redirector module for apache.
The module understands query arguments (optionally appended to the URL) for 
diagnostic or other uses. See the config example for details.


It requires a backend to work with, which can be found at
https://forgesvn1.novell.com/svn/opensuse/trunk/tools/download-redirector-v2

RPM packages are here:
http://download.opensuse.org/repositories/Apache:/Modules/
http://club.mandriva.com/xwiki/bin/view/rpms/Application/apache-mod_zrkadlo

It requires libGeoIP, mod_memcache, and mod_form.
It can be built with
apxs2 -c -lGeoIP -Wc,"-Wall -g" mod_zrkadlo.c

If you use an apr-util version prior to 1.3, the memcache client support isn't included. Then you'll
need to get and build libapr_memcache, and then you'll probably build mod_zrkadlo like this:
apxs2 -c -I/usr/include/apr_memcache-0 -lGeoIP -lapr_memcache '-Wc,-Wall -g -D_GNU_SOURCE' mod_zrkadlo.c




After installation of mod_zrkadlo, you'll need to:

- install memcached
- make sure it listens on localhost only (/etc/sysconfig/memcached)
- start it ("/etc/init.d/memcached start")
- configure it to start at boot ("chkconfig -a memcached")


- install GeoIP library and commandline tools
  (openSUSE packages GeoIP + libGeoIP1)


- install mod_form
  http://apache.webthing.com/svn/apache/forms/mod_form.c
  http://apache.webthing.com/svn/apache/forms/mod_form.h
  (openSUSE package apache2-webthings-collection)


- install mod_memcache
  http://code.google.com/p/modmemcache/
  (openSUSE package apache2-mod_memcache)


- install a database adapter for the DBD library, for example MySQL
  (openSUSE package: libapr-util1-dbd-mysql)



- log into your database at root, e.g. for mysql:
    mysql -u root -p
  there, create the database and grant write permissions for a local user:
    create database redirector;
    grant all privileges on redirector.* to wwwrun@localhost identified by '12345';

  run the sql file which creates the tables and indices:
    mysql -u wwwrun -p -D redirector < /usr/share/doc/packages/apache2-mod_zrkadlo/sql/opensuse-redirector.sql


- create /etc/mirrorbrain.conf with the following content:

  [general]
  instances = go-oo

  [go-oo]
  dbuser = wwwrun
  dbpass = 12345
  dbhost = your_host.example.com
  dbport = 3306
  dbname = redirector
  
  [mirrorprobe]
  logfile = /var/log/mirrorprobe.log
  loglevel = INFO
  mailto = your_mail@example.com, another_mail@example.com


  
- load the Apache modules:
   a2enmod form
   a2enmod memcache
   a2enmod dbd
   a2enmod zrkadlo


- configure Apache:

  - create a DNS alias for your web host, if needed

  - configure the database adapter, and mod_zrkadlo. Put it in server-wide
    context, and make the file chmod 640 because it contains the database
    password.

    ------------------------------------------------------------------------
    <IfModule mod_dbd.c>
        DBDriver mysql
        # reconnect=0 is needed with the mysql adapter. It means that connections
        # should not be "reanimated", because prepared statements would be lost anyway,
        # so dead connections should rather be invalidated and new ones made.
        DBDParams "host=localhost, user=wwwrun, pass=12345, dbname=redirector, reconnect=0"
        # # threaded MPMs only. prefork will have use db connection per process
        <IfModule !prefork.c>
                # 
                DBDMin  0
                DBDMax  32
                DBDKeep 4
                DBDExptime 10
        </IfModule>
    </IfModule>
    
    <IfModule mod_memcache.c>
        MemcacheServer 127.0.0.1:11211 min=0 smax=4 max=16 ttl=600
    </IfModule>
    <IfModule mod_zrkadlo.c>
        ZrkadloMemcached On
        ZrkadloMemcachedLifetime 1800
        ZrkadloGeoIPFile /usr/share/GeoIP/GeoIP.dat
    </IfModule>
    ------------------------------------------------------------------------



  - create a vhost for it (e.g. /etc/apache2/vhosts.d/go-oo.zrkadlo.org.conf)

    ------------------------------------------------------------------------
    <VirtualHost your.host.name:80>
        ServerName go-oo.zrkadlo.org
    
        ServerAdmin webmaster@zrkadlo.org
    
        DocumentRoot /srv/go-oo/pub/projects
    
        ErrorLog     /var/log/apache2/go-oo.zrkadlo.org/logs/error_log
        CustomLog    /var/log/apache2/go-oo.zrkadlo.org/logs/access_log combined

        <Directory /srv/go-oo/pub/projects>
            ZrkadloEngine On
            ZrkadloDebug Off
            FormGET On
            ZrkadloHandleHEADRequestLocally Off
            ZrkadloMinSize 0
            ZrkadloHandleDirectoryIndexLocally On
    
            Options FollowSymLinks Indexes
            AllowOverride None
            Order allow,deny
            Allow from all
        </Directory>
    
    </VirtualHost>
    ------------------------------------------------------------------------

  - restart Apache, while watching the error log:
      tail -F /var/log/apache2/*_log &
      rcapache2 restart

    


- collect a list of mirrors (their HTTP baseurl, and their rsync or FTP baseurl
  for scanning). For example:

    http://ftp.isr.ist.utl.pt/pub/MIRRORS/ftp.suse.com/projects/
    rsync://ftp.isr.ist.utl.pt/suse/projects/

    http://ftp.kddilabs.jp/Linux/distributions/ftp.suse.com/projects/
    rsync://ftp.kddilabs.jp/suse/projects/



  Now you need to enter the mirrors into the database; it could be done like this: 
  (see 'mirrordoctor help new' for full option list)

    mirrordoctor new ftp.isr.ist.utl.pt \
                     --http http://ftp.isr.ist.utl.pt/pub/MIRRORS/ftp.suse.com/projects/ \
                     --rsync rsync://ftp.isr.ist.utl.pt/suse/projects/

    mirrordoctor new ftp.kddilabs.jp \
                     --http http://ftp.kddilabs.jp/Linux/distributions/ftp.suse.com/projects/ \
                     --rsync rsync://ftp.kddilabs.jp/suse/projects/


  The mirror doctor figures out the GeoIP location of each mirror by itself.
  But you could also specify them on the commandline.

  If you want to edit a mirror later, use
    mirrordoctor edit <identifier>

  See the output of 'mirrordoctor help' for more commands.

  Each mirror needs to be scanned and enabled:
    mirrordoctor scan --enable <identifier>





Sorry, but further instructions are missing here. I hope I can add them later.
For now, please contact me at <poeml@suse.de>, and I'll help you, and it will
give me an occasion to improve this document along the way.

TODO:

- add wrapper script to run mirrorprobe / scanner as unprivileged user
  and describe how to set it up

    su - mirror -s /bin/bash -c "/usr/bin/scanner.mine -f ftp.isr.ist.utl.pt"
    -*/3 * * * *     root  /usr/bin/mirrorprobe &>/dev/null

- describe mysql tuning for innodb engine for performance
