$Id: README 631 2004-04-28 11:58:25Z weasel $
#####################################################################
##  R E A D M E   F O R   E C H O L O T   ###########################
#####################################################################

| Echolot, das: (German) sonic depth finder

PURPOSE
-------
Echolot is a Pinger for anonymous remailers such as Mixmaster

A Pinger in the context of anonymous remailers is a program that
regularly sends messages through remailers to determine their status.
Based on the responses, the Pinger calculates reliability statistics
which may be used by remailer clients to choose a chain of remailers to
use.

Furthermore, Echolot collects configuration parameters and keys of
remailers and offers the collected information in a format readable by
remailer clients.  This helps reduce the administration effort required
to use or host remailers.

This is Echolot2. Besides the name, author, and purpose, this software
has nothing to do with Echolot1.  Echolot2 has been written from
scratch.

LICENSE
-------
Please see the file named "LICENSE".


REQUIREMENTS
------------

o GnuPG (1.0.7 or higher required)
o Mixmaster http://mixmaster.sourceforge.net/
o Perl (5.8 or higher suggested)
o a local Mail Transfer Agent (MTA)
o Procmail (recommended)

The following perl modules:
o HTML::Template
o GnuPG::Interface (0.33 or higher required)
o Data::Dumper (should be part of perl-base)
o Digest::MD5 (included in perl 5.8 or higher)

INITIAL SETUP
-------------

o Verify that gpg 1.0.7 or later is installed:
      # gpg -version

o If the required perl modules above are not yet installed on your
  system, or if you are not sure if these perl libraries are installed,
  please install or upgrade the libraries as follows.  Even if you
  already have these libraries installed, there is no harm in following
  this installation procedure anyway.

  Execute the install-perl-modules script from the tools directory. It
  makes use of the CPAN module to check whether you have the required
  modules installed and if not downloads and installs them for you.
      # tools/install-perl-modules

  If this command reports errors, please verify that you are using perl
  5.8 or higher and are connected to the Internet.

  [Note: if you operating system already has packages with the required
   libraries than those generally are preferred since they integrate better with
   your system.

   On Debian for instance the following command can be used to get
   everything that is required:
      # apt-get install libgnupg-interface-perl libhtml-template-perl
  ]

o Create a new user named pinger (You can use a different user name if
  you so desire. The remainder of this document assumes that Echolot has
  been installed as user pinger).

o Copy all Echolot files and directories to the directory
  ~pinger/echolot.

o Copy the pingd.conf.sample file to pingd.conf.

o Check the homedir setting and set sitename in pingd.conf to match your
  host.

o If the Mixmaster executable mix is not in your PATH, set the
  mixmaster config option in pingd.conf to point to your local
  installation of mixmaster. Echolot can use any accessible mixmaster
  binary, such as the mix binary of a remailer that may be installed on
  the same machine. (Frequently found in /home/remailer/Mix/mix.)

  Echolot will not share the Mixmaster pool or key rings with the
  existing Mixmaster installation. Instead, Echolot uses pools and
  keyrings as specified by the mixhome configuration option.

  If you prefer, you can build a second Mixmaster binary for the
  exclusive use of Echolot and place that binary in /home/pinger/Mix.
  There is no need to put configuration information or key rings into
  that directory - they will not get used.

o If the GnuPG executable gpg is not in your PATH, set the gnupg
  configuration option in pingd.conf.

o Set my_localpart and my_domain in pingd.conf to the appropriate values
  for your pinger. Mail to my_localpart@my_domain needs to reach
  Echolot.

o Make sure your MTA supports user defined mailboxes to ensure that
  email addressed to my_localpart+anything@my_domain will reach Echolot.

  If your MTA uses a character other than + to indicate a user defined
  extension, set recipient_delimiter accordingly in pingd.conf.

  If you are using postfix as your MTA, adding the following line to
  postfix.s main.cf file will enable user defined mailboxes:
      recipient_delimiter = +

  If you are using an MTA other than postfix, consult your MTA's
  documentation to determine how to enable user defined mailboxes.

  If it is not possible for you to have user defined mailboxes set
  recipient_delimiter to the empty string "" in pingd.conf. Echolot
  will then work around it (This is _not_ recommended).

o Echolot can read its incoming mail either from an mbox format mailbox
  or from a Maildir. The latter is preferred for technical reasons since
  a Maildir does not require file locking.

  Echolot's mailin configuration variable defines from which location
  mail is being read. The variable defaults to mail. If this is a
  directory, Maildir is assumed, otherwise mbox format is assumed.

  If you can only use mbox format for incoming email:
    Change the mailin config option to /var/spool/pinger (or
    wherever incoming email for user pinger is being spooled on your
    system).

  If you are able to use Maildir (recommended):
    Mail will be delivered to /home/pinger/echolot/mail, a Maildir
    mailbox.

    Create Echolot's Maildir:
      # mkdir /home/pinger/echolot/mail

    Make sure the directory owned by pinger:
      # chown pinger. /home/pinger/echolot/mail

    If you are using postfix as your MTA, add one of the following lines
      to postfix's main.cf file to enable the use of procmail depending
      where on your system procmail is located.
        mailbox_command = /usr/bin/procmail
        mailbox_command = /usr/local/bin/procmail

      Reload postfix for the changes to main.cf to take effect.
        # postfix reload

      With procmail now active in your MTA, save the following two lines
      as /home/pinger/.procmailrc to ensure that mail for Echolot will be
      stored in Echolot.s Maildir:

        :0
        $HOME/echolot/mail/

        (CAVEAT: the trailing slash is significant and may not be
         omitted!)

    If you are using qmail as your MTA, do the following:
        # echo "./echolot/mail/" > .qmail
        # touch .qmail-default

o Finally, double-check to make sure that all of Echolot.s files and
  directories are owed by user pinger.



RUNNING ECHOLOT FOR THE FIRST TIME
----------------------------------

o Obtain the email addresses of 4 reliable remailers. Once connected to
  the remailer network, Echolot will over time learn about other
  remailers in operation. You can find a list of email addresses of
  reliable remailers to seed Echolot.s auto-discovery feature at
  http://www.noreply.org/echolot/rlist2.txt

  This list was created by the Echolot program.

o As user pinger, open two terminal windows.

o Change into the directory where echolot is kept.
    $ cd echolot

o In the first terminal window, type:
    [ you may want to set the log level to 'debug' in pingd.conf
      to get an idea what exactly Echolot is doing ]

    $ ./pingd --detach start
    $ tail -f pingd.log

o In the second terminal window, type:
    $ ./pingd add <address1> <address2> <address3> ...

  You can also use the following shell magic to add all addresses from
  an existing rlist.txt or mlist.txt:
    $ grep \$remailer rlist.txt | cut -f 2 -d \< | cut -f 1 -d \> |
      xargs ./pingd add

  Monitor the first terminal in which you started pingd. You should see
  mention of email addresses being added.

o In the second terminal window, execute
    $ ./pingd getkeyconf

  This will request remailer key and configuration files from the
  remailers that you added in the previous step.

o pingd can be stopped with the command

    $ ./pingd stop



VERIFYING ECHOLOT's OPERATION
-----------------------------

o Wait a few minutes for Echolot to receive results back from the
  remailers that have been pinged

o Look at one of Echolot.s result pages with the web browser of your
  choice. For example:

    $ cd /home/pinger/echolot/results
    $ lynx mlist2.html

  The file should list several remailers.

  NOTE: Results for Type I remailers can be expected within minutes.
  Results for Type II remailers may take up to an hour to appear.



DAY-TO-DAY OPERATION
--------------------

o To run Echolot in the background, run
      $ ./pingd --detach start

o You can monitor the log file to obtain debugging output:
      $ tail -f pingd.conf

  Do not forget to set the appropriate log level in pingd.conf.

o The tools directory contains the pingctl wrapper for Echolot.
  The wrapper takes care of checking ulimits, userid, and cd'ing to the
  correct directory.

  To start Echolot at system startup, install this wrapper as an init
  script in /etc/init.d or /usr/local/etc/rc.d, or wherever your
  operating system stores System V-style initialization scripts. You can
  link this wrapper from the runlevel directories if your init is SysV
  style.

o Echolot puts its stats in the result directory. Echolot also produces
  an index file named echolot.html. If you want to use echolot.html as
  your webpage.s index page, create a symbolic link.
      $ ln -sf echolot.html index.html

  Alternatively, you can set the indexfilebasename option in pingd.conf
  to index (no .html extension).

o Echolot additionally produces .meta files by default. These files
  include extra headers that your http server should send to clients. If
  you are using Apache as your web sever, you can load the mod_cern_meta
  Apache module and set MetaFiles to "on". Please ensure that Apache's
  MetaSuffix matches your meta_extension setting (".meta" by default)
  and that MetaDir is set to ".". See your web server's documentation
  for more information on meta files.



CONFIGURATION
-------------

Consult the pingd.conf.5 manpage for documentation on the available
configuration options.

To obtain all available configuration options and their current value
run:
    $ ./pingd dumpconf

You will need to restart pingd after making changes to pingd.conf for
the changes to take effect.



CAVEATS
-------

Echolot will keep open all ping and metadata files. This means it needs
quite a few file descriptors (about 2 * total keys or 6 to 8 * remailers
plus some for perl). If you have a very strict ulimit for open files you
need to increase it. A ulimit of 512 should suffice. Obscure errors
experienced might be caused by a ulimit that has been set too low.

Please report bugs and feature requests at
    http://alioth.debian.org/projects/echolot/

The Echolot homepage can be found at
    http://www.palfrader.org/echolot/



ACKNOWLEDGEMENTS
----------------
	Orange Admin for contributing ideas and templates
	Lucky Green for (re)writing docs
	BiKiKii Admin for valuable feedback
	All testers of Echolot.