REQUIREMENTS:

The Courier authentication library.

INSTALLATION:

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

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

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

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

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

Courieruserinfo is installed in /usr/local/sbin.
The courieruserinfo man page is installed in /usr/local/man.

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

For courieruserinfo to be of any use, the Courier authentication library
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.


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 courieruserinfo, it must be able to access the
authdaemon domain socket, named 'socket'. When courieruserinfo runs as
root, this presents no problem. However, if you need to run courieruserinfo
as a non-root user, you have three options, all of which require some
manual work.

Option 1: Add the user courieruserinfo 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 courieruserinfo will be run by only a small number of users.
If the authdaemon socket directory is owned by courier:courier and you
run courieruserinfo 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 courieruserinfo from such a program,
set the gid to the group ownership of the authdaemon socket directory.

Option 3: Change the permissions on courieruserinfo 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 courieruserinfo like so:

    chgrp courier courieruserinfo
    chmod g+s courieruserinfo

Be aware that this will allow any user on the system to access user
account information through courieruserinfo.

To mitigate possible security risks posed by running courieruserinfo
setgid, courieruserinfo cannot retrieve passwords.

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

FURTHER READING:

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

