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: | auth_src_2.4c.zip |
| Windows | ldapauth_25j.zip |
| Linux 32bit | ldapauth_25j_linux.tar.gz |
| Linux 64bit | ldapauth_25p_linux64.tar.gz |
| Old Versions: | |
| Windows | ldapauth_2.5a_windows.zip |
| Linux (Libc6) | ldapauth_2.5b_linux.tar.gz |
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_host ldap.host ldap_port 389ldap_mgr_dn cn=manager,dc=example,dc=com ldap_mgr_pw mpass # pop_domain host.com# LDAP Main Fields ldap_search_base dc=example,dc=com ldap_scope LDAP_SCOPE_ONELEVEL # ldap_scope LDAP_SCOPE_SUBTREE# ****** 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# LDAP MUST HAVE fields 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 |
Config settings
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 apples.com
Default: localhost
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 apples.com
Default: none
Required Setting: no, but recommended
ldap_objectclass
When adding new users LDAPAuth will add the new user to this ObjectClass.
Notes:
- 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,
ldapobjectclass
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,
fwd="value"
e.g.,
fwd="bob@another_domain.com"
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 10.0.0.23,11.*,!11.1.1.2
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) ldap_map_domain
This setting is used to map a 'domain.com' 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 domain.com dc=domain,dc=com
ldap_map_domain netwin.co.nz dc=netwin,dc=co,dc=nz
If not map for a domain is located it will default to the 'ldap_search_base' location.
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
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] |
| version | |
| verbose | |
| help | |
| quit | |
| exit |
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 'nwauth.new', 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: 'nw_convert.sh' 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_host 10.1.1.1
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:
http://www.openldap.org/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,
http://www.openldap.org/
.