From 6c92176742282974bb206409c575350e8ab5dd51 Mon Sep 17 00:00:00 2001 From: Peter Palfrader Date: Tue, 16 Jul 2002 00:15:07 +0000 Subject: Document configuration options --- doc/pingd.conf.pod | 532 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 doc/pingd.conf.pod (limited to 'doc') 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 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 + +The base directory of the echolot installation. All other filenames and +directorynames are local to this directory. B changes into this +directory upon startup. + + Default: none + Example: 'homedir' => '/home/pinger/echolot', + +=item B + +A short name for your site/pinger. Is used in the statistics produced. + + Default: none + Example: 'sitename' => 'testsite', + +=item B + +The local part of the pingers email address. + +In C the localpart is C. + + Default: none + Example: 'my_localpart' => 'pinger', + +=item B + +The domain part of the pingers email address. + +In C the localpart is C. + + Default: none + Example: 'my_domain' => 'example.com', + +=item B + +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 + +B has some information for C +pinging module. It is a hash that has two keys: + +=over + +=item B + +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 + +The directory where the files C and C are loated in. +C 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 + +The B parameter specifies the separator between user names +and address extensions (user+foo). + + Default: 'recipient_delimiter' => '+', + Example: 'recipient_delimiter' => '-', + +=item B + +Where to read random data from. + + Default: 'dev_random' => '/dev/random', + Example: 'dev_random' => '/dev/urandom', + +=item B + +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 [integer] + +Echolot uses email addresses like C. 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. Echolot uses MD5 +as the MAC hash function. + +B 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 [bool] + +Query new remailers for remailer-xxx replies by default. + + Default: 'fetch_new' => 1, + Example: 'fetch_new' => 0, + +=item B [bool] + +Ping new remailers by default. + + Default: 'ping_new' => 1, + Example: 'ping_new' => 0, + +=item B [bool] + +Show new remailers in public stats by default. + + Default: 'show_new' => 1, + Example: 'show_new' => 0, + +=back + + + +=head2 STATISTICS GENERATION + +=over + +=item B [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 [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 [bool] + +Collect Thesaurus data and build Thesaurus' Index. + + Default: 'thesaurus' => 1, + Example: 'thesaurus' => 0, + +=back + + + +=head2 TIMERS AND COUNTERS + +=over + +=item B [seconds] + +How often to process incoming email. + + Default: 'processmail' => 60, # every minute + Example: 'processmail' => 5*60, # every 5 minutes + +=item B [seconds] + +How often to build mlist et al. + + Default: 'buildstats' => 5*60, # every 5 minutes + Example: 'buildstats' => 60*60, # hourly + +=item B [seconds] + +How often to build keyrings. + + Default: 'buildkeys' => 8*60*60, # every 8 hours + Example: 'buildkeys' => 24*60*60, # daily + +=item B [seconds] + +How often to update thesaurus index page. + + Default: 'buildthesaurus' => 60*60, # hourly + Example: 'buildthesaurus' => 24*60*60, # daily + +=item B [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 [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 [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 [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 [seconds] + +=item B [integer] + +How often to send pings. Pings are sent every B seconds. The +same remailer is pinged every B. 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 [integer] + +How many times to request remailer-xxx from a remailer (done every +B 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 [integer] + +How many times to request remailer-xxx from a assumed dead remailer (done every +B 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 [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 [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 [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 [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 [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 [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 + +The Maildir directory which is searched for new messages. + + Default: 'mailindir' => 'mail', + +=item B + +The Maildir directory where messages are put that could not be parsed. + + Default: 'mailerrordir' => 'mail-errors', + +=item B + +The directory where statistics and keyrings are put. + + Default: 'resultdir' => 'results', + +=item B + +The directory where Thesaurus data is put. + + Default: 'thesaurusdir' => 'results/thesaurus', + +=item B + +The Thesaurus index file. + + Default: 'thesaurusindexfile' => 'results/thesaurus/index.html', + +=item B + +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 + +The directory which is used as temporal GnuPG home for all keyring and +encryption/decryption actions. + + Default: 'gnupghome' => 'gnupg', + +=item B + +General purpose temp directory. Make sure it is not shared with other +applications. + + Default: 'tmpdir' => 'tmp', + +=item B + +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 + +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 + +B determines which ping types are sent. +It is a hash that has the following keys: + +=over + +=item B + +Send out CPunk pings to CPunk remailers with their DSA key. + +=item B + +Send out CPunk pings to CPunk remailers with their RSA key. + +=item B + +Send out plaintext pings to CPunk remailers that don't have pgponly +in their capsstring. + +=item B + +Pings mixmaster remailers. + +=back + + Default: 'do_pings' => { + 'cpunk-dsa' => 1, + 'cpunk-rsa' => 1, + 'cpunk-clear' => 1, + 'mix' => 1 + }, + +=back + + + +=head2 TEMPLATES + +=over + +=item B + +The template files are used to generate the HTML version of all echolot output. +It is a hash that has the following keys: +B, +B, +B, +B, +B, +B, +B, +B, +B, +B, +B, and +B. + + 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 + +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". + " 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 .\n", + +=back + +=cut -- cgit v1.2.3