diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 343 |
1 files changed, 225 insertions, 118 deletions
@@ -1,23 +1,28 @@ -$Id: README,v 1.31 2002/09/12 04:28:40 weasel Exp $ +$Id: README,v 1.32 2002/09/12 16:38:11 weasel Exp $ ##################################################################### ## R E A D M E F O R E C H O L O T ########################### ##################################################################### -| Echolot, das: German, sonic depth finder +| Echolot, das: (German) sonic depth finder -Echolot is a Pinger for anonymous remailers. +PURPOSE +------- +Echolot is a Pinger for anonymous remailers such as Mixmaster A Pinger in the context of anonymous remailers is a program that -regularily sends messages through remailers to check their reliability. -It then calculates reliability statistics which are used by remailer -clients to choose the chain of remailers to use. - -Additionally it collects configuration parameters and keys of all -remailers and offers them in a format readable by remailer clients. +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 has nothing -to do with Echolot1. It's written from scratch. +This is Echolot2. Besides the name, author, and purpose, this software +has nothing to do with Echolot1. Echolot2 has been written from +scratch. LICENSE ------- @@ -26,165 +31,267 @@ Please see the file named "LICENSE". REQUIREMENTS ------------ - in general: - Data::Dumper (should be part of perl-base) - Digest::MD5 (or perl >= 5.8) - HTML::Template - a local Mail Transfer Agent - for type1 pings - GnuPG ( >= 1.0.7) - GnuPG::Interface ( >= 0.33) - for type2 pings - a Mixmaster installation -Indirect requirements: - Class:MethodMaker (by GnuPG::Interface) - File::Spec (by HTML::Template, should be in more recent perl-base) +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. - If you have the CPAN perl module installed, you can use the - »install-perl-modules« script in the tools directory to download and - install the needed perl moduesl. + 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 -SETUP ------ + If this command reports errors, please verify that you are using perl + 5.8 or higher and are connected to the Internet. -o Create a new unix user named »pinger« (You can actually use any name - you wish but I will refer to the user as pinger in this document). +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 Make sure you have the perl libraries mentioned above and GnuPG - installed properly. +o Copy all Echolot files and directories to the directory + ~pinger/echolot. -o Copy all Echolot files and directories to ~pinger/echolot +o Copy the pingd.conf.sample file to pingd.conf. -o Copy/Rename the pingd.conf.sample file to pingd.conf. +o Check the homedir setting and set sitename in pingd.conf to match your + host. -o Check the homedir setting and set sitename in pingd.conf. +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.) -o If the Mixmaster executable »mix« is not in your PATH, set - the »mixmaster« config option in pingd.conf. + Echolot will not share the Mixmaster pool or key rings with the + existing Mixmaster installation. Instead, Echolot uses pools and key + rings as specified by the MIXPATH environment variable. FIXME - Echolot can use any available mixmaster binary (e.g. your remailer's mix). - It will not share pool or keyrings with the existing installation (it sets - the MIXPATH environment variable). - - If you prefer you can build one for Echolot and place it in ~/Mix. Don't - bother putting configuration or keyrings there though - they won't get used. + 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« config option in pingd.conf. +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. so that - my_localpart+anything@my_domain also reaches Echolot. - ^^^^^^^^^ - If you use another character instead of + to indicate a user defined - extension set recipient_delimiter accordingly in pingd.conf. +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. + +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/ - postfix: add »recipient_delimiter = +« to main.cf. + (CAVEAT: the trailing slash is significant and may not be + omitted!) -o Echolot can read its incoming mail either from a mbox format mailbox or from - Maildir. The latter is preffered for technical reasons (Maildir is superiour - to mbox because it does not require any locking). + If you are using qmail as your MTA, do the following: + # echo "./echolot/mail/" > .qmail + # touch .qmail-default - The »mailin« config variable defines where mail is read from. It defaults to - »mail«. If it's a directory, Maildir is assumed, mbox format otherwise. +o Finally, double-check to make sure that all of Echolot.s files and + directories are owed by user pinger. - Mbox: - It's probably best to change the »mailin« config option to - »/var/spool/pinger« (or whatever it is on your system). - Maildir (recommended): - Mail should be delivered to /home/pinger/echolot/mail which is a Maildir - mailbox, i.e there are 3 directories: /home/pinger/echolot/mail/tmp, - /home/pinger/echolot/mail/cur and /home/pinger/echolot/mail/new. Qmail, - postfix and procmail can do this. - Example snipped for procmail: +RUNNING ECHOLOT FOR THE FIRST TIME +---------------------------------- - :0 - $HOME/echolot/mail/ - - (the trailing slash is important!) +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. - Example for qmail: +o As user »pinger«, open two terminal windows. - echo "./echolot/mail/" > .qmail; - touch .qmail-default +o Change into the directory where echolot is kept. + $ cd echolot - - To use procmail with postfix set »mailbox_command = /usr/bin/procmail« - in main.cf. +o In the first terminal window, type: + $ ./pingd --verbose start -o Run »./pingd --verbose start«. +o In the second terminal window, type: + $ ./pingd add <address1> <address2> <address3> ... -o Run »./pingd add <address> <address> <address>..« in another terminal - look at the first terminal where you started pingd. It should print - something about adding addresses. + Monitor the first terminal in which you started pingd. You should see + mention of email addresses being added. -o Run »./pingd getkeyconf« to request new remailer-key and - remailer-conf immediatly. +o In the second terminal window, execute + $ ./pingd getkeyconf -o pingd can be stopped with »./pingd stop« or with Ctrl+C on the - terminal where it runs. + This will request remailer key and configuration files from the + remailers that you added in the previous step. -When everything works you may start pingd with +o pingd can be stopped with the command + + $ ./pingd stop -o »./pingd --detach --verbose start« + or by issuing a Ctrl+C in the terminal in which pingd is running. -o You can tail the output file to get the debugging output: - »tail -f output« -o In the tools directory you find the »pingctl« wrapper for Echolot. - It takes care of checking ulimits, userid and cd'ing to the right - directory. If you want you can install it as an init script in - /etc/init.d or similar and link it from the runlevel directories - if your init is SysV style. -o Echolot puts its stats in the result directory. It also produces - an index file name echolot.html. If you want to have it as your - default index page, symlink it to index.html with something like - »ln -s echolot.html index.html« in the result directory or set - the indexfilebasename option to index.html. +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 --verbose start + +o You can monitor the output file to obtain debugging output: + $ tail -f output + +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.html. + +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. + -o Echolot produces .meta files per default. These files include extra - headers that your http server should send to clients. With apache - you can load the mod_cern_meta module and set MetaFiles to "on". - [ make sure MetaSuffix matches your meta_extension setting (".meta" - by default) and MetaDir is set to "." ] CONFIGURATION ------------- -Consult the pingd.conf.5 manpage for documentation on configuration -options. +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. -To get all available configuration options and their current value run -»./pingd dumpconf«. -After changing pingd.conf you need to restart pingd. 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 + some for - perl). If you have a very strict ulimit for open files you need to increase it. - Something like 512 should be plenty. - If you get obscure errors this might probably be it. - +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://savannah.gnu.org/bugs/?group=echolot + http://savannah.gnu.org/bugs/?group=echolot + +The Echolot homepage can be found at + http://www.palfrader.org/echolot/ + -The Echolot homepage is at -http://www.palfrader.org/echolot/ ACKNOWLEDGEMENTS ---------------- Orange Admin for contributing ideas and templates + Lucky Green for (re)writing docs + All the testers of Echolot. The FSF for savanna.gnu.org. - All testers of Echolot. |