MySQLAuth External Authentication Module for DMail
An external authentication module that allows DMail to do user lookups
on a MySQL Database.
Installing MySQLAuth
When you look for MySQLAuth in your DMail distribution,
you should find two files:
unix |
nt |
mysqlauth
mysqlauth.ini |
mysqlauth.exe
mysqlauth.ini |
(If you cannot find these files see, Download and History for MySQLAuth)
Place these files into your dmail directory and update dmail.conf to point to this
external module.
e.g. on UNIX
authent_method external
authent_process /usr/local/dmail/mysqlauth
and on Windows:
authent_method external
authent_process c:\dmail\mysqlauth.exe
Then you must edit the mysqlauth.ini file so that it points to your
MySQL server. 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
mysqlauth binary or as,
/etc/mysqlauth.ini (on UNIX based platforms)
or,
c:\winnt\system32\mysqlauth.ini (on Windows platforms)
And then RESTART both DSMTP and DPOP.
NB: you must RESTART both DSMTP and DPOP whenever you change your
mysqlauth.ini file, as they spawn copies of MySQLAuth which only read
mysqlauth.ini at startup.
And that's it. For details on other External Authentication Settings see
the User Administration section of the DMail Manual.
MySQLAuth requires a MySQL database which is setup and working.
The database that is setup must
have a username and a password that is encrypted using the mysql command PASSWORD(). You
can either create a new database/table for MySQLAuth or use a current database that has
usernames and passwords.
New DataBase:
Below are instructions on how to setup a brand new database and table to work with
MySQLAuth, with all of the features that MySQLAuth provides.
CREATE DATABASE maildb
USE maildb;
CREATE TABLE maildb (
username CHAR(128) binary DEFAULT '' NOT NULL,
passwd CHAR(128) DEFAULT '*' NOT NULL,
forward CHAR(255) DEFAULT '',
quota CHAR(20) DEFAULT '',
mailmask CHAR(18) DEFAULT '0.0.0.0' NOT NULL,
maildrop CHAR(255),
PRIMARY KEY (username)
);
To insert a brand new account into this account using your sql the command is:
INSERT INTO maildb VALUES
('test@test.org', PASSWORD('test'), '', '100k',
'0.0.0.0','/usr/spool/mail/test');
This will create a user called test@test.org with
the username of test.
To manually remove a user the command is:
DELETE FROM maildb WHERE username='test@test.org'
The inserting and deleting of users is usually taken care of by MySQLAuth.
The above is to
show how you would do this manually.
The ini settings for the above would look like the following:
mysql_server your.sql.server
mysql_login login
mysql_password password
domain your.default.domain
mysql_mail_user_db maildb
mysql_mail_user_table maildb
field_username username
field_password passwd
field_forward forward
field_quota quota
field_mailmask mailmask
field_maildrop maildrop
Using Current DataBase:
If you already have an existing database which you wish to use, then as long as the
usernames are unique and the password field is encrypted using the PASSWORD() mysql
command you should simply be able to change the ini settings to point to this
database, table and field label names.
eg. If you have a database called 'accounts' and a table called 'mail_users'
that stores all sorts of information but has the username field names 'name'
and the password field called 'pwd' then the ini settings that you
required are:
mysql_server your.sql.server
mysql_login login
mysql_password password
domain your.default.domain
mysql_mail_user_db accounts
mysql_mail_user_table mail_users
field_username name
field_password pwd
If you also have the ability to store the mail quota or forwarding, then you can add
these ini settings as well...
ie. field_forward forward
field_quota quota
Check Install
Once MySQLAuth is installed, it is best to check immediately that MySQLAuth is
working correctly. You will need to run MySQLAuth from the command line
(in a dos box on Windows) and try the
following.
NOTE: C: - Client, S: - Server
./mysqlauth
C: set test_account password
S: +OK 'test_account@test.org' has been added to database
C: set test_fwd password fwd="test_account@domain1"
S: +OK 'test_account@test.org' has been added to database
C: set test_quota password quota="100k"
S: +OK 'test_account@test.org' has been added to database
C: set test password fwd="test_account@domain1" quota="100k"
S: +OK 'test_account@test.org' has been added to database
C: search *
S: +DATA test_quota@test.org config 0 quota="100k"
S: +DATA test_fwd@test.org config 0 fwd="test_account@domain1"
S: +DATA test_account@test.org config
S: +DATA test@test.org config 0 fwd="test_account@domain1"
quota="100k"
S: +OK Search Completed 4 items found
C: lookup test_quota
S: +OK test_quota@test.org config 0 quota="100k"
C: lookup test
S: +DATA test@test.org config 0 fwd="test_account@domain1"
quota="100k"
C: check test password
S: +OK test@test.org config 0 fwd="test_account@domain1" quota="100k"
C: check test incorrect
S: -ERR test@test.org password wrong or not a valid user
C: del test
S: +OK 'test@test.org' has been deleted
C: del test_account
S: +OK 'test_account@test.org' has been deleted
C: del test_quota
S: +OK 'test_quota@test.org' has been deleted
C: del test_fwd
S: +OK 'test_fwd@test.org' has been deleted
The acutal response with quota and fwd might vary if the mysql database does not
have quotas or fwd setup. In order to display the complete list of commands that
MySQLAuth supports, enter the
command:
help
Information about the protocol being used can be found in the DMail
manual:
User Administration , External Authentication
Protocol section
If you need an mysqlauth.ini to start with, download, mysqlauth.ini.
Label |
Example |
Default |
Explanation |
debug |
true |
false |
Enables verbose debug output. |
domain |
your.default.domain |
none |
This is default domain that is appended to any username which 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 |
fwd |
forward |
The label of the forward field in your table. This is the fowarding information that
DMail uses to determine whether mail for the account looked up should be delivered
to a different address. |
field_quota |
quota |
none |
The label of the quota field in your table. This is the disk quota which the user has.
e.g. 100k, 10M |
field_mailmask |
mailmask |
none |
The label of the mailmask field in your table. This is the IP mask which MySQLAuth 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 |
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), mysqlauth will return the keywork 'config' indicating
that the server knows where to locate the drop file. |
log_path |
mysqlauth.log |
auth.log |
This is the mysqlauth log file. |
mysql_server |
your.sql.server |
none |
This is the IP or name of the computer hosting the mysql server. |
mysql_login |
username |
none |
This is the username that has access to the correct database and table that stores the
usernames and passwords. |
mysql_password |
password |
none |
This is the password that is required and used in conjuction with mysql_login. |
mysql_mail_user_db |
user_data |
maildb |
This is the database name where the mail usernames are stored. |
mysql_mail_user_table |
users_list |
maildb |
This is the table name that is within the mail user database that has the user
details. |
mysql_mail_uid |
99 |
0 |
This is the unique mail ID. NB: by default, mysqlauth returns 0 for this,
which indicates to the DMail Servers that the userid should not be checked. |
Below is an unedited example of setting up a mysql database to test on
a Windows NT box.
1. Downloaded from a mysql mirror site (they like it when you use a mirror),
mysql-shareware-3.22.32.win.zip
and unpacked to,
d:\mysql
2. Edited example file, d:\mysql\my-example.cnf that came with it, so that,
all c:'s were changed to d:, and saved as,
c:\my.cnf
(notepad named it c:\my.cnf.txt for me so I did a rename on it in
a dos prompt)
3. In order to install as service on NT...
d:\mysql\bin>mysqld-shareware --install
NB: when I then tried to start service in ControlPanel|Services, it
failed with a message saying that the process had stopped itself.
so I entered...
d:\mysql\bin>mysqld-shareware --debug
and at the top of all the mess was an error about a setting in the
my.cnf file that it did not like.
NB: if I ran it from a command line, it started and could not be stopped,
even with a CTRL-C - I had to kill it in process list of task manager.
In the bin dir was an exe mysqlshutdown, which just popped up a window
(Icon in system tray), but I could not get it to stop the process - maybe
it is for stopping the service? - no does not seem to affect that
either - kind of a cute icon though :-)
The dos command,
net stop mysql
does work as does,
net start mysql
.
4. Creating root user.
NB: our sqlauth module makes you send a password. By default, the
mysql daemon has a root user with no password, so you need to set the
root password to something.
From the mysql manual ...
(The following example starts by removing the anonymous user. That allows
anyone to access the 'test' database)
d:\mysql\bin\mysql mysql
mysql> DELETE FROM user WHERE Host='localhost' AND User='';
mysql> QUIT
d:\mysql\bin\mysqladmin reload
d:\mysql\bin\mysqladmin -u root password your_password
NB: I had problems getting the root password set after deleting it. I
ended up entering the following to set the root password...
D:\mysql\bin>mysqlc -u root mysql
Reading table information for completion of table and column names
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 16 to server version: 3.22.32-shareware-debug
Type 'help' for help.
mysql> UPDATE user SET Password=PASSWORD('qwerty') WHERE user='root';
Query OK, 2 rows affected (0.02 sec)
Rows matched: 2 Changed: 2 Warnings: 0
mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.03 sec)
Now in c:\my.cnf edit client section and add,
password=qwerty
and save.
Now you should be able to connect with the client program as user root
with the new password...
5. Now follow the examples in the manual.
In section 8.4 of the manual file,
d:\mysql\docs\manual.htm
start client (on local machine - same as ...
D:\mysql\bin>mysqlc -u root -pqwerty
(can also do,
D:\mysql\bin>mysqlc -u root -p
and it prompts for password so that your command prompt buffer does not
contain your password if you are worried about that sort of
security)
(on non-local machine,
D:\mysql\bin>mysqlc -u root -pqwerty -host=1.2.3.4
)
(NB: you can also include a database name on the end of the line to connect to a specific
database, e.g. to connect to a database called, 'mydb' enter,
D:\mysql\bin>mysqlc -u root -pqwerty mydb
)
every time you see 'mysql>' from now on, it indicates that you are at the
prompt in the mysqlc client program...
6. Create test database and a table within it ...
mysql> CREATE DATABASE maildb;
Query OK, 1 row affected (0.01 sec)
mysql> CREATE TABLE maildb (username VARCHAR(20),password VARCHAR(20),forward VARCHAR(20));
Query OK, 0 rows affected (0.03 sec)
mysql> SHOW TABLES;
+------------------+
| Tables in maildb |
+------------------+
| maildb |
+------------------+
1 row in set (0.01 sec)
mysql> DESCRIBE maildb;
+----------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+----------+-------------+------+-----+---------+-------+
| username | varchar(20) | YES | | NULL | |
| password | varchar(20) | YES | | NULL | |
| forward | varchar(20) | YES | | NULL | |
+----------+-------------+------+-----+---------+-------+
3 rows in set (0.01 sec)
7. Loading users in from a text file ...
I then made a file d:\mysql\users.txt which looked like,
tam pass \N
test test \N
where \N stands for NULL meaning no entry for that field.
and then tried to load it. You'll see I assumed a few things about
file paths incorrectly. I remember reading in the manual somewhere
about using / instead of \ (or using \\).
mysql> LOAD DATA LOCAL INFILE "users.txt" INTO TABLE maildb;
ERROR: File 'users.txt' not found (Errcode: 2)
mysql> LOAD DATA LOCAL INFILE "d:\MYSQL\users.txt" INTO TABLE maildb;
ERROR: File 'd:MYSQLusers.txt' not found (Errcode: 2)
mysql> LOAD DATA LOCAL INFILE "d:/MYSQL/users.txt" INTO TABLE maildb;
Query OK, 2 rows affected (0.02 sec)
Records: 2 Deleted: 0 Skipped: 0 Warnings: 0
8. Inserting a single record/updating a field/encrypting passwords ...
(use 'NULL' where you don't have an
entry for a field)
mysql> INSERT INTO maildb VALUES ('bob','bob','NULL');
Query OK, 1 row affected (0.01 sec)
oops - should have encrypted the password ...
mysql> UPDATE maildb SET password = PASSWORD('bob') WHERE username = 'bob';
Query OK, 1 row affected (0.01 sec)
Rows matched: 1 Changed: 1 Warnings: 0
so how do I add from text file and encrypt the passwords ...?
I can't work out how to do this, so I had better encrypt all the
other passwords ...
mysql> UPDATE maildb SET passwd = PASSWORD('tam') WHERE username = 'tam';
Query OK, 1 row affected (0.01 sec)
Rows matched: 1 Changed: 1 Warnings: 0
mysql> UPDATE maildb SET passwd = PASSWORD('test') WHERE username = 'test';
Query OK, 1 row affected (0.01 sec)
Rows matched: 1 Changed: 1 Warnings: 0
Now, let's see what I have in my maildb database ...
mysql> SELECT * FROM maildb;
+----------+------------------+---------+
| username | password | forward |
+----------+------------------+---------+
| tam | 6752d6483e543e43 | NULL |
| test | 378b243e220ca493 | NULL |
| bob | 7d67547927a4589e | NULL |
+----------+------------------+---------+
3 rows in set (0.01 sec)
oops - I gave the wrong name to my table column 'password' ...
8. Changing a table column name ...
mysql> ALTER TABLE maildb CHANGE 'password' 'passwd' VARCHAR(20);
ERROR 1064: You have an error in your SQL syntax near ''password' 'passwd' VARCH
AR(20)' at line 1
mysql> ALTER TABLE maildb CHANGE password passwd VARCHAR(20);
Query OK, 3 rows affected (0.19 sec)
Records: 3 Duplicates: 0 Warnings: 0
Now let's see what is in my maildb database again ...
mysql> SELECT * FROM maildb;
+----------+------------------+---------+
| username | passwd | forward |
+----------+------------------+---------+
| tam | 6752d6483e543e43 | NULL |
| test | 378b243e220ca493 | NULL |
| bob | 7d67547927a4589e | NULL |
+----------+------------------+---------+
3 rows in set (0.01 sec)
Went to Australian mirror of http://mysql.com , http://mirror.aarnet.edu.au/mysql
and downloaded,
mysql-3.23.32-sun-solaris2.7-sparc.tar.gz
then umpacked to /usr/local with,
(If you want to install support for the Perl DBI/DBD interface, see section 4.11 Perl Installation Comments. )
Hmmm, seems not to be working when I do, ps -ef |grep mysql, so find manual section,
4.16.2 Problems Starting the MySQL Server
which informs me that log is in,
In order to use MySQLAuth, you have to have set the root password, so ...
using the instructions given above,
Let's try from local box, so on solaris box set /etc/mysqlauth.ini as above but change,
Generally you will find the latest download in with your distribution set. You can check what
version of mysqlauth you have by running mysqlauth at a command prompt, e.g.,
c:\dmail\mysqlauth -version
If we put a download on the site for a version, it will be listed in the history below as a link.
A customer reports that it would seem that the mysql,user table entry, i.e. the entry that holds the username and password
that mysqlauth connects as, must allow access from anywhere. We suspect that this is just an intricacy of the
permission system used by MySQL. However, in testing we have found that almost the reverse is true, we had to add the user
twice, once for connections from 'localhost' AND once for connections from '%'.
If you want to test this ...
You can use the following in order to add a login account for a user called,
'dmail' with a password of 'mail', where that user can login from anywhere,