Authentication Module, LDAPAuth

LDAPAuth enables you to authenticate against an LDAP server. You must already have an LDAP server setup and working before this module can be tested.

Installing and Setup

Some applications already come with this verison already built. If you have not got a build and/or require the lastest code it can be downloaded from the one of the links below:

Source: 118k
Linux 32bit
Linux 64bit
Old Versions:

Windows 55k
Linux (Libc6) ldapauth_2.5b_linux.tar.gz 39k


Building From Source:

If you are building LDAPAuth from the source you will need to have a C compiler either cc or
gcc and make. To build the command line prompt would be:

make -f Makefile.ldap

Setting up with OpenLDAP:

If your ldap server is OpenLDAP you will need to enable 'bind_v2' so that LDAPAuth will correctly bind to OpenLDAP. LDAPAuth currently only supports simple binding. You need to add the following line to openldap file 'slapd.conf':

allow bind_v2

The default schema 'person' should be used. This schema does not support the most of the surgemail default fields, and you will need to update the schema to include the fields that you wish to store.

Setting up with SurgeLDAP:

SurgeLDAP has been setup to use the 'netwinperson' schema instead of the deafult 'person' schema. In your ldapauth.ini file you should add the setting:

ldap_objectclass netwinperson

This schema has already been setup to support all the surgemail and surgeftp fields to make it easy to just include the fields that you wish to support.

Configuration Options:

LDAPAuth comes requires an ldapauth.ini to configurate it's options. This file is located in the same directory as the LDAPAuth binary OR in a directory specified by the -path command line option.

You should consult the ldapauth.ini that comes with the LDAPAuth download this will display all the default and common settings that you will need. Here is an example of what this file should look like:

# Welcome to Auth ini File.
# Leading # makes line a comment

# Main LDAP connection Information
ldap_port 389

ldap_mgr_dn cn=manager,dc=example,dc=com
ldap_mgr_pw mpass

# pop_domain

# LDAP Main Fields
ldap_search_base dc=example,dc=com

# ****** SurgeLDAP v1.0j+ use 'netwinperson' ****
# ldap_objectclass person
# ldap_objectclass netwinperson
# ldap_search_name mail
# ldap_extend_search (AnyAttribute==AnyValue)
# ldap_extend_lookup (AnyAttribute==AnyValue)
# field_password UserPassword

# LDAP Optional Fields
# --------------------

# ldap_extend_search (usertype=student)

# SurgeMail/DMail and NetAuth Settings
# ------------------------------------
# layout: info_fields surgemail_field ldap_field
# info_fields created created
info_fields fwd fwd
info_fields quota quota

# SurgeMail Only Settings
# ------------------------------------
# If surgemail is setup as a proxy you need this setting
# info_fields tohost tohost
# info_fields allow allow

# info_fields mailaccess mailaccess
# info_fields mailstatus mailstatus
# info_fields full_name givenName
# info_fields phone homePhone
# info_fields smsto smsto
# info_fields user_access user_access

# info_fields alias_quota alias_quota
# info_fields list_quota list_quota
# info_fields user_access user_access
# info_fields send_limit send_limit

# info_fields spf_block spf_block
# info_fields disabled disabled

# info_fields realuser realuser
# info_fields friends friends
# info_fields enotify enotify
# info_fields ddpriv ddpriv
# info_fields ddfrom ddfrom

# SurgeMail and NetAuth Settings
# ------------------------------
# info_fields pass_question pass_question
# info_fields pass_answer pass_answer

# SurgeMail/DMail and DNews Settings
# ----------------------------------
# info_fields groups groups

# SurgeFTP Settings
# -----------------
# info_fields ftphome ftphome
# info_fields ftpquota ftpquota
# info_fields ftpfromip ftpfromip
# info_fields ftpgid ftpgid
# info_fields ftpuid ftpuid
# info_fields accountstatus accountstatus

must_set_fields sn name
must_set_fields cn name

# NWAuth Password Method (defaults to plain text)
# unix_password true
# use_crypt_on_set true
# plain_password true
# sha_hash true
# ssha_hash true

The table below display the available options are available to use:

Setting Description
info_fields Use setting to inform LDAPAuth of pairs of database field names. It takes a list of up to 20 comma separated pairs of field names, where each pair is two words separated by a space. In each pair the first name is the name that LDAPAuth should lookup in your LDAP database and the second is the name it should display in the output.

Syntax: info_fields db_name1 field_name1,[...]
Example: info_fields groups usergroups,diskquota ftpquota
Default: none
Required Setting: no

ldap_group_base (Version 1.1a, DMail 3.0) These four settings are used to pass the group membership through to DNews for access control. It is much better to use the info_fields when possible (it is much more efficient). ldap_group_base defines where in the LDAP database group information is found.  See below this table for more info on using this.

Example: ldap_group_base dc=netwin,dc=co,dc=nz
Default: none
Required Setting: no

ldap_group_search A search that will find the LDAP objects that contain usergroup information, it's best to make this as specific as possible.

Example: ldap_group_search cn=group*
Default: none
Required Setting: no

ldap_group_field Specify the field that contains the users email address in usergroup objects.

Example: ldap_group_field cn
Default: cn
Required Setting: no

ldap_group_attrib Specify the attribute in a user group object that contains the information about each user.

Example: ldap_group_attrib uniquemember
Default: uniquemember
Required Setting: no

ldap_port The TCPIP port to connect to the LDAP server on.

Example: ldap_port 3890
Default: 389
Required Setting: no

log_path The file to store log files in

Example: log_path c:\logs\auth.log
Default: the location of the LDAPAuth executable ldapauth.log (older versions wrote to auth.log by default)
Required Setting: no

max_log_size The size at which log files are rotated. Logs are numbered 1,2,3,4

Example: max_log_size 10000
Default: 100000
Required Setting: no

log_level Controls the amount of information logged during use. One of error, info, debug.

Example: log_level debug
Default: info
Required Setting: no

ldap_host The IP address or domain of the host to connect to, ie: the machine where the LDAP server is listening.

Example: ldap_host
Default: localhost
Required Setting: no

ldap_mail_uid The LDAP attribute which will be used to store the uid SurgeMail should use for accessing the users drop file. ie: the SurgeMail servers will create and check that a user's drop file is owned by this system uid. Typically the default of 0 for root is used. In general we do not recommend changing this setting.

Example: ldap_mail_uid mail (user files owned by 'mail' user)
Default: 0 (root as SurgeMail runs as root)
Required Setting: no

ldap_mgr_dn The LDAP manager distinguished name to bind with. NB: add this field and the ldap_mgr_pw field with blank entries for anonymous login.

Example: ldap_mgr_dn cn=SurgeMail Manager
Default: cn=Directory Manager
Required Setting: yes

ldap_mgr_pw The password for the ldap_mgr_dn entry.NB: add this field and the ldap_mgr_dn field with blank entries for anonymous login.

Example: ldap_mgr_pw secret
Default: none
Required Setting: yes

ldap_search_base The LDAP search base to use for all interactions with the LDAP server

Example: ldap_search_base dc=apples,dc=com
    (or, ldap_search_base o=apples)
Default: none
Required Setting: yes

ldap_search_name IMPORTANT: Specifies the attribute used for identifying the users entry in the database. eg: when set to the default of mail, lookup bob, makes LDAPAuth lookup, mail=bob in database. (Prior to version 1.0k this was only used for lookups and not on the set command)

Example: ldap_search_name uid
Default: mail
Required Setting: no

pop_domain The domain which will be appended to any usernames not containing @domain

NB: if set then you must use the setting,
authent_domain true
in surgemail.ini (and in netauth.ini if using NetAuth);

Example: pop_domain
Default: none
Required Setting: no, but recommended

ldap_drop_file Name of LDAP attribute which will be used for storing the full name and path of the users drop file. Normally this is not set and LDAPAuth returns the keyword 'config' to indicate that the SurgeMail servers should use their internal settings to locate the users drop file location.

Example: ldap_drop_file mail_drop_file
    (makes LDAPAuth get value from the DB field 'mail_drop_file');
Default: none - so default 'config' keyword is returned.
Required Setting: no and not recommended

ldap_objectclass When adding new users LDAPAuth will add the new user to this ObjectClass.


  • When using the set command, you must specify attributes (fields) and values for any attributes 'required' by the object class that you specify with this setting. You may not specify any attributes that are 'not allowed' in the objectclass.

    You must enter something like,
    set username pass a="x" b="y" c="z"
    , where the fields a, b and c MUST be allowed in the specified objectclass, otherwise you will get an 'objectclass violation' error message. If you get that message then generally you need to alter the fields you are trying to set. Yes we wish there was a more informative error message also! Version 1.0k of LDAPAuth (and above) at least logs exactly which attributes and their values it is trying to set.

  • Often people forget to set cn="xxx" and 'violate the objectclass', so remember to place it on the end of the set command (or make NetAuth put it there if using NetAuth).
  • Some older versions of LDAPAuth have the incorrect setting name,
    as an example in the example ldapauth.ini file.

Example: ldap_objectclass umichPerson
    (umichPerson has the mail attribute that Person often does not);
Default: Person
Required Setting: no if using LDAPAuth for read-only, yes if using set command.

ldap_surgemail_forward Name of LDAP attribute in database which will be used to store SurgeMail forwarding addresses. It can be set blank. If a value for this attribute is found when doing a lookup or check command then LDAPAuth responds with the info field,
causing mail redirection to that address.

See the SurgeMail Manual section,
Ext. Auth Fwd Field for further details.

Example: ldap_surgemail_forward alias
Default: mailForwardingAddress
Required Setting: yes, because you probably don't want that bad default!

log_name Base of log file name. Note suffix n.log will be appended so default is ldapauth1.log

Example: log_name c:\mylogdir\
    (umichPerson has the mail attribute that Person often does not);
Default: LDAPAuth
Required Setting: no

sha_hash On set command only, take password given and use the SHA to hash it. NB: this setting is really obsoleted by SSHA, which is done by default. If you really want SHA then you need to set the two settings as per the example below.

Example (If you really do want SHA not SSHA or plaintext):
    sha_hash true
    ssha_hash_dont true
Default: false (ssha instead)
Required Setting: no

ssha_hash_dont Unless this setting is set to true, on the set command only, LDAPAuth will hash the given password using SSHA and prepend the string, {ssha} to the start of it before sending to the database. That way the database knows to SSHA the password sent by the LDAPAuth check command before comparing it with that user's password in the database. Starting with version 1.0L LDAPAuth will SSHA all passwords when setting (adding) a user in the database. This setting is for turning that behaviour off.

To make LDAPAuth add users with plain text passwords as it used to, use the setting as per the example below and check that the sha_hash setting is false or not in the ini file.

Example: #sha_hash true (commented out, for plain text passwords)
    ssha_hash_dont true
Default: false (ssha done automatically)
Required Setting: no

ldap_access_wild A list of IP addresses from which POP logins are accepted if 'pop' is found in the users ldap_access_field field, this allows you to disable direct pop access and only allow POP access from your WebMail interface.

Example: ldap_access_wild,11.*,!

ldap_access_field LDAP field in which to search for 'pop' if found then apply ldap_access_wild to POP logins
dir_hash Makes LDAPAuth return a path for drop/bin processing, eg:

dir_hash 2 2 /var/mail

Would return /var/mail/ch/ri/chrisp instead of 'config' as the path.


ldap_search_name_alt For example: ldap_search_name mail_alias

Would lookup the 'mail_alias' field for this user, if found, the ldap_uid field is then used to construct the drop path for this user, so this allows you to define aliases for a user. (very similar to forwarding) 

The feature is not intended for general use, avoid it if possible, it is intended for backward compatibility with pre existing LDAP databases.

ldap_uid uid Sets the UID field to use to construct a path for a user, see above setting.
ldap_mailhost If a user cannot be found the normal way, LDAPAuth will try the user part of the address as a ldap_uid search, and then see if the ldap_mailhost matches it, if so it then delivers to that uid.  Again this setting is not for general use it is only for backward compatibility with existing LDAP databases.
strip_domain true Removes the domain name from all lookups (can be useful with active directory or other ldap databases where the domain is not in the database)

This setting is used to map a '' setting to a seperate 'search_base_dn'. This allows you to seperate each domain into a seperate part of the LDAP tree.
When you do this you should NOT map any sub domains.

ldap_map_domain dc=domain,dc=com
ldap_map_domain dc=netwin,dc=co,dc=nz

If not map for a domain is located it will default to the 'ldap_search_base' location.

Notes on using ldap_group* settings with DNews.

Command Line Options:

-path Tells LDAPAuth where to create it's logfile and where to find it's config file.
-debug Sets the logging level to debug.
-log Turns on logging to nwauth.log.
-version This display the LDAPAuth version information
-filtername,str1,str2 The username on a set,del,lookup,check command is check for 'str1' and replaced with 'str2'
-convert_nwauth nwauth_path This will create a 'nw_convert.bat' file from the nwauth.add and nwauth.txt files that when run will run LDAPAuth with various commands to make the LDAP database match NWAuth setup.

Supported Commands

The commands below are the list of commands that this module supports. For a full description about the command see Authentication Protocol

Command Parameters
check <user> <pass>
lookup <user>
set <user> <pass>|(NULL) [label="value"]
del <user>
search <string> [-from n] [-max m]

How do I upgrade NWAuth to LDAPAuth

To upgrade to LDAPAuth you need to following the following steps.

Step 1:   Create your LDAP schema and setup LDAPAuth seperatly.
    Ensure that your LDAPAuth uses the following ini setting:
         unix_password true
The reason for this is that since NWAuth used 1 way encoding password you need to make LDAPAuth to use the same password encoding method.
Step 2:   Test and get it working before nwauth user converted over.
    You will need version 2.2u of LDAPAuth to preform this migration.
    You should be able to create, delete, lookup and check users.
ie.   ./ldapauth
      set lynden pass
      search lyn*
      lookup lynden
      check lynden pass
      del lynden
Step 3:   Once LDAPAuth works correctly the next step is to migrate the nwauth information to the LDAP server.
    The 2 NetAuth files are 'nwauth.add' and '', these are the 2 that need to be converted. keeping in mine that that ones that are deleted should not be added.

The Lastest LDAPAuth (v2.2u) as built in code to take these files and convert then into a .bat or .sh file that you can run which will populate LDAPAuth database.

To do this you run like this:
./ldapauth -convert_nwauth /usr/local/surgemail
or ./ldapauth -convert_nwauth c:\surgemail

This creates a file called: '' or 'nw_convert.bat'

Before you run the batch file you first need to setup ldapauth to accept the passwords as plain text otherwise they will be encoded twice. To do this you need to remove/comment out the ini setting 'unix_password' and add this ldapauth.ini setting:
         plain_password true
This will make sure that the password is added in as is. Once you have run the batch file you then will need to remove the 'plain_password' and place back the 'unix_password'.
Step 4:   Test LDAPAuth.
    You should be able to search, lookup and check the users you have just added.
ie.   ./ldapauth
      search lyn*
      lookup lynden
      check lynden pass


Example used with Active Directory (windows)

ldap_port 389
ldap_mgr_dn cn=ftpadmin1,ou=mgt_info_sys,ou=CTL,ou=region_sales,dc=example,dc=com
ldap_mgr_pw secret_password
ldap_search_base OU=region_sales,dc=example,dc=com
ldap_scope LDAP_SCOPE_subtree
ldap_search_name ExampleAccountName
ldap_group_base OU=region_sales,dc=example,dc=com
ldap_group_search CN=&*
ldap_group_field CN
ldap_group_attrib member

Downloading a recommended LDAP server

OpenLDAP server, available at:

We also test LDAPAuth against Netscape's LDAP server (a number of the defaults reflect this) and the University of Michigan server.

SDKs for LDAP are also available,