1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
|
$Id: README 631 2004-04-28 11:58:25Z weasel $
#####################################################################
## 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.
|