diff options
Diffstat (limited to 'trunk/README')
| -rw-r--r-- | trunk/README | 319 |
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. |