This is Info file INSTALL.info, produced by Makeinfo-1.55 from the
input file INSTALL.texi.

A ONE-MINUTE INTRODUCTION TO MIRRORD/FLOOOD
===========================================

   These step-by-step instructions detail how to replicate a Harvest
broker using our mirrord/floodd replication tools.  In brief, floodd
measures the available network bandwidth and delay between broker
replicas and creates and maintains the network topology over which
replicas should be updated to use the network most efficiently.
Mirrord invokes the ftp-mirror package written by Lee McLoughlin
<lmjm@doc.ic.ac.uk> when it is time to grab a new version of the broker
database.  As you start testing your own replica, you might want to
query an operating <A href="http://jurassic.usc.edu:9500/floodd">
floodd </A> and its corresponding mirrord <A
href="http://jurassic.usc.edu:4000"> mirrord </A>.

CONFIGURING A REPLICA
=====================

   Follow the steps to configure mirrord and replicate a broker.  These
instructions are written assuming that you want to replicate the
www-home-pages broker and that you will run this replica from directory
`/usr/local/mirrord'.

  1. `gunzip mirrord.tar.gz and tar xf mirrord.tar'

     This will leave you with the directory mirrord-dist.

  2. `cd mirrord-dist'

  3. `configure --prefix=/usr/local/mirrord'

     Note: without the `--prefix' argument, `configure' builds mirrord
     for installation in `/usr/local'.  *Don't use -prefix=~smith.  Use
     -prefix=/home/smith.*

  4. `make'

  5. `make install'

     Note: this will create and populate /usr/local/mirrord.

  6. `cd /usr/local/mirrord/lib/'

  7. `cp join.conf replica.conf'

     Configuration file `join.conf' is a template for joining  an
     existing replication group.

  8. `cd ~ftp; mkdir www-home-pages;'

     If not already enabled, you will need to enable anonymous FTP.
     Refer to your machine's man pages for `ftpd'.

     This installation guide assumes that your FTP directory is
     `/usr/local/ftp' and that your FTP directory is
     `/usr/local/ftp/www-home-pages'.

  9. `chown www-home-pages smith'

     Set directory protection so that it can be written by the user
     account under which you are going to run mirrord.   Here, we
     assume you will run mirrord from account `smith'.

 10. `ftp localhost; dir; quit;'

     *Verify that your anonymous ftpd returns times in GMT.*  You can
     check this by using anonymous ftp to connect to your server and
     issuing the `dir' command.  The date returned for any particular
     file should differ from the date returned by a `cd ~ftp; ls -l' ',
     unless your local timezone is GMT.  Triple check that the
     difference between the anonymous ftpd notion of the date and the
     file system notion of the date differs by your site's GMT offset.

     Explanation: To keep timestamps synchronized across multiple time
     zones, mirror exports all dates in GMT.  If one machine exports
     dates in its local time, your replica may cause havoc for the
     entire replica group.  On many UNIX systems, you can specify the
     timezone using the TZ environment variable.  If you needed to
     force your ftpd to use GMT times, please tell dante@usc.edu your
     solution.

 11. `vi /usr/local/mirrord/lib/replica.conf'

     Examine your `replica.conf' and substitute the
     CAPITALIZED-VARIABLE-NAMES with appropriate values for your
     installation.   To replicate the www-home-pages, substitute the
     following names wherever they appear in replica.conf.

        * MYHOST.LOCAL.DOMAIN: substitute your domain name

        * MASTER.OTHER.DOMAIN: powell.cs.colorado.edu

        * THE-GROUP-NAME: www-home-pages

        *  You should not need to change the following defaults unless
     some other daemon process has already allocated particular TCP
     ports or you decide to relocate the RootDirectory after your
     original `configure --prefix=/usr/local/mirrord':

        * Your replica DataPort = 9501

        * Your replica ClientPort  = 9500

        * Master DataPort = 9501

        * Master ClientPort =9500

        * Your RootDirectory

 12. `/usr/local/mirrord/bin/setup-replica MYHOST.LOCAL.DOMAIN'

     *Be sure to use your hostname for MYHOST.LOCAL.DOMAIN*.  This
     copies necessary files to directory /usr/local/mirrord/replica.

 13. `cd /usr/local/mirrord/replica;'

 14. `cp ../lib/mirrord.conf.ex mirrord.conf;'

 15. `vi mirrord.conf;'

     Substitute local values for the CAPITALIZED-VARIABLES. We know, the
     list looks formidable:

        * <LOCAL-DIRECTORY> specifies the full path name of the
          directory in which the broker's database is mirrored.  This
          should be /usr/local/ftp/www-home-pages.

        * <FTP-DIRECTORY> the <LOCAL-DIRECTORY> specifies the path name
          as seen by anonymous FTP.  This should be www-home-pages.

        * ADMIN-DIRECTORY specifies the directory where the mirror
          configuration files are kept.  This should be
          /usr/local/mirrord/replica.

        * <MIRROR-PROG> The mirror program that performs the actually
          fetch of a replica via anonymous ftp.  This should be
          /usr/local/mirrord/lib/perl/mirror.pl.

        * <MIRROR-ARGS> Arguments to pass to mirror.  Leave this alone
          unless you want to increment or decrement the degree of
          debugging.

        * <FLOOD> The name of the local floodd daemon.  This must be
          the local daemon, otherwise mirrord will not be able to finds
          its correct neighbors.  This should be
          MY.HOST.NAME:ClientPort  For example, warthog.usc.edu:9500

        * VERSION-FILE The full path name holding the version
          information for a replica as it is known on the local file
          system.  This should be /usr/local/ftp/www-home-pages/VERSION

        * FTP-VERSION-FILE The path name relative to an anonymous ftp
          login  that holds the VERSION file.  This should be
          www-home-pages/VERSION

 16. `# SKIP THIS STEP IF YOUR PERL INSTALLATION IS COMPLETE'

     If perl has not been completely installed on your system, you
     might need to copy the file `ftp-mirror/socket.ph' from the full
     harvest distribution to
     `/usr/local/mirrord/lib/perl/sys/socket.ph'.  The `socket.ph' file
     shipped is for SunOs4.1.3.  Your mileage may vary on other systems
     and you ought to have your sysadmin install perl correctly.

 17.    `cd /usr/local/mirrord/replica'

 18.    `/usr/local/mirrord/bin/floodd'

 19.    `/usr/local/mirrord/bin/mirrord'

 20. Check your <A href="http://localhost:9500"> floodd </A> and <A
     href="http://localhost:9500"> mirrord </A> home pages.

 21. Force a database update by buttoning your <A
     href="http://localhost:9500/synchronize"> mirrord synchronization
     page</A>.

 22. Force a topology update by buttoning <A
     href="http://localhost:9500/floodd/topology-force"> floodd
     topology force</A>.

 23. WARNING: MULTI-HOMED MACHINES

     When setting up floodd/mirrord on a multi-homed machine, check the
     floodd and mirrord pages to be sure that all sites are referring
     to your replica by a single IP address.

RUNNING A BROKER
================

 24. Create a broker with the program in  harvest/bin/CreateBroker.

     If you are installing the www-home-pages broker, you may want to
     install a WAIS index rather than a glimpse index.  We assume that
     you create this broker in directory
     /usr/local/httpd/htdocs/www-home-pages.

 25. `cd /usr/local/httpd/htdocs/www-home-pages/admin'

 26. `ln -s /usr/local/ftp/www-home-pages/admin/Registry  .'

 27. `cd ..'

 28. `ln -s /usr/local/ftp/www-home-pages/objects  .'

 29. `RunBroker'

     You will have to wait until mirrord copies your entire replica.
     For the www-home-page broker, this can take all night at 28,000
     baud or an hour on a faster network.

 30. Instruct the broker to index itself using the broker <A
     href="http://localhost:80/www-home-pages/admin/admin.html">
     administration page </A>.

 31. Query your <A
     href="http://localhost:80/www-home-pages/query.html"> replicated
     broker </A> to see that it's functioning.

