summaryrefslogtreecommitdiff
path: root/trunk/README
diff options
context:
space:
mode:
Diffstat (limited to 'trunk/README')
-rw-r--r--trunk/README319
1 files changed, 319 insertions, 0 deletions
diff --git a/trunk/README b/trunk/README
new file mode 100644
index 0000000..6d62f2e
--- /dev/null
+++ b/trunk/README
@@ -0,0 +1,319 @@
+$Id$
+#####################################################################
+## 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.