Previous TOC Next

Technical document: Linux Mail Server Howto
Chapter 4 - Installing authdaemond

Downloading, compiling and installing authdaemond

NOTE: If you are intending on using IMAP over SSL (strongly recommended), then you must first install development versions of OpenSSL or GnuTLS, before doing anything that follows. "Development" means the source code, not just the binaries. If you do not then support for ssl encryption will not be compiled into authdaemond and courier-imap.

authdaemond is the authentication daemon for courier-imap, and must be installed before courier-imap itself. As root:

> cd
> wget http://prdownloads.sourceforge.net/courier/courier-authlib-0.60.6.tar.bz2
> bunzip2 courier-authlib-0.60.6.tar.bz2
> tar -xvf courier-authlib-0.60.6.tar.bz2
> cd courier-authlib-0.60.6
> ./configure
> make
> make check
> make install-strip
> make install-configure

Assuming all these processes completed with no errors, authdaemond is now installed:

/usr/local/etc/authlib    - the configuration files.
/usr/local/sbin    - the authdaemond startup script; several utility programs (courierlogger, authconfig, authtest, authenumerate); and userdb scripts.
/usr/local/lib/courier-authlib    - various authentication modules, as shared libraries.
/usr/local/libexec/courier-authlib    - some miscellaneous stuff.
/usr/local/var/authdaemon    - a subdirectory that contains the filesystem socket which authdaemond listens on.
/usr/local/include    - a header file that Courier packages will use to build against courier-authlib.

Starting and stopping authdaemond

To manually start authdaemond:

> /usr/local/sbin/authdaemond start

authdaemond does NOT report to the shell any errors to indicate that startup failed. To check authdaemond is running, do:

> ps ax

and you should see amongst other processes something like:

19923 ?        S      0:00 /usr/local/sbin/courierlogger -pid=/usr/local/var/spool/authdaemon/pid
-start /usr/local/libexec/courier-authlib/authdaemond
19925 ?        S      0:00 /usr/local/libexec/courier-authlib/authdaemond
19926 ?        S      0:00 /usr/local/libexec/courier-authlib/authdaemond
19927 ?        S      0:00 /usr/local/libexec/courier-authlib/authdaemond
19928 ?        S      0:00 /usr/local/libexec/courier-authlib/authdaemond
19931 ?        S      0:00 /usr/local/libexec/courier-authlib/authdaemond
19932 ?        S      0:00 /usr/local/libexec/courier-authlib/authdaemond

If you do not see any entries for authdaemond, then it is not running. Check syslog:

> tail -20 /var/log/maillog

If you see:

authdaemond: /usr/local/libexec/courier-authlib/authdaemond: error while loading shared libraries: libltdl.so.3: cannot open shared object file: No such file or directory

This is becuase courier-authlib is looking in /usr/lib for the shared library libltdl.so.3, which may be actually installed elsewhere, possibly in /usr/local/lib. The easiest fix is to create a soft link:

> ln -s /usr/local/lib/libltdl.so.3 /usr/lib/libltdl.so.3

Now try starting authdaemond again. If authdaemond starts successfully you should see something like this in syslog:

Jul  4 14:38:56 roo10 authdaemond: modules="authuserdb authpam authldap authmysql authcustom authpipe", daemons=5
Jul  4 14:38:56 roo10 authdaemond: Installing libauthuserdb
Jul  4 14:38:56 roo10 authdaemond: Installation complete: authuserdb
Jul  4 14:38:56 roo10 authdaemond: Installing libauthpam
Jul  4 14:38:56 roo10 authdaemond: Installation complete: authpam
Jul  4 14:38:56 roo10 authdaemond: Installing libauthldap
Jul  4 14:38:56 roo10 authdaemond: Installation complete: authldap
Jul  4 14:38:56 roo10 authdaemond: Installing libauthmysql
Jul  4 14:38:56 roo10 authdaemond: Installation complete: authmysql
Jul  4 14:38:56 roo10 authdaemond: Installing libauthcustom
Jul  4 14:38:56 roo10 authdaemond: Installation complete: authcustom
Jul  4 14:38:56 roo10 authdaemond: Installing libauthpipe
Jul  4 14:38:56 roo10 authdaemond: Installation complete: authpipe

When it is up and running, you can do test authentications using authtest.

Authentication testing

The authtest module is included with authdaemond in order to facilitate easy authentication testing. Iniitially we are just going to test authentication of system users:

> /usr/local/sbin/authtest [user]

where [user] is a system username (without the square brackets!). If all is well you should see something like:

Authentication succeeded.

     Authenticated: [user]  (system username: [user])
    Home Directory: /home/[user]
           Maildir: (none)
             Quota: (none)
Encrypted Password: $hjhjdskGHjkhnHKhj898rrtyGjGHJ/
Cleartext Password: (none)
           Options: (none)
You can also do:

> /usr/local/sbin/authtest [user] [password]

to authenticate against their password.

If authdaemond is NOT running, and you attempt to authenticate then you will see an error like this:

> /usr/local/sbin/authtest user
ERR: authdaemon: s_connect() failed: Connection refused
Authentication FAILED: Illegal seek

(If you are authenticating via an imap login attempt, then a similar error will appear in the syslog)

authdaemond can be stopped doing:

> /usr/local/sbin/authdaemond stop

We discuss here setting up authdaemond to start at boot time.

Configuring authdaemond

The configuration file for authdaemond is located here:

/usr/local/etc/authlib/authdaemonrc

As well as a few other things, this file specifies the following:

  • The authentication mechanisms to use. There will be a line looking something like:

    authmodulelist="authuserdb authpam authldap authmysql authcustom authpipe"

    Each authentication mechanism will be tried in the order it is listed here, and authdaemond will authenticate if any of methods tried returns true. Very briefly, authdaemond enables authentication against a variety of sources. System users are authenticated with authpam, whilst virtual users can be authenticated with the following:

    • A Berkely database (authuserdb)
    • LDAP (authldap)
    • MySQL database (authmysql)
    • A custom authentication module (authcustom)
    • Or by piping to some external program (authpipe)

    When we come to discuss creating virtual users, we will consider only Berkeley databases for authentication, as this is the simplest to set up and perfectly legitimate for smaller scale systems. You should remove any authentication modules you will not be using from the line above. You can switch to using other databases at any later time.

  • The number of daemon processes to run. By default this is 5:

    daemons=5

    For a system hosting only a handful of mailboxes it is probably unnecessary to have five daemons, one or two should be sufficient. For systems hosting thousands of mailboxes more may be required. However in this instance note that the major performance bottleneck is likely to be RAM and CPU, and increasing the number of daemons may not be the optimal perfermance driver.

  • A debug level:

    DEBUG_LEVEL=0

    By default this is set to 0. When first setting up is probably a good idea to switch to 1 (Note: level 2 gives the same detail as level 1, but will also include any passwords in clear text). With the debug level set to 1 (or 2) lots of helpful verbose info is published to the syslog.

With authdaemond running and authenticating system users, it is time to install courier-imap.
Previous: Chapter 3 - Installing Postfix TOC Next: Chapter 5 - Installing courier-imap