Checkpassword LDAP

Checkpassword LDAP

Chkpassldap is a Perl checkpassword implementation suitable for qmail-ldap and Dovecot proxying clusters and beyond.

Download chkpassldap



Qmail run script:

/var/qmail/bin/qmail-smtpd /var/qmail/bin/ /bin/true 2>&1

Dovecot passdb checkpassword configuration:

args = /opt/bin/


Chkpassldap is a Perl implementation of D. J. Bernstein's checkpassword interface that authenticates and authorizes against LDAP. It is suited for SMTP-Auth via qmail, and any other applications that supports the standard checkpassword interface. Beyond simple auth, it is also capable of setting environment variables if required. This flexibility allows the interface to scale to other applications as well, such as the Dovecot POP/IMAP server.


Script requirements are as follows:

 Net::LDAP (from perl-ldap)
 Net::DNS (optional for enabling nslookups)

Installation consists of copying the script to the filesystem, for example in /opt/bin. The script then must be configured, and applications setup to make use of it.


Configuration is done in-script, changing variables at the top of the script. Most are self-explanatory, but all are described here.


Eenable or disable (1|0) logging to STDERR. Default: '1'


Increase the amount of debugging information to the log. Default: '0'


LDAP server IP address or name. TCP port can optionally be specified with trailing colon such as This must be set to suit your environment. Default: nothing useful

ldap_base people_base group_base

LDAP root search base and the people and group search bases. The search base must be set to suit your environment. The people and group bases are pretty typical but may need to be adjusted to suit your environment. Default: nothing useful


LDAP search scope. This determines how searches are conducted, with possible values sub, one, and base. The value sub will suffice for most sites. Default: 'sub'


LDAP group authorization. This is the cn of a group of which the user must be a memberuid. If not specified, no group restriction. Default: ''


LDAP attribute authorization. This is an attribute/value pairing which the user must possess, for example accountStatus=active. If not specified, no attribute restriction. Default: ''


Enable or disable (1|0) environment variable setting. Default: '0'


Configure how the environment is set. No effect if envset=0. See section ENVIRONMENT MODIFICATION.


Configurations for common applications which have been heavily tested with this script.


Qmail is almost always run out of daemontools run scripts. Assuming roughly a life with qmail install running on port 25 (hopefully with STARTTLS required):

 exec /usr/local/bin/softlimit -m 24000000
        /usr/local/bin/tcpserver -v -R -l "$LOCAL" -x /etc/tcp.smtp.cdb
                -c "$MAXSMTPD" -u "$QMAILDUID" -g "$NOFILESGID" 0 smtp
                /opt/bin/ /bin/true 2>&1

Note: This should be all one line or lines ending with ' \'

Qmail and Stunnel

The following daemontools run script sets up qmail using stunnel to provide SSL on the official dedicated SSL port 465:

 exec /usr/local/bin/softlimit -m 24000000
        /usr/local/bin/tcpserver -v -R -l "$LOCAL" -x /etc/tcp.smtps.cdb
                -c "$MAXSMTPD" -u "$QMAILDUID" -g "$NOFILESGID" 0 smtps
                /usr/sbin/stunnel /etc/stunnel/smtp.conf 2>&1

Note: This should be all one line or lines ending with ' \'

And the following stunnel smtp.conf configuration:

 cert = /etc/stunnel/smtp.pem
 exec = /var/qmail/bin/qmail-smtpd
 execargs = qmail-smtpd /opt/bin/ /bin/true
 foreground = yes


Dovecot can make us of the checkpassword interface for both passdb and prefetch userdb lookups. In dovecont.conf:

 userdb prefetch {
 passdb checkpassword {
        args = /opt/bin/

The prefetch userdb avoids unnecessary LDAP lookups, but will only work with extensive use of chkpassldap's environment modification capabilities. See section ENVIRONMENT MODIFICATION.


Some applications have needs beyond simple authentication and authorization, such as modifying the environment. The envmap hash at the top of the script controls this behavior. Each key is an environment variable name that points to a hash of options that controls how it is set. Options are described here.


Names the LDAP attribute whose value will be looked up to fill the environment variable.


Flags the variable for inclusion in a special environment variable named EXTRA. This is higly specific to Dovecot.


Flags the variable as optional so the environment variable will not be set at all if no value can be found.


Flags the variable for address resolution. This is included for the strange reason that in qmail-ldap it is typical to store the mailHost ldap attribute as a hostname, but Dovecot proxying can only make use of ip addresses. Therefore, we resolve it on behalf of Dovecot.


Names a dependency for the variable, so it will only be set if the dependency is set. This is included because Dovecot does not like to see proxying enabled when there is no host set.


When lookups are actually done, values are stored in this hash element. If a value is set ahead of time, it is effectively hardcoded and no lookup is done. This is a handy shortcut to specify a global setting for all users.

It may be obvious that much of the capability for environment modification grew up around tailoring the environment for Dovecot using qmail-ldap ldap attributes. It may be beneficial to describe the default hash in full to better show what is happening.

 my %envmap = (
        'HOME' =>               { ldap=>'homeDirectory' },
        'USER' =>               { ldap=>'uid' },
        'userdb_uid' =>         { ldap=>'uidNumber', extra=>1 },
        'userdb_gid' =>         { ldap=>'gidNumber', extra=>1 },
        'host' =>               { ldap=>'mailHost', extra=>1, optional=>1, nslookup=>1 },
        'proxy_maybe' =>        { value=>1, extra=>1, depends=>'host' },

When envset is enabled, the environment variables HOME, USER, userdb_uid, userdb_gid, and host are all set to the corresponding ldap attribute values returned for the user. The host variable is flagged for nslookup. It is also flagged as optional, so that if mailHost cannot be looked up or does not exist, the host environment variable is not set at all. If such is the case, proxy_maybe will not be set since it is flagged as depends on host, otherwise it is hardcoded to value 1. Finally, all those flagged with extra are stored by name, space-separated, in a special EXTRA environment variable.

A full reading of the Dovecot authentication documentation is required to understand the ramifications of the above. This specific setup is geared towards setting the environment for a qmail-ldap and Dovecot proxying cluster, but should scale well to other needs. Enable logging and debug and watch the logs. Suffice it to say, it does actually work.


chkpassldap 1.00 (20120526)

- Initial release.