This package contains the beta distribution of the Anonymous Contact
Service (ACS) software. The software has been tested on only one system
(a Sun-2/120 running SunOS3.4.) YOU USE IT ENTIRELY AT YOUR OWN RISK.
This software is hereby placed in the public domain EXCEPT for
smail2.5, which carries its own copyright and distribution restrictions.
See the documentation in the mailer directory.

The ACS, in its current configuration, requires a system which has
either the dbm or ndbm libraries, Perl3.0pl18, smail2.5 and its mutant
brother, acsmail (provided in the distribution), a mail transport
agent which deals with /usr/lib/aliases properly (sendmail works,
smail2.5 and smail3.1.18 probably do), elm2.3 (but it should be 
easy to adapt other mail UA's to handle the bounced message handling),
and a news package which includes "inews" - Cnews works, B2.11.19
probably works.

WHAT IT DOES

is described in the "Intro" document in this directory. Read that.

HOW IT WORKS

/usr/lib/aliases contains aliases for acs-ping, acs-post, and each
anonymous user who has used the system. These aliases are pipes into
three suid root programs in the ACS source directory: anon-ping,
anon-post, and anon-reply. These programs dump their stdin into
uniquely named files in the ACS spool directory, except for anon-reply,
which writes the user's alias into the first line of the spool file
before dumping its stdin into the spool file. The files in the spool
directory are named PING#####, POST#####, or REP#####, depending on
which type of message they contain. The ##### is the pid of the
instance of anon-whatever that does the writing. (NOTE: there is a
potential bug here: on a very fast system which wraps around on its
process ids very quickly and doesn't unspool the incoming messages
frequently enough, older messages could be overwritten. Some better
"unique" file naming strategy is needed.)

The workhorse of the system is a Perl script called "unspool". This
is invoked by cron at regular intervals (I run it every 15 minutes)
to scavenge the contents of the spool directory and process the files
according to their type. unspool processes the files in the spool
directory by their type (REP, POST, then PING). For each message,
it extracts the user's address from the From: line, and checks to
see if that user has already been registered with the system. It does
this using the address as the key to a dbm database called "real2alias".
The data corresponding to the key is the user's alias. If the user
has not been registered, unspool creates an alias for the user of the
form "acs-..." where "..." is a sequential entry starting with "a" and
incrementing to "zzz" and beyond. (The last assigned alias is stored in
the file "alias-index" which unspool reads, increments, and writes as
needed.) unspool then adds the address:alias record to the real2alias
database, and appends a line for that user to the /usr/lib/aliases file
of the form 'acs-xxx:"|/usr/personals/anon-reply acs-xxx"'.

For additional information on how unspool works, see the documentation
in the code.

ADMINISTRATIVE FUNCTIONS

There are a number of scripts in this directory to help the ACS
administrator keep things running smoothly. They are:

addalias - add a new record to the real2alias database.

rmbyalias - remove a database record given the user's alias.

rmbyaddr - remove a database record given a user's address.

dupalias - check the database for duplicate aliases. This is needed
           if you accidentally delete unspool's lock file and 
           another instance of unspool starts up. 

fixit - a modified version of dbmrmbyalias.perl which creates
             a new instance of the database with one record removed.

listr2a - write the contents of real2alias on stdout. Each line
          contains a record of the form "alias:address".

nextalias - a pretty much useless way of finding out what the
                 next alias assigned will be. It's easier to cat
                 alias-index.

rebuild - rebuilds the real2alias database given the output of
		listr2a as input. Obviously, you have to checkpoint
		the listr2a output occasionally foor this to be useful.
		If you do, make damned sure its owned by root and
		not readable/writable by group or other.

MISCELLANEOUS

This directory includes three "Intro" files, which describe how to
use the ACS. Each one includes a header so they can be posted simply
by typing "inews -h < <Intro-file>". While the config.perl script
processes them to change references to my system, you'll still
probably need to tune them a bit for your purposes. "Intro" is the
long (definitive) version of the file, which is posted to several
newsgroups. "Intro2" is the same thing, but is only posted to
alt.personals. "Intro-short" is the short form version of the
instructions.

Dave Mack
{csu,acs-admin,acs-a}@alembic.ACS.COM
uunet!alembic!{csu,acs-admin,acs-a}
