REQUIREMENTS:

The Courier authentication library.

INSTALLATION:

Before building courierpasswd, build and install the Courier
authentication library.

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

cd /path/to/courierpasswd-<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.

The one courierpasswd specific configure option is:

        --with-minuid[=UID]
		Sets the minimum uid for which courierpasswd
	        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.

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

Courierpasswd is installed in /usr/local/sbin.
The courierpasswd man page is installed in /usr/local/man.

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

For courierpasswd 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


SECURITY CONSIDERATIONS:

In order to use courierpasswd, it must be able to access the
authdaemon domain socket, named 'socket'. When courierpasswd runs as
root, this presents no problem. However, if you need to run courierpasswd
as a non-root user, you have three options, both of which require some
manual work.

Option 1: Add the user courierpasswd will run as to the group that
owns the authdaemon socket directory in /etc/group. More than one user
can be added to the group vector in this way. This arrangement works
well if courierpasswd will be run by only a small number of users.
If the authdaemon socket directory is owned by courier:courier and you
run courierpasswd as user vmail, your /etc/group file will have a line
something like this:

    courier:x:465:vmail

Option 2: Some programs, such as tcpserver, allow you to separately set
the uid and gid of programs they call but don't honour the group vector
found in /etc/group. If you invoke courierpasswd from such a program,
set the gid to the group ownership of the authdaemon socket directory.
For tcpserver, you could do something like this:

    #!/bin/sh

    QMAILUID=`/usr/bin/id -u qmaild`
    COURIERGID=`/usr/bin/id -g courier`

    exec /usr/local/bin/tcpserver -u "$QMAILUID" -g "$COURIERGID" \
    0 smtp /var/qmail/bin/qmail-smtpd /usr/local/sbin/courierpasswd -- \
    /usr/bin/true 2>&1


Option 3: Change the permissions on courierpasswd to set gid to the
group ownership of the socket directory. Again, if the socket directory
is owned by courier:courier, change the ownership and permissions
of courierpasswd like so:

    chgrp courier courierpasswd
    chmod g+s courierpasswd

Be aware that courierpasswd does not provide any max-failed-retry
functionality so it is possible for local users to perform dictionary
attacks against account passwords if courierpasswd is set up this way.

The location of the authdaemon domain socket is listed in the
authdaemonrc configuration file as the parameter authdaemonvar.

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.


FURTHER READING:

Use the command 'courierpasswd --help' for a brief explanation of available
options. The man page provides more detailed information on how courierpasswd
works and how to use it.

