diff options
| -rw-r--r-- | NEWS | 1 | ||||
| -rw-r--r-- | TODO | 3 | ||||
| -rw-r--r-- | doc/pingd.conf.pod | 532 |
3 files changed, 534 insertions, 2 deletions
@@ -3,6 +3,7 @@ Changes in version * Added legend to templates (Orange) * Thesaurus building failed when an id did not return a valid remailer. A check was there bug it was wrong. + * Have pingd.conf.5 manpage documenting all options. Changes in version 2.0beta13 - 2002-07-13 * Have correct title tags and some layout changes in the HTML templates @@ -1,7 +1,6 @@ -$Id: TODO,v 1.31 2002/07/15 20:19:40 weasel Exp $ +$Id: TODO,v 1.32 2002/07/16 00:13:27 weasel Exp $ for 2.0: - document configuration options can be done later, nice if for 2.0: getkeyconf command could take option: address [address ...] diff --git a/doc/pingd.conf.pod b/doc/pingd.conf.pod new file mode 100644 index 0000000..190d6ee --- /dev/null +++ b/doc/pingd.conf.pod @@ -0,0 +1,532 @@ +=pod + +=head1 NAME + +pingd.conf - configuration file for the echolot ping daemon + +=head1 DESCRIPTION + +The file B<pingd.conf> sets configuration parameteres for the echolot pingd(1). +It is a perl script that gets eval()ed from withing pingd. It has to set the +values in the $CONFIG hash. + +=cut + +=head1 OPTIONS + +=head2 REQUIRED OPTIONS + +=over + +=item B<homedir> + +The base directory of the echolot installation. All other filenames and +directorynames are local to this directory. B<pingd> changes into this +directory upon startup. + + Default: none + Example: 'homedir' => '/home/pinger/echolot', + +=item B<sitename> + +A short name for your site/pinger. Is used in the statistics produced. + + Default: none + Example: 'sitename' => 'testsite', + +=item B<my_localpart> + +The local part of the pingers email address. + +In C<pinger@example.com> the localpart is C<pinger>. + + Default: none + Example: 'my_localpart' => 'pinger', + +=item B<my_domain> + +The domain part of the pingers email address. + +In C<pinger@example.com> the localpart is C<example.com>. + + Default: none + Example: 'my_domain' => 'example.com', + +=item B<operator_address> + +The email address of the human operator that runs this pinger. + + Default: none + Example: 'operator_address' => 'remop@example.org', + +It is used in several templates. + +=item B<Pinger::Mix> + +B<Pinger::Mix> has some information for C<Echolot::Pinger::Mix> +pinging module. It is a hash that has two keys: + +=over + +=item B<mix> + +The name (with complete path) of the mix binary. It is expected to support the +same command line options as the canonical mixmaster client/server by +Anonimizer Inc. + +=item B<mixdir> + +The directory where the files C<type2.list> and C<mixring.pub> are loated in. +C<Echolot::Pinger::Mix> will overwrite these files before sending any pings. + +=back + + Default: none + Example: 'Pinger::Mix' => { + 'mix' => '/home/pinger/Mix/mix', + 'mixdir' => '/home/pinger/Mix', + }, + + +=back + + + +=head2 SYSTEM SPECIFIC OPTIONS + +=over + +=item B<recipient_delimiter> + +The B<recipient_delimiter> parameter specifies the separator between user names +and address extensions (user+foo). + + Default: 'recipient_delimiter' => '+', + Example: 'recipient_delimiter' => '-', + +=item B<dev_random> + +Where to read random data from. + + Default: 'dev_random' => '/dev/random', + Example: 'dev_random' => '/dev/urandom', + +=item B<sendmail> + +Path to the sendmail binary. It is expected to accept the C<-f> and C<-t> +parameters. + + Default: 'sendmail' => '/usr/sbin/sendmail', + Example: 'sendmail' => '/usr/lib/sendmail', + +=back + + + +=head2 MAGIC NUMBERS + +=over + +=item B<hash_len> [integer] + +Echolot uses email addresses like C<foo+some_data=MAC@domain>. MAC +is Message Authentification Code used to verify that the address +was actually generated by this pinger using a secret which is set +from random data the first time you run B<pingd>. Echolot uses MD5 +as the MAC hash function. + +B<hash_len> is the number of characters to include in the email address. + + Default: 'hash_len' => 8, + Example: 'hash_len' => 4, + +=back + + + +=head2 NEW REMAILERS + +=over + +=item B<fetch_new> [bool] + +Query new remailers for remailer-xxx replies by default. + + Default: 'fetch_new' => 1, + Example: 'fetch_new' => 0, + +=item B<ping_new> [bool] + +Ping new remailers by default. + + Default: 'ping_new' => 1, + Example: 'ping_new' => 0, + +=item B<show_new> [bool] + +Show new remailers in public stats by default. + + Default: 'show_new' => 1, + Example: 'show_new' => 0, + +=back + + + +=head2 STATISTICS GENERATION + +=over + +=item B<seperate_rlists> [bool] + +Also build sperate rlists with data from only DSA pings, only RSA pings and +only plaintext pings. + + Default: 'seperate_rlists' => 0, + Example: 'seperate_rlists' => 1, + +=item B<combined_list> [bool] + +Build a combinded list of all different stats too. While this is no +standard format it is nice to read for a human eye. + + Default: 'combined_list' => 0, + Example: 'combined_list' => 1, + +=item B<thesaurus> [bool] + +Collect Thesaurus data and build Thesaurus' Index. + + Default: 'thesaurus' => 1, + Example: 'thesaurus' => 0, + +=back + + + +=head2 TIMERS AND COUNTERS + +=over + +=item B<processmail> [seconds] + +How often to process incoming email. + + Default: 'processmail' => 60, # every minute + Example: 'processmail' => 5*60, # every 5 minutes + +=item B<buildstats> [seconds] + +How often to build mlist et al. + + Default: 'buildstats' => 5*60, # every 5 minutes + Example: 'buildstats' => 60*60, # hourly + +=item B<buildkeys> [seconds] + +How often to build keyrings. + + Default: 'buildkeys' => 8*60*60, # every 8 hours + Example: 'buildkeys' => 24*60*60, # daily + +=item B<buildthesaurus> [seconds] + +How often to update thesaurus index page. + + Default: 'buildthesaurus' => 60*60, # hourly + Example: 'buildthesaurus' => 24*60*60, # daily + +=item B<commitprospectives> [seconds] + +How often to check for prospective new remailer addresses and +commit them to the list of remailers. + + Default: 'commitprospectives' => 8*60*60, # every 8 hours + Example: 'commitprospectives' => 24*60*60, # daily + +=item B<expire> [seconds] + +How often to expire old keys, pingds and remailers + + Default: 'expire' => 24*60*60, # daily + Example: 'expire' => 8*60*60, # every 8 hours + +=item B<getkeyconf> [seconds] + +How often to query remailers for new keys and configuration data +(remailer-xxx). + + Default: 'getkeyconf' => 24*60*60, # daily + Example: 'getkeyconf' => 2*24*60*60, # every other day + +=item B<check_resurrection> [seconds] + +How often to check assumed dead remailers for resurrection. + + Default: 'getkeyconf' => 7*24*60*60, # weekly + Example: 'getkeyconf' => 24*24*60*60, # every other week + +=item B<pinger_interval> [seconds] + +=item B<ping_every_nth_time> [integer] + +How often to send pings. Pings are sent every B<pinger_interval> seconds. The +same remailer is pinged every B<ping_every_nth_time>. This is done this way in +order to avoid spikes. + + Default: 'pinger_interval' => 5*60, # send out pings every 5 minutes + 'ping_every_nth_time' => 48, # send out pings to the same remailer every 48 calls, i.e. every 4 hours + Example: 'pinger_interval' => 60*60, # send out pings every minute + 'ping_every_nth_time' => 60, # send out pings to the same remailer every 60 calls, i.e. every hour + +=item B<addresses_default_ttl> [integer] + +How many times to request remailer-xxx from a remailer (done every +B<getkeyconf> seconds, daily per default) without a reply before it is asumed +dead. + + Default: 'addresses_default_ttl' => 5, # getkeyconf seconds (days if getkeyconf is 24*60*60, the default) + Example: 'addresses_default_ttl' => 7, + +=item B<check_resurrection_ttl> [integer] + +How many times to request remailer-xxx from a assumed dead remailer (done every +B<check_resurrection> seconds, weekly per default) without a reply before it is +really considered dead. + + Default: 'check_resurrection_ttl' => 8, # check_resurrection seconds (weeks if check_resurrection is 7*24*60*60, the default) + Example: 'check_resurrection_ttl' => 4, + +=item B<prospective_addresses_ttl> [seconds] + +How long to keep information about a prospective address in the database. +Addresses that are not committed to the list of remailer addresses are +expired after that time. + + Default: 'prospective_addresses_ttl' => 5*24*60*60, # 5 days + Example: 'prospective_addresses_ttl' =>14*24*60*60, # 2 weeks + +=item B<reliable_auto_add_min> [integer] + +How many different remailer need to list an address in Reliable's remailer-conf +reply to get it committed to the list of remailer addresses. + + Default: 'reliable_auto_add_min' => 3, + Example: 'reliable_auto_add_min' => 5, + +=item B<expire_keys> [seconds] + +After which time to expire received keys if they were not updated +by remailer-key replies. + + Default: 'expire_keys' => 5*24*60*60, # 5 days + Example: 'expire_keys' => 7*24*60*60, # 1 week + +=item B<expire_confs> [seconds] + +After which time to expire received remailer-conf replies. + + Default: 'expire_confs' => 5*24*60*60, # 5 days + Example: 'expire_confs' => 7*24*60*60, # 1 week + +=item B<expire_pings> [seconds] + +After which time to expire pings. 12 is the value of choice +because that is the time frame the statistics show. You should +not make this smaller than 12 days. + + Default: 'expire_pings' => 12*24*60*60, # 12 days + +=item B<expire_thesaurus> [seconds] + +After which time to expire files in the thesaurus directory. + + Default: 'expire_thesaurus' => 21*24*60*60, # 2 weeks + Example: 'expire_thesaurus' => 7*24*60*60, # 1 week + +=back + + + +=head2 DIRECTORIES AND FILES + +=over + +=item B<mailindir> + +The Maildir directory which is searched for new messages. + + Default: 'mailindir' => 'mail', + +=item B<mailerrordir> + +The Maildir directory where messages are put that could not be parsed. + + Default: 'mailerrordir' => 'mail-errors', + +=item B<resultdir> + +The directory where statistics and keyrings are put. + + Default: 'resultdir' => 'results', + +=item B<thesaurusdir> + +The directory where Thesaurus data is put. + + Default: 'thesaurusdir' => 'results/thesaurus', + +=item B<thesaurusindexfile> + +The Thesaurus index file. + + Default: 'thesaurusindexfile' => 'results/thesaurus/index.html', + +=item B<private_resultdir> + +The directory where private stats and keyrings are put (Remailers that have +show set to false are shown here too). + + Default: 'private_resultdir' => 'results', + +=item B<gnupghome> + +The directory which is used as temporal GnuPG home for all keyring and +encryption/decryption actions. + + Default: 'gnupghome' => 'gnupg', + +=item B<tmpdir> + +General purpose temp directory. Make sure it is not shared with other +applications. + + Default: 'tmpdir' => 'tmp', + +=item B<commands_file> + +A file where commands to the daemon process are stored. The client +puts commands (like add a new remailer) in it and then sends a HUP +to the daemon process which reads and empties the file. + + Default: 'commands_file' => 'commands.txt', + +=item B<pidfile> + +The daemon's pid file. The daemon's Process ID is stored in this file. +As long as it exists pingd refuses to start up in daemon mode. + + Default: 'pidfile' => 'pingd.pid', + +=back + + + +=head2 PINGING TYPES + +=over + +=item B<do_pings> + +B<do_pings> determines which ping types are sent. +It is a hash that has the following keys: + +=over + +=item B<cpunk-dsa> + +Send out CPunk pings to CPunk remailers with their DSA key. + +=item B<cpunk-rsa> + +Send out CPunk pings to CPunk remailers with their RSA key. + +=item B<cpunk-clear> + +Send out plaintext pings to CPunk remailers that don't have pgponly +in their capsstring. + +=item B<mix> + +Pings mixmaster remailers. + +=back + + Default: 'do_pings' => { + 'cpunk-dsa' => 1, + 'cpunk-rsa' => 1, + 'cpunk-clear' => 1, + 'mix' => 1 + }, + +=back + + + +=head2 TEMPLATES + +=over + +=item B<templates> + +The template files are used to generate the HTML version of all echolot output. +It is a hash that has the following keys: +B<thesaurusindexfile>, +B<mlist>, +B<mlist2>, +B<rlist>, +B<rlist-rsa>, +B<rlist-dsa>, +B<rlist-clear>, +B<rlist2>, +B<rlist2-rsa>, +B<rlist2-dsa>, +B<rlist2-clear>, and +B<clist>. + + Default: 'templates' => { + 'thesaurusindexfile' => 'templates/thesaurusindex.html', + 'mlist' => 'templates/mlist.html', + 'mlist2' => 'templates/mlist2.html', + 'rlist' => 'templates/rlist.html', + 'rlist-rsa' => 'templates/rlist-rsa.html', + 'rlist-dsa' => 'templates/rlist-dsa.html', + 'rlist-clear' => 'templates/rlist-clear.html', + 'rlist2' => 'templates/rlist2.html', + 'rlist2-rsa' => 'templates/rlist2-rsa.html', + 'rlist2-dsa' => 'templates/rlist2-dsa.html', + 'rlist2-clear' => 'templates/rlist2-clear.html', + 'clist' => 'templates/clist.html', + }; + +=back + + + +=head2 STRINGS + +=over + +=item B<remailerxxxtext> + +The text to send along with remailer-xxx queries. +The tempalte variables address and operator_address are substituted for their +real values. + + Default: 'remailerxxxtext' => "Hello,\n". + "\n". + "This message requests remailer configation data. The pinging software thinks\n". + "<TMPL_VAR NAME=\"address\"> is a remailer. Either it has been told so by the\n". + "maintainer of the pinger or it found the address in a remailer-conf or\n". + "remailer-key reply of some other remailer.\n". + "\n". + "If this is _not_ a remailer, you can tell this pinger that and it will stop\n". + "sending you those requests immediatly (otherwise it will try a few more times).\n". + "Just reply and make sure the following is the first line of your message:\n". + " not a remailer\n". + "\n". + "If you want to talk to a human please mail <TMPL_VAR NAME=\"operator_address\">.\n", + +=back + +=cut |