REQUIREMENTS:

Courier, either the full mail server or the IMAP server package.

A super-server such as tcpserver or xinetd.


INSTALLATION:

Courierpassd uses the standard configure, make, make install process for
building the software. Only three non-standard configure options are available,
details are given below.

Before building courerpassd, configure and build courier. If you are
using courier IMAP as opposed to the full courier mail server, you will
need to configure courier with the --with-authchangepwdir option set to
the path to install the authdaemon.passwd program in. Otherwise,
courierpassd will not be able to change user passwords. Even with the
above option set, you may need to manually copy the authdaemon.passwd
program to its desired destination. When building the full courier mail
server, authdaemon.passwd is installed by default.

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.

	--with-couriersrc=path
		Specifies the path to the courier source
		tree. This option must be included when
		configuring courierpassd.

Build courierpassd like so:

  ./configure --with-couriersrc=/path/to/courier/source/tree

				or
			
  ./configure --with-minuid=300 --with-couriersrc=/path/to/courier/source/tree

  make
  su - root
  make install

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

By default, courierpassd is installed in /usr/local/sbin.

Courierpassd has been successfully built on:
    Mandrake Linux 8.2, 9.0
    FreeBSD 4.6.2, 4.7

On FreeBSD, it is necessary to use gmake instead of make for the build.
Gmake is available in the FreeBSD ports tree.

For courierpassd to be of any use, courier (either the full
mail server or just the IMAP server) must be installed and user accounts
set up which can be accessed by the installed courier authentication
modules. See the courier documentation for details on how to do this.

The courierpassd man page is installed in /usr/local/man by default.


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 not
to do so.

A typical xinetd entry for courierpassd would look like this:

    service courierpassd
    {
            port            = 106
            socket_type     = stream
            protocol        = tcp
            user            = root
            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

    tcpserver -R -x /etc/tcprules.d/tcp.poppassd.cdb 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

    exec tcpserver -v -R -x /etc/tcprules.d/tcp.poppassd.cdb 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:

Because courierpassd runs as root and 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 it 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. 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 possability 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
switches. See the courierpassd man page for additional information.

