[minion-cvs] and another man page

[nickm@seul.org (Nick Mathewson)]

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

Added Files:
	mixminiond.8 
Log Message:
and another man page

--- NEW FILE: mixminiond.8 ---
.\" $Id: mixminiond.8,v 1.1 2004/03/23 00:08: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
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 mixminiod.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.