##################################################################### ## 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 ... 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.