Document configuration options

1 files changed, 532 insertions, 0 deletions

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