Contents of /trunk/README

$Id: README,v 1.18 2002/07/16 01:37:17 weasel Exp $

Echolot is a Pinger for anonymous remailers.

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.


This is echolot2. Besides the name, author and purpose this has nothing
to do with echolot1. It's written from scratch.

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


REQUIREMENTS
------------
        in general:
                Data::Dumper (should be part of perl-base)
                Digest::MD5
                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)

SETUP
-----

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 Make sure you have the perl libraries mentioned above and GnuPG
  installed properly.

o Create a Mixmaster client installation in ~pinger/Mix echolot needs to
  have its own installation because it will mess with mix' mlist.txt
  file, the public Mixmaster keyring, and type2.list.  Don't bother
  putting current keyrings there.

o Copy all echolot files and directories to ~pinger/echolot

o Check the homedir setting and set sitename 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 or + to indicate a user defined
  extension set recipient_delimiter accordingly in pingd.conf.

o Mail should be delivered to /home/pinger/echolot/mail which must be 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:

    :0
    $HOME/echolot/mail/
  
  (the trailing slash is important!)


  Example for qmail:

    echo "./echolot/mail/" > .qmail;
    touch .qmail-default


o Run »./pingd --verbose start«.

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.

o Run »./pingd getkeyconf« to request new remailer-key and
  remailer-conf immediatly.

o pingd can be stopped with »./pingd stop« or with Ctrl+C on the
  terminal where it runs.

When everything works you may start pingd with

o »./pingd --detach --verbose start«

o You can tail the output file to get the debugging output:
  »tail -f output«


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

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

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.


Please report bugs and feature requests at
http://savannah.gnu.org/bugs/?group=echolot
1	$Id: README,v 1.18 2002/07/16 01:37:17 weasel Exp $
2
3	Echolot is a Pinger for anonymous remailers.
4
5	A Pinger in the context of anonymous remailers is a program that
6	regularily sends messages through remailers to check their reliability.
7	It then calculates reliability statistics which are used by remailer
8	clients to choose the chain of remailers to use.
9
10	Additionally it collects configuration parameters and keys of all
11	remailers and offers them in a format readable by remailer clients.
12
13
14	This is echolot2. Besides the name, author and purpose this has nothing
15	to do with echolot1. It's written from scratch.
16
17	LICENSE
18	-------
19	Please see the file named "LICENSE".
20
21
22	REQUIREMENTS
23	------------
24	in general:
25	Data::Dumper (should be part of perl-base)
26	Digest::MD5
27	HTML::Template
28	a local Mail Transfer Agent
29	for type1 pings
30	GnuPG (1.0.7)
31	GnuPG::Interface (0.33)
32	for type2 pings
33	a Mixmaster installation
34
35	Indirect requirements:
36	Class:MethodMaker (by GnuPG::Interface)
37
38	SETUP
39	-----
40
41	o Create a new unix user named »pinger« (You can actually use any name
42	you wish but I will refer to the user as pinger in this document).
43
44	o Make sure you have the perl libraries mentioned above and GnuPG
45	installed properly.
46
47	o Create a Mixmaster client installation in ~pinger/Mix echolot needs to
48	have its own installation because it will mess with mix' mlist.txt
49	file, the public Mixmaster keyring, and type2.list. Don't bother
50	putting current keyrings there.
51
52	o Copy all echolot files and directories to ~pinger/echolot
53
54	o Check the homedir setting and set sitename in pingd.conf.
55
56	o Set my_localpart and my_domain in pingd.conf to the appropriate values
57	for your pinger. Mail to my_localpart@my_domain needs to reach
58	echolot.
59
60	o Make sure your MTA supports user defined mailboxes. so that
61	my_localpart+anything@my_domain also reaches echolot.
62	^^^^^^^^^
63	If you use another character instead or + to indicate a user defined
64	extension set recipient_delimiter accordingly in pingd.conf.
65
66	o Mail should be delivered to /home/pinger/echolot/mail which must be a Maildir
67	mailbox, i.e there are 3 directories: /home/pinger/echolot/mail/tmp,
68	/home/pinger/echolot/mail/cur and /home/pinger/echolot/mail/new. Qmail,
69	postfix and procmail can do this.
70
71	Example snipped for procmail:
72
73	:0
74	$HOME/echolot/mail/
75
76	(the trailing slash is important!)
77
78
79	Example for qmail:
80
81	echo "./echolot/mail/" > .qmail;
82	touch .qmail-default
83
84
85	o Run »./pingd --verbose start«.
86
87	o Run »./pingd add <address> <address> <address>..« in another terminal
88	look at the first terminal where you started pingd. It should print
89	something about adding addresses.
90
91	o Run »./pingd getkeyconf« to request new remailer-key and
92	remailer-conf immediatly.
93
94	o pingd can be stopped with »./pingd stop« or with Ctrl+C on the
95	terminal where it runs.
96
97	When everything works you may start pingd with
98
99	o »./pingd --detach --verbose start«
100
101	o You can tail the output file to get the debugging output:
102	»tail -f output«
103
104
105
106	CONFIGURATION
107	-------------
108
109	Consult the pingd.conf.5 manpage for documentation on configuration
110	options.
111
112	To get all available configuration options and their current value run
113	»./pingd dumpconf«.
114
115	After changing pingd.conf you need to restart pingd.
116
117	CAVEATS
118	-------
119
120	- echolot will keep open all ping and metadata files. This means it needs quite
121	a few file descriptors (about 2 * total keys or 6 to 8 * remailers + some for
122	perl). If you have a very strict ulimit for open files you need to increase it.
123	Something like 512 should be plenty.
124	If you get obscure errors this might probably be it.
125
126
127	Please report bugs and feature requests at
128	http://savannah.gnu.org/bugs/?group=echolot