[minion-cvs] Move man pages to new doc/ directory

[nickm@seul.org (Nick Mathewson)]

Update of /home/minion/cvsroot/src/minion/doc
In directory moria.mit.edu:/tmp/cvs-serv5422/doc

Added Files:
	mixminion.1 mixminiond.8 mixminiond.conf.5 mixminionrc.5 
Log Message:
Move man pages to new doc/ directory

--- NEW FILE: mixminion.1 ---
.\" $Id: mixminion.1,v 1.1 2004/05/10 16:46:21 nickm Exp $
.\" Copyright (c) 2004 Nick Mathewson -- see LICENCE for licensing information
.\" "man mdoc.samples" for information on how to tag the document.
.\" Type nroff -mdoc mixminion.1 | less
.Dd March 7, 2004
.Dt MIXMINION 1 Anonymity
.Os GNU/Linux
.Sh NAME
.Nm mixminion
.Nd Type III anonymity client
.Sh SYNOPSIS
.Nm mixminion
.Bro Cm benchmarks | clean-queue | decode | flush | generate-surb | help |
.Cm import-server | inspect-queue | inspect-surbs | list-fragments |
.Cm list-servers | ping | purge-fragments | queue | reassemble | send |
.Cm shell | testvectors | unittests | update-servers | version Brc
.Op Ar command_options
.Op Ar command_args ...
.Pp
[...1045 lines suppressed...]
point of failure.)
.It
Automatic generation of dummy messages.
.It
Built-in network reliability testing ("pinging").
.El
.El
.Ss Reporting bugs
To report bugs, please use the Bugzilla pages at http://bugs.noreply.org/.
For other correspondence, please email <nickm@freehaven.net>.
For help in debugging, please try to send a copy of:
.Bl -bullet -offset indent -compact
.It
What command you were running.
.It
The complete error you got, including stack trace (if any).
.El
.Pp
If your error occurred on a running server, please make a copy of your
log--it might be helpful.

--- NEW FILE: mixminiond.8 ---
.\" $Id: mixminiond.8,v 1.1 2004/05/10 16:46:21 nickm Exp $
.\" Copyright (c) 2004 Nick Mathewson -- see LICENCE for licensing information
.\" "man mdoc.samples" for information on how to tag the document.
.\" Type nroff -mdoc mixminion.1 | less
.Dd March 20, 2004
.Dt MIXMINIOND 8 Anonymity
.Os GNU/Linux
.Sh NAME
.Nm mixminion
.Nd Type III anonymity server
.Sh SYNOPSIS
.Nm mixminiond Cm start
.Bk -words
.Op Fl -h | Fl \-help
.Op Fl -Q | Fl \-quiet
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Op Fl \-daemon | \-nodaemon
.Op Fl \-echo
.Op Fl \-severity= Ns Ar level
.Ek
.Pp
.Nm mixminion Cm stop
.Op Fl -h | Fl \-help
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Nm mixminion Cm reload
.Op Fl -h | Fl \-help
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Nm mixminion Cm republish
.Op Fl -h | Fl \-help
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Nm mixminion Cm DELKEYS
.Op Fl -h | Fl \-help
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Nm mixminion Cm stats
.Op Fl -h | Fl \-help
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Nm mixminion Cm upgrade
.Op Fl -h | Fl \-help
.Op Fl -f Ar file | Fl \-config= Ns Ar file
.Pp
.ti 2
Deprecated:
.Nm mixminion
.Bro Cm server-start | server-stop | server-reload | server-republish
.Cm server-DELKEYS | server-stats | server-upgrade  Brc
.Sh DESCRIPTION
Mixminion is software suite that lets you send and receive very
anonymous mail via the "Type III" remailer protocol.
.Xr mixminiond 8
is the standard interface for running a Mixminion server.
.Pp
To configure a Mixminion server, follow these steps.
.Bl -enum
.It
Optionally, create a separate account on your system for the mixminiond
user.  This step is recommended.
.It
Create a configuration file.  The easiest way to do this is by editing
the file
.Pa etc/mixminiond.conf
from the Mixminion distribution.  See
.Xr mixminiond.conf 5
for more information on configuration options.
.It
Install the configuration file in one of:
.Pa ~/.mixminiond.conf
.Pa ~/etc/mixminiond.conf , or
.Pa /etc/mixminiond.conf .
(You may store it elsewhere, but you will need to specify the location on the
command line when you start mixminion.)
.It
To start your server, run:
.Bk -words
.Nm mixminiond Cm start
.Op Fl f Ar path\ to\ mixminiond.conf
.Ek
.Pp
(The
.Fl f
option is only necessary if you placed the file somewhere besides one of the
default locations.)
.It
To try out your server, clients will need a copy of your server descriptor,
whose location is stored in a file named
.Pa current-desc
under your server's base directory.
.Pp
For example, if your mixminiond.conf file contains the line:
"Homedir: /home/mixminion/spool", then if you read the contents of
.Pa /home/mixminion/spool/current-desc ,
you will file a filename like
"/home/mixminion/spool/keys/key_0001_ServerDesc".
This file is your current server descriptor.
.Pp
To try using this server descriptor, send messages using the filename as part
of your path:
.D1 Ic mixminion send -t <addr> -P '<filename>,*2'
.It
When you're ready to advertise your server, edit 'mixminiond.conf' and set
the 'Publish' option to 'yes'.  When you restart your server, it will
advertise itself to the central directory.
.Pp
The first time you do this, your server will not be inserted automatically;
the directory server holds your server's information separately until I
confirm it (to prevent pseudospoofing).  Once your server is listed, future
updates will be get into the directory automatically.
.Pp
WARNING: We don't have statistics yet, so the system isn't robust in the
presence of unreliable servers in the directory.  Please don't publish a
server if you don't think you can keep it up for a good while.
.El
.Pp
Once invoked, the
.Nm mixminiond
process tries to perform all the tasks necessary to implement the Type III
anonymous remailer protocol correctly.  These include
.Bl -item
.It
Listening on a network port and accepting incoming Type III packets via
the "Mixminion Transfer Protocol" (MMTP).
.It
Decrypting, storing, re-ordering, delaying, and scheduling outgoing packets
for delivery.
.It
Delivering outgoing packets via MMTP.
.It
Delivering outgoing messages via email (SMTP).
.It
Discarding invalid packets.
.It
Reassembling fragmented messages before delivery.
.It
Advertising its presence to the directory server(s).
.It
Periodically downloading fresh directories.
.It
Generating new keys as its old ones expire.
.El
.Sh INVOKING MIXMINIOND
Like
.Xr mixminion 1 ,
.Nm mixminiond
expects as its first argument a command name, and expects options for that
command as subsequent arguments.  To invoke a specific command, call
.Ic mixminiond Ar command_name .
The supported commands are:
.Bl -tag -width ".Cm republish"
.It Cm start
Begin running a mixminiond process.  Depending on the value of the
.Va Daemon
variable in the configuration file, the process will run in the foreground,
or the background.
.It Cm stop
Safely shutdown a mixminiond process.  You can also do this by sending a KILL
signal to the process (on Unix).
.It Cm reload
Tell a mixminiond process to reload its configuration data.  You can also do
this by sending a HUP signal to the process (on Unix). (This isn't
implemented yet; right now,
.Nm mixminiond .Cm reload
only closes and re-opens the log files.)
.It Cm republish
Tell a mixminiond process to re-publish all of its server descriptors to the
directory servers, whether it has already done so or not.  This is almost
never necessary anymore.
.It Cm DELKEYS
Delete keys from the server's directory.  This can be handy for some forms of
disaster recovery, but is almost never necessary anymore.
.It Cm stats
Dump statistics for the server's current time period.  (Old statistics are
stored a file, configurable with the
.Va StatsFile
option in
.Xr mixminiond.conf 5 ).
.It Cm upgrade
Upgrade an older server's file formats.  The last forward-incompatible format
change was between 0.0.4 and 0.0.5, but future incompatible changes are
possible.  (Backward-incompatible format changes are a matter of course, and
will be for as long as the software is in alpha.)
.El
.Pp
Every command can take takes one or more options.  The supported options are
listed below, along with a summary of which command support them:
.Bl -tag -width "Ds"
.It Fl \-daemon
.Brq Nm mixminiond Cm start
Run the server in the background, no matter what the configuration file
requests.  (Unix only.)
.It Fl f Ar filename | Fl \-config= Ns Ar filename
.Brq all
Load the configuration file from the provided filename, instead of searching
in the usual places.
.It Fl \-echo
.Brq Nm mixminiond Cm start
Print log messages to standard output, even if the configuration file
requests otherwise.  For debugging.
.It Fl h | Fl \-help
.Brq all
Print a help message and exit.
.It Fl \-nodaemon
.Brq Nm mixminiond Cm start
Run the server in the foreground, no matter what the configuration file
requests. For debugging. (Unix only.)
.It Fl Q | Fl \-quiet
.Brq Nm mixminiond Cm start
Don't print non-error messages to standard output.
.It Fl \-severity= Ns Ar level
Log at the requested severity level, no matter what the configuration file
requests.
.El
.Sh ENVIRONMENT
Mixminion servers recognize the following environment variables:
.Bl -tag -width ".Ev MIXMINIONRC"
.It Ev http_proxy
If you use a proxy to access the web, you should set this variable
so that mixminion can use HTTP to download its directory.
.It Ev MM_NO_FILE_PARANOIA
If set, don't check file permissions on private files.
.El
.Sh FILES
The mixminion server stores its files in configurable locations, as
configured in
.Xr mixminiond.conf 5 .
In the list of files below, file locations are given relative to
configuration variables.  For example, if a file is named
.Pa fname
and is stored in a directory configured with the
.Va SomeDir
variable, we describe its location as:
.Pa ${SomeDir}/fname .
.Bl -tag -width ".Pa ${WorkDir}/dir/*"
.It Pa mixminiond.conf
Configuration file.  When
.Nm mixminiond
starts a new server, it checks in a list of standard file locations in order,
unless you use the
.Fl f
option to provide a different filename on the command line.  See
.Xr mixminiond.conf 5
for information on the file format.  The default search path is
.Bl -enum -compact
.It
.Pa $HOME/mixminiond.conf
.It
.Pa $HOME/etc/mixminiond.conf
.It
.Pa /etc/mixminiond.conf
.It
.Pa /etc/mixminion/mixminiond.conf
.El
.It Pa ${BaseDir}/current-desc
A file containing the name of the file holding the current server descriptor.
.It Pa ${BaseDir}/version
The version of the current file format used by this server.  Mixminion 0.0.7
uses "1001"; older software does not use a version at all.
.It Pa ${WorkDir}
Directory holding volatile non-key data.  This defaults to
.Pa ${BaseDir}/work
the
.Va WorkDir
variable is not set.
.It Pa ${WorkDir}/tls/dhparameters
Diffie-Hellman  parameters used for MMTP key exchange.
.It Pa ${WorkDir}/hashlogs/hash_*
Logs of packet hashes, used to prevent replay attacks.  These files may be
stored as Berkeley DB files, as GDBM files, as DBM files, or as flat text
files, depending on your Python configuration.  Each one corresponds to a
separate key set in
.Pa ${KeyDir} .
.It Pa ${WorkDir}/stats.tmp
Cache of server statistics from latest period, stored as a Python object.
Use the
.Nm mixminiond stats
command to see the contents of this file.
.It Pa ${WorkDir}/dir/*
Latest server directory, downloaded from the directory server.  Currently,
this is used to print useful nicknames for other servers.
.It Pa ${QueueDir}
Directory used to hold packets and messages.  Defaults to
.Pa ${WorkDir}/queues .
See "Pool Directories" below for information about files under this
directory.
.It Pa ${QueueDir}/incoming/
A pool directory holding packets that have been received via MMTP, but not
yet processed.
.It Pa ${QueueDir}/mix/
A pool directory holding packets that have been received and decrypted.
Packets are delayed in this directory for a while after receipt in order to
prevent blending attacks.
.It Pa ${QueueDir}/outgoing/
A pool directory holding packets for delivery via MMTP.
.It Pa ${QueueDir}/deliver/
A directory holding messages for file outgoing delivery, and files used by
various delivery modules to deliver those files.
.It Pa ${KeyDir}
A directory holding private key information.  Defaults to
.Pa ${BaseDir}/keys .
Every subdirectory of ${KeyDir} corresponds to a separate set of keys, with
its own lifetime.  The
.Nm mixminiond
server automatically generates new keys as necessary, and deletes them as
they expire.
.It Pa ${KeyDir}/identity.key
This server's long-term signing private key.
.It Pa ${KeyDir}/key_*/ServerDesc
A server descriptor corresponding to a single key set.
.It Pa ${KeyDir}/key_*/mix.key
A private key used to decrypt mix packets.
.It Pa ${KeyDir}/key_*/mmtp.key
A private key used for on-the-wire encryption.
.It Pa ${KeyDir}/key_*/mmtp.cert
An X.509 certificate chain used for on-the-wire encryption.
.It Pa ${KeyDir}/key_*/published
This file is present only if the corresponding server descriptor has been
published to a directory server.
.It Pa ${LogFile}
A file holding log messages generated by the
.Nm mixminiond
process.  The location defaults to
.Pa ${BaseDir}/log .
.It Pa ${PidFile}
A file holding the numeric process ID for the current
.Nm mixminiond
process.  While the server is running, this file is locked to prevent
multiple servers from running with the same configuration.  The location
defaults to
.Pa ${BaseDir}/pid .
.It Pa ${StatsFile}
A file holding a record of packet statistics for the server. The location
defaults to
.Pa ${BaseDir}/stats .
.El
.Pp
Note: the only one of these files you should ordinarily be modifying is
.Pa .mixminiond.conf .
.Ss "Pool Directories"
Most of the directories under
.Pa ${QueueDir}
store messages or packets with a standardized naming format.  Each file
begins with a prefix, followed by an underline, followed by a random string
of characters.  All file transitions are performed via the (atomic)
.Xr rename 2
operation, to prevent race conditions or data loss in the event of a crash.
The recognized prefixes are:
.Bl -tag -width "inmp"
.It inp
A message or packet being written to the filesystem.  If any of these are
found when the server starts, they are assumed to be incomplete messages from
a previous run and deleted.
.It msg
A message or packet.  These can either be stored as a raw file, or as a
"pickled" Python object, depending on the pool.  These formats are not
frozen yet.
.It rmv
A message or packet that has been scheduled for deletion.
.It crp
A corrupted file that, for some reason, could not be read.  These files are
not deleted automatically, since their presence implies a bug that needs to
be addressed.  If you find any of these, please report a bug.
.It inpm
Metadata being written; Corresponds to "inp".
.It meta
A metadata file for a given message.  These files are usually "pickled"
Python objects of some kind.  These formats are not frozen yet.
.It rmvm
Metadata being removed; Corresponds to "rmv".
.It crpm
Corrupted metadata; Corresponds to "crp".
.El
.Sh SEE ALSO
.Xr mixminion 1 ,
.Xr mixminiond.conf 5
.Sh AUTHORS
See the AUTHORS section in
.Xr mixminion 1
.Sh ACKNOWLEDGMENTS
The Mixminion software is by Nick Mathewson, with contributions by Roger
Dingledine, Brian Fordham, Lucky Green, Peter Palfrader, Robyn Wagner, Brian
Warner, and Bryce "Zooko" Wilcox-O'Hearn.
.Sh BUGS
Future releases will probably break backward compatibility with this release
at least once or twice.
.Pp
See the manpage for
.Xr mixminion 1
for information on other bugs, and instructions for reporting bugs.

--- NEW FILE: mixminiond.conf.5 ---
.\" $Id: mixminiond.conf.5,v 1.1 2004/05/10 16:46:21 nickm Exp $
.\" Copyright (c) 2004 Nick Mathewson -- see LICENCE for licensing information
.\" "man mdoc.samples" for information on how to tag the document.
.\" Type nroff -mdoc mixminion.1 | less
.Dd March 21, 2004
.Dt MIXMINIOND.CONF 5 Anonymity
.Os GNU/Linux
.Sh NAME
.Nm mixminiond.conf
.Nd Mixminion server configuration file
.Sh SYNOPSIS
.Bl -tag -width Ds -compact
.It Pa $HOME/mixminiond.conf
.It Pa $HOME/etc/mixminiond.conf
.It Pa /etc/mixminiond.conf
.It Pa /etc/mixminion/mixminiond.conf
.El
.Sh DESCRIPTION
.Nm mixminiond
reads its configuration first from the command line, then from its
configuration file, then from its built-in defaults.  To find a configuration
file, the software looks in the following locations:
.Bl -enum -offset indent -compact
.It
the configuration file specified with the command-line
.Fl f | Fl \-config
flag, if any.
.It
.Pa $HOME/.mixminiond.conf
.It
.Pa $HOME/etc/mixminiond.conf
.It
.Pa /etc/mixminiond.conf
.It
.Pa /etc/mixminion/mixminiond.conf
.El
.Pp
The file itself is line-based, with lines grouped into sections.  Blank line
and lines beginning with '#' are treated as comments.  All section headings
and entries must appear in the first column.
.Pp
Each non-comment line is either a section header, of the format
"[SectionName]", or an entry of the format "Key: Value".  Values may continue
on to later lines by indenting the lines after the first, as in an
RFC822-style message. All names are case-sensitive.  Unless otherwise noted,
sections and entries may appear in any order, but no section or entry may
appear more than once.
.Pp
We describe the recognized entry keys below, grouped by section.
.Ss The [Host] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm ShredCommand
A program (such as 'shred -u') used to securely delete files.
.Bq Default: use internal overwrite-and-delete functionality.
.It Cm EntropySource
A character device to provide secure random data for generating keys and
seeding the internal pseudorandom number generator.  Not used on Windows.
.Bo Default: try
.Pa /dev/random ,
.Pa /dev/srandom ,
and
.Pa /dev/random
in an appropriate order.
.Bc
.It Cm TrustedUser
The username of a user who should not trigger "file paranoia".  For example,
if
.Pa /home/
is owned by the user "system", setting "TrustedUser: system" would prevent
warnings on startup.
This option may appear more than once.
.Bq Default: none.
.It Cm FileParanoia
Boolean: If true, check file permissions on private files and directories and
their parents.
.Bq Default: yes
.El
.Ss The [Server] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm BaseDir
Location to store server files.  This is the only file location that you need
to specify; all others default to subdirectories of
.Pa ${BaseDir} .
Defaults to
.Pa /var/spool/minion .
.It Cm Homedir
An obsolete synonym for "BaseDir".
.It Cm LogFile
A file to hold the server log.  Defaults to
.Pa ${BaseDir}/log .
.It Cm StatsFile
A file to hold the server stats log.  Defaults to
.Pa ${BaseDir}/stats .
.It Cm KeyDir
Directory to hold the server's keys and certificates. Defaults to
.Pa ${BaseDir}/keys .
.It Cm WorkDir
Directory to hold volatile or large data, such as messages, replay logs, and
so on.  Defaults to
.Pa ${BaseDir}/work .
.It Cm QueueDir
Directory to hold messages and packets.  Defaults to
.Pa ${WorkDir}/queues .
.It Cm PidFile
File to hold the process identifier of the current server process. Defaults
to
.Pa ${BaseDir}/pid .
.It Cm LogLevel
The minimum severity of messages to send to the server's log; log messages
less severe than this will be ignored.  Recognized severities are:
.Bl -tag -width "ERROR"
.It FATAL
An unrecoverable error affecting the entire server and causing an immediate
shutdown.
.It ERROR
An unrecoverable error affecting a single packet or message.
.It WARN
A warning message.  This may reflect an error that has resulted in no lost
data, or a worrisome situation that may not actually be an error.
.It INFO
A non-error message describing server status.  Logging these messages should
not affect users' anonymity.
.It DEBUG
A verbose debugging message.  Logging these messages can fill up your disk
space, and keeping the logs can endanger users' anonymity.
.It TRACE
A hyper-verbose debugging message.  Logging these messages can fill up your
disk space rapidly, and keeping the logs will endanger users' anonymity.
.El
.Pp
LogLevel defaults to "WARN".
.It Cm EchoMessages
Boolean: should the server send log messages to standard output as well as to
the log file?  Used for debugging.  Defaults to "no".
.It Cm Daemon
Boolean: should the server start in the background?  (Not yet supported on
Windows.)  Defaults to "no".
.It Cm LogStats
Boolean: should the server keep track of packet statistics such as number of
packets received?  Defaults to "yes".
.It Cm StatsInterval
Interval: how often should the server flush packet statistics to disk?
Defaults to "1 day".
.\" .It Cm EncryptIdentityKey
.It Cm IdentityKeyBits
How large should the server's signing key be, in bits?  Must be between
2048 and 4096.  Defaults to "2048".
.It Cm PublicKeyLifetime
Interval: How often should the server rotate its public key?  Must be at
least one day.  Defaults to "30 days".
.It Cm PublicKeyOverlap
Interval: How long after a server's public key stops getting used should the
server continue to accept messages using that key?  Defaults to "24 hours".
.\" .It Cm EncryptIdentityKey
.It Cm Mode
Should the server relay messages or not? Currently, only "relay" is
supported.
.It Cm Nickname
What nickname should the others call the server? These nicknames must be
unique; must contain only letters, numbers, and hyphens; and must start with
a letter.  They should be easy to type, and not too long.  Once your server
has published its keys and been included in the directory, you can't change
its nickname without becoming a different server.
.It Cm Contact-Email
An email address that people can use to contact the server's administrator.
Generally, this email address should not depend on the same computer or
network hosting the server it describes--otherwise, people will have no way
to tell the administrator if the network problems.
.It Cm Comments
A string to include in your server descriptor's "Comments" section.  You may
want to describe the server's stability, policies, and so forth.
.\" .It Cm ModulePath
.\" .It Cm Module
.It Cm MixAlgorithm
What approach should the server use to delay messages in its Mix pool and
prevent blending attacks?  The recognized algorithms are:
.Bl -tag -compact -width "DynamicPool"
.It Timed
Store messages as they arrive, and try to deliver all messages every time
.Va MixInterval
elapses.  Not secure, but useful for debugging.
.It DynamicPool
Store messages as they arrive.  Every time MixInterval elapses, sends
messages chosen at random, such that it always keeps MixPoolMinSize messages
in the pool, never sends unless it has over MixPoolMinSize messages, and
never sends more than MixPoolRate of the messages in the pool.  This
algorithm is also called "Cottrell" or "Mixmaster".
.It BinomialDynamicPool
Store messages as they arrive.  Every time MixInterval elapses, send a
\fIrandomly chosen\fP number of messages based on the number that DynamicPool
would send.  This algorithm is also called "Binomial" or "BinomialCottrell".
.El
Defaults to "Timed".
.It Cm MixInterval
How often should the server consider flushing messages from the mix pool?
See MixAlgorithm for more informatino.  Defaults to "30 min".
.It Cm MixPoolRate
Fraction: When running with the DynamicPool or BinomialDynamicPool algorithm,
how much of the pool do we flush at once?  See MixAlgorithm for more
information.  Setting this value too high can enable some blending attacks.
Defaults to "60%".
.It Cm MixPoolMinSize
Fraction: When running with the DynamicPool or BinomialDynamicPool algorithm,
how many messages do we try to keep in the pool? Setting this value too low
can enable some blending attacks.  See MixAlgorithm for more information.
Defaults to "5".
.It Cm Timeout
Interval: In general, how long do we wait for another computer to respond
on the network before assuming that it is down?  Defaults to "5 min".
.It Cm MaxBandwidth
Size: If specified, we try not to use more than this amount of network
bandwidth for MMTP per second, on average.
.It Cm MaxBandwidthSpike
Size: If specified, we try not to use more than this amount of network
bandwidth for MMTP per second, ever.
.El
.Ss The [DirectoryServers] Section
.Bl -tag -width ".Cm EntropySource"
.\" .It Cm ServerURL
.\" .It Cm PublishURL
.It Cm Publish
Boolean: should the server advertise itself to the directory servers?  Don't
turn this on until you want users to start using your server.  Defaults to
"no".
.Pp
Do \fInot\fP set this option to "yes" before you are reasonable confident
that you like your server's configuration, and that it will stay up for a
while.  In particular, please do not delete your server's keys after you have
published it, or else the directory will not accept your new keys.
.\" .It Cm MaxSkew
.El
.Ss The [Incoming/MMTP] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm Enabled
Boolean: should the server accept incoming packets? Must be "yes".
.It Cm Hostname
A public hostname that other servers can reach your host by resolving.  This
hostname \fImust\fP be reachable by others, or else they won't be able to
find your server.  Defaults to the result of
.Xr gethostname 3 .
.It Cm IP
The IP address your server will tell others to connect to.  Older versions
of Mixminion use this instead of
.Va Hostname .
If you don't provide this, Mixminion will try to guess your IP, but may
guess wrong.
.It Cm Port
The port your server will tell others to connect to.  Defaults to "48099".
.It Cm ListenIP
The IP address your server will \fIactually\fP listen on.  Use this option if
you are behind a firewall that forwards MMTP connections to your server.
Defaults to the value of
.Va IP .
.It Cm ListenPort
The Port your server will \fIactually\fP listen on.   Use this option if
you are behind a firewall that forwards MMTP connections to your server.
Defaults to the value of
.Va Port .
.\" .It Cm Allow
.\" .It Cm Deny
.\" .It Cm ListenIP6
.El
.Ss The [Outgoing/MMTP] Section
This section configures the outgoing connections your server uses to transmit
Type III packets.
.Bl -tag -width ".Cm EntropySource"
.It Cm Enabled
Should this server deliver packets via MMTP?  Must be "yes".
.It Cm Retry
RetrySchedule: how often, and for how long, should the server attempt to
deliver failing messages?  Defaults to "Every 1 hour for 1 day, every
7 hours for 5 days".
.It Cm MaxConnections
Integer: How many outgoing connections, at most, will the server try to open
at once?  Defaults to "16".
.\" .It Cm Allow
.\" .It Cm Deny
.El
.Ss The [Delivery/Fragmented] Section
This section configures server-side reassembly of fragmented messages.
.Bl -tag -width ".Cm EntropySource"
.It Cm Enabled
Boolean: Should the server reassemble fragmented messages at all? Default:
"no".
.It Cm MaximumSize
Size: What is the largest message size, after compression, that we will
try to reassemble?
.It Cm MaximumInterval
Interval: How long will the server hold fragments for a message before
giving up on the message?  Defaults to "2 days".
.El
.Ss The [Delivery/SMTP] Section
This section configures outgoing email delivery to final recipients.  (Note:
because Mixminion doesn't use email as a server-to-server transport, you do
\fInot\fP need to set this option if you're running a middleman server.)
.Bl -tag -width ".Cm EntropySource"
.It Cm Enabled
Boolean: Does the server support outgoing email?  Don't enable this unless
you have your ISP's permission to run a remailer that will send email to
arbitrary recipients.  Defaults to "no".
.It Cm Retry
RetrySchedule: How often, and for how long, should the server attempt to
send failed SMTP messages?  Defaults to "every 7 hours for 6 days".
.It Cm SendmailCommand
A command (possibly with options) to use for delivering outgoing messages.
When invoked, the command must accept an RFC822-encoded message from
standard input, terminated by an end of file.  It must learn the destination
and origin addresses from the message headers.  (If using sendmail, remember
to give the command as "sendmail -i -t".)
.It Cm SMTPServer
Hostname of the SMTP server that should be used to deliver outgoing
messages.  Defaults to "localhost".
.It Cm MaximumSize
Size: Largest message size (before compression) that we are willing to
deliver.  Defaults to "100K".
.It Cm AllowFromAddress
Boolean:  Do we allow user-configurable return addresses?  (Note that this
allows the user to set only the "Username" portion of the
\&'From: "[Anon] Username" <returnaddress>' header. Defaults to "yes".
.It Cm X-Abuse
What should the X-Abuse header of outgoing messages contain?
.It Cm Comments
What should the Comments header of outgoing messages contain?
.It Cm Message
If provided, a message to put before the content of any outgoing messages.
.It Cm FromTag
What should the 'tag' portion of outgoing return addresses contain?  Defaults
to "[Anon]".
.It Cm ReturnAddress
Must contain an email address to put in the "From" header of outgoing mail.
.It Cm BlacklistFile
The name of a file describing which outgoing addresses to support.  The file
format is line-based.  Lines starting with # and empty lines are ignored.
Whitespace is ignored.  All other lines take the format 'deny type value',
type is one of the following:
.Bl -tag -width "allhosts"
.It address
Match an email address, exactly. "Deny address fred@fred" matches "fred@fred"
and 'FRED@FRED'.
.It user
Match the part of an email address before the @, exactly.  "Deny user fred"
matches "fred@fred" and "fred@alice", but not "bob@fred" or "mr-fred@alice".
.It onehost
Match the part of an email address after the @, exactly.  "Deny onehost fred"
matches "bob@fred" but not "bob@fred.com" or "bob@host.fred".
.It allhosts
Match the part of an email address after the @, or any parent domain thereof.
"Deny allhosts fred.com" matches "bob@fred.com" and "bob@host.fred.com", but
not "bob@com".
.It pattern
match the email address if the provided regex appears anywhere in it.  "Deny
pattern /./" matches everything; "Deny pattern /(..)*/" matches all addresses
with an even number of characters.  See
.Xr perlre 1
for a description of the regular expression syntax.
.El
.El
.Ss The [Delivery/MBOX] Section
This section configures outgoing delivery to locally configured users via the
\'MBOX' module.
.Bl -tag -width ".Cm EntropySource"
.It Cm Enabled
Should the 'MBOX' module be enabled? Defaults to "no".
.It Cm AddressFile
The name of file contain mapping mbox names to email addresses.  The file
format is line-based.  Blank lines and lines starting with '#' are ignored.
All other lines must be of the format "mboxname: emailaddress@example.com".
.It Cm RemoveContact
A contact address that users can email to be removed from the address file.
.It Cm Retry, SendmailCommand, SMTPServer, MaximumSize, AllowFromAddress, \
X-Abuse, Comments, Message, FromTag, ReturnAddress
See the corresponding entries in the [Delivery/SMTP] section.
.El
.Ss The [Delivery/SMTP-Via-Mixmaster] Section
This section is deprecated; it allows you to use Mixmaster to deliver
anonymous messages via the Type I/II remailer network.  This feature was
useful when there were no Type III remailers that supported outgoing SMTP
delivery, but that time has long since passed.
.Ss Argument Formats
.Bl -tag -width ".Cm EntropySource"
.It Boolean values
Boolean values are case-insensitive. "Yes", "y", "1", "true", and "on" are
considered true; "No", "n", "0", "false" and "off" are considered false.
.It Intervals of time
Time intervals are given as a floating-point value, and a unit.  The units
may be single or plural.  Recognized units are "second", "sec", "minute",
"min", "hour", "day", "week", "month" (30 days), "mon", and "year" (365
days).  "1.5 hour", "90 min", "90 minutes", and "5400 sec" are all the same
value.
.It Sizes
Data sizes are given as a numeric value and a unit.  The units are
case-insensitive, and may be single or plural.  Recognized units are "b",
"byte", "octet", "K", "KB", "M", "MB", "G", and "GB".  If no units
are given, we default to "bytes".  "524288 bytes", "524288", "512K",
"512 KB", and ".5 MB" are all the same size.
.It Retry Schedules
Delivery retry schedules are given as a comma-separated series of elements.
An element may be either an Interval, which indicates a single retry attempt
after that interval has passed; or a string of the format "every <Interval1>
for <Interval2>", which retries with a period of Interval1 until Interval2
has passed.
.Pp
For example, "5 minutes, every 10 min for 1 hour, 1 day", makes one attempt
after 5 minutes, and 6 more attempts at ten-minute intervals thereafter, then
one final attempt 1 day after that.
.Pp
Note: New deliveries are only attempted when MixInterval has passed; if the
intervals in a RetrySchedule are smaller than the value of MixInterval, they
are interpreted to mean, "Retry at the earliest opportunity."
.It Fractions
A fraction may be given as a floating point value between 0.0 and 1.0, or
a percentage (followed by a single percent sign).
.El
.Sh EXAMPLE
See the mixminiond.conf file in the standard Mixminion distribution for an
example.
.Sh AUTHORS
See the AUTHORS section in
.Xr mixminion 1 .
.Xr mixminion 1
.Sh SEE ALSO
.Xr mixminion 1
.Xr mixminiond 8

--- NEW FILE: mixminionrc.5 ---
.\" $Id: mixminionrc.5,v 1.1 2004/05/10 16:46:21 nickm Exp $
.\" Copyright (c) 2004 Nick Mathewson -- see LICENCE for licensing information
.\" "man mdoc.samples" for information on how to tag the document.
.\" Type nroff -mdoc mixminion.1 | less
.Dd March 15, 2004
.Dt MIXMINIONRC 5 Anonymity
.Os GNU/Linux
.Sh NAME
.Nm mixminionrc
.Nd Mixminion client configuration file
.Sh SYNOPSIS
.Bl -tag -width Ds -compact
.It Pa $HOME/.mixminionrc
.It Pa $HOME/mixminionrc
.El
.Sh DESCRIPTION
.Nm mixminion
reads its configuration first from the command line, then from its
configuration file, then from its built-in defaults.  To find a configuration
file, the software looks:
.Bl -enum -offset indent -compact
.It
In the configuration file specified with the command-line
.Fl f | Fl \-config
flag, if any.
.It
.Pa $HOME/.mixminionrc
.It
.Pa $HOME/mixminionrc
.El
.Pp
If
.Nm mixminion
starts with no available configuration file, it creates one in the default
location.
.Pp
The file itself is line-based, with lines grouped into sections.  Blank line
and lines beginning with '#' are treated as comments.  All section headings
and entries must appear in the first column.
.Pp
Each non-comment line is either a section header, of the format
"[SectionName]", or an entry of the format "Key: Value".  All names are
case-sensitive.  Unless otherwise noted, sections and entries may appear in
any order, but no section or entry may appear more than once.
.Pp
We describe the recognized entry keys below, grouped by section.
.Ss The [Host] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm ShredCommand
A program (such as 'shred -u') used to securely delete files.
.Bq Default: use internal overwrite-and-delete functionality.
.It Cm EntropySource
A character device to provide secure random data for generating keys and
seeding the internal pseudorandom number generator.  Not used on Windows.
.Bo Default: try
.Pa /dev/random ,
.Pa /dev/srandom ,
and
.Pa /dev/random
in an appropriate order.
.Bc
.It Cm TrustedUser
The username of a user who should not trigger "file paranoia".  For example,
if
.Pa /home/
is owned by the user "system", setting "TrustedUser: system" would prevent
warnings on startup.
This option may appear more than once.
.Bq Default: none.
.It Cm FileParanoia 
Boolean: If true, check file permissions on private files and directories and
their parents.
.Bq Default: yes
.El
.Ss The [User] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm UserDir
Location to store a user's queued packets, cached directories, and so on.
.Bo Default:
.Pa $HOME/.mixminion/
.Bc
.El
.Ss The [Security] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm SURBAddress
Default address to use when generating SURBs without the
.Fl t
option.
.Bq Default: none
.It Cm SURBLifetime
Default lifetime for generated SURBs.
.Bq Default: 7 days
.It Cm ForwardPath
Default path to use when generating forward (non-reply, non-SURB) packets.
.Bq Default: ~5
.It Cm ReplyPath
Default path to use when generating reply packets.
.Bq Default: ~5
.It Cm SURBPath
Default path to use when generating SURBs.
.Bq Default: ~5
.It Cm BlockServers
A list of servers that should not be used when choosing random servers in
path generation.  This option may appear more than once.  This servers will
still be used if specifically requested.
.Bq Default: none
.It Cm BlockEntries
A list of servers that should not be used when choosing a random first server
in path generation.  This option may appear more than once.  This servers will
still be used if specifically requested.
.Bq Default: none
.It Cm BlockExits
A list of servers that should not be used when choosing a random last server
in path generation.  This option may appear more than once.  This servers will
still be used if specifically requested.
.Bq Default: none
.El
.Ss The [DirectoryServers] Section
.Bl -tag -width ".Cm EntropySource"
.\" .It Cm ServerURL
.\" .It Cm MaxSkew
.It Cm DirectoryTimeout
Maximum interval to wait for an answer when downloading a directory.
.Bq Default: 1 minute.
.El
.Ss The [Network] Section
.Bl -tag -width ".Cm EntropySource"
.It Cm ConnectionTimeout
Maximum length of time to wait for an answer when opening a connection to a
remote server.
.Bq Default: 2 minutes
.El
.Ss Argument Formats
.Bl -tag -width ".Cm EntropySource"
.It Boolean values
Boolean values are case-insensitive. "Yes", "y", "1", "true", and "on" are
considered true; "No", "n", "0", "false" and "off" are considered false.
.It Intervals of time
Time intervals are given as a floating-point value, and a unit.  The units
may be single or plural.  Recognized units are "second", "sec", "minute",
"min", "hour", "day", "week", "month" (30 days), "mon", and "year" (365
days).  "1.5 hour", "90 min", "90 minutes", and "5400 sec" are all the same
value.
.It Lists
Lists of servers are separated by commas.  Space is permitted, but not
required.
.It Paths
The
.Cm ForwardPath , ReplyPath ,
and
.Cm SURBPath
entries expect path specifiers.  See
.Xr mixminion 1
for information on the proper format.
.El
.Sh EXAMPLE
.Bd -literal
[Host]
# Don't try to overwrite files before removing them.
ShredCommand: rm -f
# Read entropy from /dev/urandom
EntopySource: /dev/urandom

[DirectoryServers]
DirectoryTimeout: 1 minute

[User]
# Store data in ~/share/mixminion/, instead of ~/.mixminion/
UserDir: ~/share/mixminion/

[Security]
SURBAddress: my-address@example.com
ForwardPath: ~5,FavoriteExit
ReplyPath: ~3,FavoriteExit
SURBPath: *3,FavoriteExit
BlockServers: insecure, malicious, nasty

[Network]
ConnectionTimeout: 180 seconds
.Ed
.Sh AUTHORS
See the AUTHORS section in
.Xr mixminion 1
.Sh SEE ALSO
.Xr mixminion 1
.Xr mixminiond 8