ODBCAuth External Authentication Module for DMail

An external authentication module that allows DMail to do user lookups on a Database with an ODBC driver.

Designed to work with, Microsoft SQL Server, Microsoft Access and ORACLE databases amongst others.

This is a Windows Only External Authentication Module.

Installing ODBCAuth

Once you have downloaded, ODBCAuth from the Utilities Download Page and unpacked it to your DMail directory (e.g. c:\dmail), you should find two files:

odbcauth.exe
odbcauth.ini

(If you cannot find these files contact, DMail Support)

Place these files into your dmail directory and update dmail.conf to point to this external module.

e.g. on Windows:
    authent_method external
    authent_process c:\dmail\odbcauth.exe

Then you must edit the odbcauth.ini file so that it points to the ODBC driver for your Database. More details on this step are provided on the rest of this page.

NB: You should locate the ini file in the same directory as the odbcauth binary or as,
c:\winnt\system32\odbcauth.ini (on Windows platforms)

And then RESTART both DSMTP and DPOP.

NB: you must RESTART both DSMTP and DPOP when ever you change your odbcauth.ini file, as they spawn copies of ODBCAuth which only reads odbcauth.ini at startup.

And that is it. For details of other External Authentication Settings see the User Administration section of the DMail Manual.

IMPORTANT Notes on using ODBCAuth

Notes for MS Access Database (Office 2000)
(Many will apply to all databases)

  • have to save before columns are updated in odbc driver.
  • you do not have to stop odbcauth when database changes, but sometimes you do have to stop editing the database - just saving it is NOT enough.
  • you cannot save certain table changes in access when odbcauth is running, e.g. changing a column name, but you can add rows to a table or edit column values.
  • spaces in column names get taken out so for column, Email Address, it should be identified in odbcauth.ini as, field_x EmailAddress
  • space in table names do stay so,
    odbc_mail_user_table Mail Database
    is valid.
  • (to be checked) any data type is ok in columns
  • set odbc driver name with setting,
    odbc_driver_name odbcauth
  • if odbcauth dies before connection to odbc driver then odbc_driver_name settting probably set incorrectly.

Creating/Using a ODBC Database

This section has still to be completed...

Basically you have to create your database or use an existing database.

Then setup an ODBC database driver to point to your database, in Control Panel, ODBC Data Sources.

Then setup ODBCAuth by editing its ini settings so that it talks to the odbc driver that you have set up.

Check Install

NB: ODBCAuth only supports the Basic External Authentication Protocol. So it only supports looking up a user (no password needed) and checking a user (requires username and password), and not adding, modifying or searching for users.

Once ODBCAuth is installed it is best to then check that ODBCAuth is working correctly. You will need to run ODBCAuth from the command line (in a dos box on Windows) and try the following. NB: We recommend that you run in debug mode at this stage. So you will get a lot of lines coming back that are just information.

NOTE:    C: - Client, S: - Server

c:\dmail\odbcauth -debug

C: lookup test
S: +OK test config 0

C: check test password
S: +OK test config 0

C: check test incorrect
S: -ERR test password wrong or not a valid user

The acutal response may vary. To display the complete list of commands that ODBCAuth supports enter the command:

help

Information about the protocol being used can be found in the DMail manual: (Basic External Authentication Protocol)

User Administration , External Authentication Protocol section

ODBCAuth.ini settings

Label

Example

Default

Explanation
allowats
(Optional) 		true false Overrides default limitation of one @ symbol in username. Added in version 1.0h.
allowhighascii
(Optional) 		true false Added in version 1.0h. By default odbcauth will no longer allow usernames with high or low ascii characters in them, i.e. in the ranges 0-31 and greater than 127. This setting allows you to turn that restriction off.
badchar <string>
(Optional) 		:; 
:|"`'
 Use string to specify a list of characters which will not be allowed in any part of the usernames. If found, then odbcauth responds -ERR without doing lookup. Default characters shown are based on relevant RFCs and our recommended set to use. Only override the defaults if you are sure of what you are doing. Added in version 1.0h.
badchar_localpart <string>
(Optional) 		:; 
':|;[]/\()<>"
 Use string to specify a list of characters which will not be allowed in the localpart of a username, i.e. the bit before the @. If found, then odbcauth responds -ERR without doing lookup. Default characters shown are based on relevant RFCs and our recomendation. Only override the defaults if you are sure of what you are doing. Added in version 1.0h.
debug
(Optional) 		true false No Longer settable in ini file, use 'log true' instead. Or if you really want extra info to 'stdout' then use the command line -debug option or the command debug once it is running.
domain
(Optional) 		your.default.domain none This is default domain that is appended to any username that does not already have a domain setting attached.
field_username user username The label of the username field in your table.
field_password password passwd The label of the password field in your table.
field_forward
(Optional) 		fwd none The label of the forward field in your table. This is the fowarding information that DMail uses to determine if mail for the account looked up should be delivered to a different address.
field_quota
(Optional) 		quota none The label of the quota field in your table. This is the disk quota the user has.
          e.g. 100k,  10M
field_mailmask
(Optional) 		mailmask none The label of the mailmask field in your table. This is the IP mask that ODBCAuth checks against the from IP of the user. If specified, this forces the user to connect only to the specified IP in order to collect mail (POP).
field_maildrop
(Optional) 		maildrop none The label of the maildrop field in your table. This is the location where dmail will drop the user mail files. NB: if the field value is empty in the database (NULL) odbcauth will return the keywork 'config' indicating that the server knows where to locate the drop file.
log
(Optional) 		true false Makes odbcauth log verbose information to the log file. Use instead of debug, as does not increase output to STDOUT which breaks communication with DPOP and DSMTP.
logpass
(Optional) 		true false Makes odbcauth log all commands it receives (up to the first newline character). NB: this will log passwords, so only set when needed for debugging system. Added in version 1.0h.
log_path
(Optional) 		odbcauth.log auth.log This is the odbcauth log path or filename. If just a path, filename will have same base name as module.
odbc_login
(Optional) 		username none (Optional) This is the username that has access to the correct database and table that stores the usernames and passwords.
odbc_password
(Optional) 		password none (Optional) This is the password that is required and used in conjuction with odbc_login.
odbc_odbc_driver_name user_data odbcauth This is the odbc driver name as set in ODBC Data Sources in Control Panel for the database where the mail usernames are stored.
odbc_mail_user_table users_list maildb This is the table name that is within the mail user database that has the user details. NB: cannot have spaces in table name!
odbc_mail_uid
(Optional) 		99 0 This is the unique mail ID.NB: by default odbcauth returns 0 for this which indicates to the DMail Servers that the userid should not be checked.
-version
(Optional) 		    Command line option, e.g. odbcauth -version, that makes odbcauth give it's version number.


 

 
Products Downloads Prices Support Company