Provided by: echolot_2.1.8-6_all bug

NAME

       pingd.conf - configuration file for the Echolot ping daemon

DESCRIPTION

       The file pingd.conf sets configuration parameters for Echolot pingd(1).
       It is a Perl script that gets eval()ed from within pingd. It has to set
       the values in the $CONFIG hash.

OPTIONS

       REQUIRED OPTIONS

       sitename
           A short name for your site/pinger. It is used in the statistics
           produced.

                   Default: none
                   Example: 'sitename' => 'testsite',

       my_localpart
           The local part of the pinger's email address.

           In "pinger@remailer.example.com" the localpart is "pinger".

                   Default: none
                   Example: 'my_localpart' => 'pinger',

       my_domain
           The domain part (FQDN) of the pinger's email address.

           In "pinger@remailer.example.com" the domain part is
           "remailer.example.com".

                   Default: none
                   Example: 'my_domain' => 'remailer.example.com',

       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.

       SYSTEM SPECIFIC OPTIONS

       recipient_delimiter
           The recipient_delimiter parameter specifies the separator between
           user names and address extensions (user+foo).

           If it is an empty string Echolot does not make use of user defined
           mailboxes but rather encodes the message type etc in a
           Comment/Realname part of an address.

           The use of recipient_delimiter is strongly recommended if your MTA
           setup supports it.

                   Default: 'recipient_delimiter' => '+',
                   Example: 'recipient_delimiter' => '-',
                            'recipient_delimiter' => '',

           Example addresses:

           with + as a recipient delimiter:
            pinger+conf.1=1035540778=1dd23d97@example.org

           without recipient delimiter:
            pinger@example.org (conf.2=1035541597=3baa2ae5)

       dev_random
           Where to read strong random data from - currently used only for
           generating our secret.

                   Default: 'dev_random' => '/dev/random',

       dev_urandom
           Where to read weak random data from - currently used only for
           garbage generation.

                   Default: 'dev_urandom' => '/dev/urandom',

       sendmail
           Path to the sendmail binary. It is expected to accept the "-f" and
           "-t" parameters.

                   Default: 'sendmail' => '/usr/sbin/sendmail',
                   Example: 'sendmail' => '/usr/lib/sendmail',

       MAGIC NUMBERS

       hash_len [integer]
           Echolot uses email addresses of the form
           "foo+some_data=MAC@domain". MAC is a Message Authentication 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 pingd. Echolot uses MD5 as the MAC hash function.

           hash_len is the number of characters to include in the email
           address.

                   Default: 'hash_len' => 8,
                   Example: 'hash_len' => 4,

       seconds_per_day [integer]
           The length of one character in reliability and latency stats.  One
           character usually stands for exactly one day (hence the name of
           this config option).  Changing it in production use is probably a
           bad idea but shortening it might come in handy during debugging.

                   Default: 'seconds_per_day' => 24*60*60,

       stats_days [integer]
           How many days (or whatever you configured seconds_per_day to really
           be) to have in the stats.  This is 12 days.

                   Default: 'stats_days' => 12,

       NEW REMAILERS

       fetch_new [bool]
           Query new remailers for remailer-xxx replies by default.

                   Default: 'fetch_new' => 1,
                   Example: 'fetch_new' => 0,

       ping_new [bool]
           Ping new remailers by default.

                   Default: 'ping_new' => 1,
                   Example: 'ping_new' => 0,

       show_new [bool]
           Show new remailers in public stats by default.

                   Default: 'show_new' => 1,
                   Example: 'show_new' => 0,

       STATISTICS GENERATION

       separate_rlists [bool]
           Also build separate rlists with data from only DSA pings, only RSA
           pings and only unencrypted pings.

                   Default: 'separate_realists' => 0,
                   Example: 'separate_rlists' => 1,

       combined_list [bool]
           Build a combined list of all different stats too. While there is no
           standard format it is nice to read for the human eye.

                   Default: 'combined_list' => 0,
                   Example: 'combined_list' => 1,

       thesaurus [bool]
           Collect Thesaurus data and build Thesaurus Index.

                   Default: 'thesaurus' => 1,
                   Example: 'thesaurus' => 0,

       fromlines [bool]
           Build a summary of default From: header lines and list remailers
           which allow overriding them.

                   Default: 'fromlines' => 1,
                   Example: 'fromlines' => 0,

       stats_sort_by_latency
           In the statistics output remailers are sorted by reliability as the
           primary key.  The secondary key is usually nickname. If you prefer
           to sort by latency rather than nick set this to 1 (-1 if you want
           to reverse the order).

                   Default: 'stats_sort_by_latency' => 0,
                   Example: 'stats_sort_by_latency' => 1,

       TIMERS AND COUNTERS

       processmail [seconds]
           How often to process incoming email.

                   Default: 'processmail' => 60, # every minute
                   Example: 'processmail' => 5*60, # every 5 minutes

       buildstats [seconds]
           How often to build mlist etc.

                   Default: 'buildstats' => 5*60, # every 5 minutes
                   Example: 'buildstats' => 60*60, # hourly

       chainping_update [seconds]
           When building stats and we have chain pinging enabled (see
           do_chainpings), how often to rebuild chain stats.  This can be a
           CPU intensive task therefore it's not updated every time stats are
           built.

                   Default: 'chainping_update' => 4*60*60, # chain stats should never
                                                           #  be older than 4 hours

       buildkeys [seconds]
           How often to build keyrings.

                   Default: 'buildkeys' => 8*60*60, # every 8 hours
                   Example: 'buildkeys' => 24*60*60, # daily

       buildthesaurus [seconds]
           How often to update thesaurus index page.

                   Default: 'buildthesaurus' => 60*60, # hourly
                   Example: 'buildthesaurus' => 24*60*60, # daily

       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

       expire [seconds]
           How often to expire old keys, pings and remailers

                   Default: 'expire' => 24*60*60, # daily
                   Example: 'expire' => 8*60*60, # every 8 hours

       getkeyconf_interval [seconds]
       getkeyconf_every_nth_time [integer]
           How often to query remailers for new keys and configuration data
           (remailer-xxx). Some requests are sent every getkeyconf_interval
           seconds. The same request to the same remailer is sent only every
           getkeyconf_every_nth_time time.

                   Default: 'getkeyconf_interval'       => 5*60,    # send out requests
                                                                    #  every 5 minutes
                            'getkeyconf_every_nth_time' => 24*60/5, # send out the same
                                                                    #  request to the same
                                                                    #  remailer once a day
                   Example: 'getkeyconf_interval'       => 10*60,
                            'getkeyconf_every_nth_time' => 2*24*60/10, # new request every
                                                                       #  other day

       check_resurrection [seconds]
           How often to check assumed dead remailers for resurrection.

                   Default: 'check_resurrection' => 7*24*60*60, # weekly
                   Example: 'check_resurrection' => 14*24*60*60, # every other week

       pinger_interval [seconds]
       ping_every_nth_time [integer]
           How often to send pings. Pings are sent every pinger_interval
           seconds. The same remailer is pinged every ping_every_nth_time time
           pings are sent (This means the same remailer is pinged every
           pinger_interval * ping_every_nth_time seconds).  It is done this
           way in order to avoid spikes.

                   Default: 'pinger_interval'     => 5*60, # send out pings every 5 minutes
                            'ping_every_nth_time' => 24,   # send out pings to the same remailer every 24 calls, i.e. every 2 hours
                   Example: 'pinger_interval'     => 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

       chainpinger_interval [seconds]
       chainping_every_nth_time [integer]
       chainping_ic_every_nth_time [integer]
           How often to send chain pings. Chain-Pings are sent every
           chainpinger_interval seconds.  The same chain is pinged every
           chainping_every_nth_time time chain-pings are sent.  Chains in
           Intensive Care (ic), that are chains that are either known or
           believed to be bad or are not tested enough yet (see
           chainping_minsample), should be tested more often: They are checked
           every chainping_ic_every_nth_time time chain-pings are sent.

                   Default: 'chainpinger_interval'        => 5*60, # send out pings every 5 minutes
                            'chainping_every_nth_time'    => 2016, # send out pings to the same chain every 2016 calls, i.e. week
                            'chainping_ic_every_nth_time' => 288,  # send out pings to broken or unknown chains every 288 calls, i.e. daily

       addresses_default_ttl [integer]
           How many times to request remailer-xxx from a remailer (done every
           getkeyconf seconds, daily per default) without a reply before it is
           assumed dead.

                   Default: 'addresses_default_ttl' => 5, # getkeyconf seconds (days if getkeyconf is 24*60*60, the default)
                   Example: 'addresses_default_ttl' => 7,

       check_resurrection_ttl [integer]
           How many times to request remailer-xxx from an assumed dead
           remailer (done every 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,

       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 this time.

                   Default: 'prospective_addresses_ttl' => 5*24*60*60, # 5 days
                   Example: 'prospective_addresses_ttl' =>14*24*60*60, # 2 weeks

       reliable_auto_add_min [integer]
           How many different remailers need to list an address in a remailer-
           conf reply to get it committed to the list of remailer addresses.

                   Default: 'reliable_auto_add_min' => 6,
                   Example: 'reliable_auto_add_min' => 3,

       expire_keys [seconds]
           After how long 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

       expire_confs [seconds]
           After how long to expire received remailer-conf replies.

                   Default: 'expire_confs' => 5*24*60*60, # 5 days
                   Example: 'expire_confs' => 7*24*60*60, # 1 week

       expire_pings [seconds]
           After how long 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

       expire_chainpings [seconds]
           After how long to expire chain pings. This should probably be set
           to the same as chainping_period.

                   Default: 'expire_chainpings' => 12*24*60*60, # 12 days

       expire_thesaurus [seconds]
           After how long 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

       expire_fromlines [seconds]
           After how long to expire header From: lines.

                   Default: 'expire_fromlines' => 5*24*60*60, # 5 days
                   Example: 'expire_fromlines' => 7*24*60*60, # 1 week

       cleanup_tmpdir [seconds]
           How often to clean old files from the temp directory.
                Default: 'cleanup_tmpdir'   => 24*60*60, # daily

       metadata_backup [seconds]
           How often to make backups of metadata and rotate them. If gzip is
           set, backups are compressed.

                   Default: 'metadata_backup' => 8*60*60, # 8 hours
                   Example: 'metadata_backup' => 24*60*60, # daily

       metadata_backup_count [integer]
           How many backups of metadata to keep.

                   Default: 'metadata_backup_count' => 32, # keep the last 32 backups
                   Example: 'metadata_backup_count' => 4, # keep 4 rotations

       summary [seconds]
           How often to print a status summary to the log.

                   Default: 'summary' => 24*60*60, # daily
                   Default: 'summary' => 12*60*60, # twice a day

       DIRECTORIES AND FILES AND RELATED OPTIONS

       homedir
           The base directory of the Echolot installation. All other filenames
           and directory names are local to this directory. pingd changes into
           this directory upon startup.

                   Default: The directory in which pingd is.
                   Example: 'homedir' => '/home/pinger/echolot',

       mailin
           The Maildir directory or Mbox which is searched for new messages.

                   Default: 'mailin' => 'mail',
                   Example: 'mailin' => '/var/mail/echolot',

       mailerrordir
           The Maildir directory where messages are put that could not be
           parsed.

                   Default: 'mailerrordir' => 'mail-errors',

       save_errormails [bool]
           Whether to keep error messages at all

                   Default: 'save_errormails' => 0,
                   Example: 'save_errormails' => 1,

       resultdir
           The directory where statistics and keyrings are put.

                   Default: 'resultdir' => 'results',

       thesaurusdir
           The directory where Thesaurus data is put.

                   Default: 'thesaurusdir' => 'results/thesaurus',

       thesaurusindexfile
           The Thesaurus index file.

                   Default: 'thesaurusindexfile' => 'results/thesaurus/index',

       fromlinesindexfile
           The From Lines index file.

                   Default: 'fromlinesindexfile' => 'results/from',

       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.private',

       indexfilebasename
           The file to write the index.html to (relative to the result
           directory).

                   Default: 'indexfilebasename' => 'echolot',
                   Example: 'indexfilebasename' => 'index',

       gnupghome
           The directory which is used as temporary GnuPG home for all keyring
           and encryption/decryption actions.

                   Default: 'gnupghome' => 'gnupghome',

       gnupg
           Name of the GnuPG executable. If it is not in your PATH make sure
           to include path information.

           If gnupg is an empty string, the "GnuPG::Interface" default
           (usually gpg) is used.

                   Default: 'gnupg' => '',
                   Example: 'gnupg' => '/home/pinger/bin/myGnuPG',

       gzip
           Name of the gzip executable. If it is not in your PATH make sure to
           include path information.

                   Default: 'gzip' => 'gzip',

       mixhome
           The directory which is used as temporary Mixmaster home for all
           keyring and encryption/decryption actions.

                   Default: 'mixhome' => 'mixhome',
                   Example: 'mixhome' => '/home/pinger/Mix',

       mixmaster
           Name of the mixmaster executable. If it is not in your PATH make
           sure to include path information.

                   Default: 'mixmaster' => 'mix',
                   Example: 'mixmaster' => '/home/pinger/Mix/mix',

       tmpdir
           General purpose temp directory. Make sure it is not shared with
           other applications.

                   Default: 'tmpdir' => 'tmp',

       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',

       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',

       broken1
           File listing broken type I remailer chains. If it does not exist,
           the part is skipped in generated stats. Otherwise its content is
           copied in verbatim.

                   Default: 'broken1' => 'broken1.txt',
                   Example content:
                           (havenco cmeclax)
                           (frog3 nycrem)

       broken2
           File listing broken type II remailer chains. If it does not exist,
           the part is skipped in generated stats. Otherwise its content is
           copied in verbatim.

                   Default: 'broken2' => 'broken2.txt',
                   Example content:
                           (freedom lcs)
                           (* xganon)

       sameop
           File listing remailers that have the same operator or share a
           machine or other important infrastructure.  If it does not exist,
           the part is skipped in generated stats. Otherwise its content is
           copied in verbatim.

                   Default: 'sameop' => 'sameop.txt',
                   Example content:
                           (xganon2 xganon)
                           (cracker redneck)

       LOGGING

       logfile
           File to write logs to.  This file is reopened on SIGHUP.

                   Default: 'logfile' => 'pingd.log',
                   Example: 'logfile' => '/var/log/echolot/pingd.log',

       loglevel
           Minimum severity of messages to include in log file. Possible
           values are trace, debug, info, notice, warning, error, critical,
           alert, and emergency.

                   Default: 'loglevel' => 'info',
                   Example: 'loglevel' => 'debug',

       MISCELLANEOUS

       write_meta_files [bool]
           Whether to write meta files for each created file. These files
           include meta information for http servers and http clients like the
           date when a specific page expires.

                   Default: 'write_meta_files' => 1,

       meta_extension
           The extension that such metafiles (see above) should have.

                   Default: 'meta_extension' => '.meta',

       random_garbage [integer]
           Pings usually are quite short.  Some 100 bytes are sufficient to
           relay all the information that is required.  To make them not stand
           out that obviously, pings are padded using random garbage of random
           length.

           random_garbage is the top limit for the amount of bytes to add.
           The actual number is randomly generated and uniformly distributed
           over [0, random_garbage]

                   Default: 'random_garbage' => '8192',

       CHAIN PINGING

       do_chainpings [bool]
           Whether or not to do chain pings.  Chain pings test all chains of
           two remailers and come up with a list of broken chains.  This
           produces a non-trivial amount of traffic.

                   Default: 'do_chainpings' => 1,

       show_chainpings [bool]
           Show the results of our chainpinging in public stats.

                   Default: 'show_chainpings' => 1,

       chainping_fudge
           What proportion of the expected replies derived from one-hop stats
           must return before a chain is not declared broken.

                   Default: 'chainping_fudge' => 0.3, # if less than 0.3 * rel1 * rel2 make it, the chain is really broken

       chainping_grace
           The factor of time in addition to the guessed latency derived from
           one-hop stats before a chain ping is considered lost

                   Default: 'chainping_grace' => 1.5, # don't count pings sent no longer than 1.5 * (lat1 + lat2) ago

       chainping_period [seconds]
           What time frame is taken into account when calculating chain stats.
           This should probably be smaller than expire_chainpings.

                   Default: 'chainping_period' => 12*24*60*60, # 12 days

       chainping_minsample [seconds]
           Have at least as many sent (and not within grace) chain pings
           before declaring a chain broken.

                   Default: 'chainping_minsample' => 3, # have at least sent 3 pings before judging any chain

       chainping_allbad_factor
           How many chains "(A x)" must be bad before "(A *)" is listed.  The
           value is given as a proportion of all available remailers.

                   Default: chainping_allbad_factor => 0.5, # at least 50% of possible chains (A x) need to fail for (A *) to be listed in broken chains

       PINGING TYPES

       do_pings
           do_pings determines which ping types are sent.  It is a hash that
           has the following keys:

           cpunk-dsa
               Send out CPunk pings to CPunk remailers with their DSA key.

           cpunk-rsa
               Send out CPunk pings to CPunk remailers with their RSA key.

           cpunk-clear
               Send out unencrypted pings to CPunk remailers that don't have
               pgponly in their capsstring.

           mix Pings mixmaster remailers.

                   Default: 'do_pings' => {
                      'cpunk-dsa' => 1,
                      'cpunk-rsa' => 1,
                      'cpunk-clear' => 1,
                      'mix' => 1
                     },

       which_chainpings
           which_chainpings controls some aspects of chain pinging.  It's a
           hash over chaintypes - currently mix and cpunk.  Each entry is a
           reference to an array which specifies the preference for key types
           in that chaintype.

                   Default: which_chainpings => {
                      'cpunk' => [ qw{cpunk-dsa cpunk-rsa cpunk-clear} ],
                      'mix' => [ qw{mix} ]
                     },

           This means that in the case of cpunk chain pings we prefer using
           cpunk-dsa over cpunk-rsa which in turn we prefer to cpunk-clear.
           For mix there's only mix.

       pings_weight
           Not all pings have the same influence on the average reliability
           calcluated.  Very new pings don't count fully since there is some
           margin of error.  Similarly very old pings are not that interesting
           either.

           By default days 1 to 4 count fully (with weight 1), the older they
           are the less they count.

                   Default: pings_weight => [ qw{0.5 1.0 1.0 1.0 1.0 0.9 0.8 0.5 0.3 0.2 0.2 0.1 } ],

       TEMPLATES

       templates
           The template files are used to generate the HTML version of all
           Echolot output.  It is a hash of hashes which each have following
           keys: thesaurusindexfile, mlist, mlist2, rlist, rlist-rsa, rlist-
           dsa, rlist-clear, rlist2, rlist2-rsa, rlist2-dsa, rlist2-clear, and
           clist.

           The outer hash keys are for language selection.

                   Default: 'templates' => {
                       'default' => {
                               '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',
                       },
                       'de' => {
                              'thesaurusindexfile' => 'templates/thesaurusindex.de.html',
                              ....
                       },
                       'pl' => {
                              'thesaurusindexfile' => 'templates/thesaurusindex.pl.html',
                              ....
                       }
                     };

       echolot_css
           Location of the CSS file. This is copied to resultdir/echolot.css.

                   Default: 'echolot_css'               => 'templates/echolot.css',

       STRINGS

       remailerxxxtext
           The text to send along with remailer-xxx queries.  The template
           variables address and operator_address are substituted for their
           real values.

                   Default: 'remailerxxxtext' => "Hello,\n".
                       "\n".
                       "This message requests remailer configuration 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 immediately (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",

AUTHOR

       Peter Palfrader <peter@palfrader.org>

BUGS

       Please report them at
       <URL:http://alioth.debian.org/projects/echolot/<gt>