REQUIREMENTS:

The Courier authentication library.

A super-server such as tcpserver or xinetd.


INSTALLATION:

Before building courierpassd, build and install courier-authlib, the
Courier authentication library.

To build and install courierpassd, unpack the tarball and follow these
commands.

cd /path/to/courierpassd-<version>
./configure
make
su root
make install

That's it. If you installed the authentication library in a non-standard
place, the configure script will complain. Just follow the instructions to
tell it where to find courierauthconfig, a program that is installed as
part of the authentication library.

Courierpassd configure options are:

	--with-minuid[=UID]
		Sets the minimum uid for which courierpassd
		will change the password. Below this uid,
		attempts to change a password will always
		fail. If this option is not used, or a uid
		not indicated, the value defaults to 100.

	--with-badpassdelay[=sec]
		Sets the time in seconds that courierpassd
		will sleep after a failed attempt to change
		a password. This option is intended to make
		brute force attacks against passwords harder
		to perform. This value defaults to 3.

Use ./configure --help to see the full range of available configure
options.

Courierpassd is installed in /usr/local/sbin.
The courierpassd man page is installed in /usr/local/man.

Courierpassd has been successfully built on:
    Debian 4.0
    Mandrake Linux 10.1
    FreeBSD 5.4, 6.1

For courierpassd to be of any use, the Courier authentication library
must be installed and user accounts set up which can be accessed by the
installed authentication modules. See the library documentation for
details on how to do this.


TROUBLESHOOTING BUILD ISSUES:

If make fails on your FreeBSD system, try using gmake. Gmake is available
in the FreeBSD ports tree. I haven't needed to use gmake on FreeBSD
5.X or 6.X.

If make fails with an error like this:

        courierauth.h: No such file or directory

then your compiler doesn't know where you keep your courier-authlib header
files. Find where courierauth.h is (look in /usr/local/include first) and
then set the CPPFLAGS environment variable to point to that directory. So
if courierauth.h is in /usr/local/include, set CPPFLAGS like so:

        CPPFLAGS=-I/usr/local/include


SUPER-SERVER SETUP:

Because courierpassd relies on a super-server to handle network connections,
it is easy to set up courierpassd to listen on whatever port is desired.
Since courierpassd uses the poppassd protocol to talk to clients, however,
the use of port 106 is recommended unless there is a compelling reason to
do otherwise.

A typical xinetd entry for courierpassd would look like this:

    service courierpassd
    {
            port            = 106
            socket_type     = stream
            protocol        = tcp
            user            = courier
            server          = /usr/local/sbin/courierpassd
            server_args     = -s imap
            wait            = no
            only_from       = 192.168.1.0 127.0.0.1
            instances       = 4
            disable         = no
    }

Courierpassd can also be used with tcpserver from the ucspi-tcp package
written by Dan Bernstein. A simple example of a courierpassd run script
would look like this:

    #!/bin/sh

    AUTHUID=`/usr/bin/id -u courier`
    AUTHGID=`/usr/bin/id -g courier`

    tcpserver -R -x /etc/tcprules.d/tcp.poppassd.cdb \
    -u "$AUTHUID" -g "$AUTHGID" 0 106 courierpassd -s imap &

If you use the daemontools package to control tcpserver, you can take
advantage of multilog and courierpassd's --stderr switch to provide
a consistent logging interface. In this case, the run script would look 
something like this:

    #!/bin/sh

    AUTHUID=`/usr/bin/id -u courier`
    AUTHGID=`/usr/bin/id -g courier`

    exec tcpserver -v -R -x /etc/tcprules.d/tcp.poppassd.cdb \
    -u "$AUTHUID" -g "$AUTHGID" 0 106 courierpassd -s imap --stderr 2>&1

And the corresponding log run script would look like this:

    #!/bin/sh

    exec multilog t /var/log/courierpassd

See the documentation that comes with ucspi-tcp and daemontools for
more information on how to use these packages and why you might want
to.


SECURITY CONSIDERATIONS:

The user you choose to run courierpassd as is determined by the ownership
of the directory in which the authdaemon domain socket, named 'socket',
resides. The location of the socket directory is listed in the
authdaemonrc configuration file as the parameter authdaemonvar.
You should run courierpassd as the user and group of this directory to
allow it to communicate with the authentication library.

Because courierpassd interacts with clients at remote locations,
careful thought must be given to access control.

When configuring the super-server, restrict the machines from which 
connections will be accepted. Restrict access to particular machines or
at least to particular subnets. If your network is protected by a firewall,
make sure the firewall blocks incoming requests to the port courierpassd
listens on.

Use of the --with-minuid configure option is highly recommended. The default
value of 100 should be seen as providing a minimal level of security which can
be improved upon. It is safest to peruse /etc/passwd and set minuid to the
lowest user account uid found there. On Linux systems, user accounts often
begin at uid 501 so setting minuid to 501 would be a good choice in this
situation. Under no circumstances should minuid be set to 0. The root account
has no business changing its password from across the network.

Using courierpassd means there will be plain text user IDs and passwords
transiting the network. If there is a possibility that passwords can be
captured on the wire by packet sniffers, use tunneling software such
as stunnel to encrypt the connection between server and clients.


FURTHER READING:

Use the command 'courierpassd --help' for a brief explanation of available
options. See the courierpassd man page for additional information.

