mSQL authentication Module. (authlibmsql) Version 0.1

This module allows muddleftpd 1.3.4 and above authenticate using a mSQL
server. This module will read client information from a supplied
table/database within mSQL. It does not modify any data on the server. It
supports:

	* Password encryption: Passwords can be encrypted on the mSQL
	  server in either plaintext (no encryption) or crypt based methods.
	* Support for custom SELECT query strings. This allows tremendous
	  flexibility for choosing the structure of the tables muddleftpd
	  retreive data from.

Note: This server is based very heavily off the mysql authentication module.
      Please excuse any reference to mysql I may make here as most of this
      module is copied directly from the mysql module.

DEPENDANCIES:

mSQL 2.0.11 or better. This module may compile and work on earlier versions, 
but it hasn't been tested for any older version.

Unless you specify a custom query for authlibmsql to perform, the table
containing user data must have the following fields, with these names:

	username	The username
	password	The password for the username
	homedir		The home directory for the user.
	rootdir		The root directory for the user.
	uid		The uid of the user.
	gid		The gid of the user.

BUILDING:

To build, execute the following in the authlibmsql source directory:

	./configure [--with-msql=<msqldir>]
	make

Or simply build it with the rest of muddleftpd, add --with-authmsql to
the configuration options of that configure script.
If mSQL is not installed in the default location (/usr/local/Hughes), you
need to supply the --with-msql option with the path to the base directory
of your mSQL setup.

After you have run make, the file libauthmsql.so can be copied to the 
directory you wish to store muddleftpd modules in. This directory must be 
secure, so users cannot overwrite the module with a cracked version.
By default it is put into @prefix@/lib from configure, if you dont set
prefix this is /usr/local/lib/muddleftpd.

USAGE:

In the groups that you wish authlibmsql to authenticate, you need to use
the following to tell muddleftpd to use the authlibmsql module, replacing the
directory here with the directory the authentication module is stored in:
(If unsure a locate libauthmsql.so may help).

authmethod /usr/local/lib/muddleftpd/libauthmsql.so

To configure authlibmsql, the following directives have been added. You must
specify these in the group section that is being configured.

msql_host <hostname>

	This specifies the host the mSQL server is located on. If you do
	not specify this value, authlibmsql will assume the host is
	'localhost'. (the same computer as the ftp server)

msql_port <portnumber>

	This specifies what TCP port number to connect to the mSQL server
	using. If it is not supplied, the default mSQL port is used.

msql_database <databasename>

	This specifies what database to use on the mSQL server. It is
	advisable not to use the master database. You must specify this
	value for authlibmsql to work.

msql_table <tablename>

	This specifies the table to read user password data from. By
	default, this is 'users'. This is not used if you specify a custom
	query string.

msql_encryption <encryptiontype>

	This specifies the type of encryption to use on passwords. There are
	two options avaliable:

	a) 'plaintext'
		Passwords are stored with no encryption at all. Anybody with
		read access to the database can steal the passwords. You
		should set muddleftpd.conf to 600 permissions if you use this 
		setting.

	b) 'crypt'
		Use the standard unix crypt() call to test passwords, so
		they typically end up as the same format as the password file

	The default option for msql_encryption is 'crypt'

msql_query <querystring>

	(ADVANCED OPTION) This specifies the query to use to get data from
	the database. It should be a SELECT query that returns data in the
	following order:

	1) password:	   The password of the user, in the selected encrypted
			   form.
	2) home directory: The home directory of the user.
	3) root directory: The root directory of the user.
	4) uid:		   An integer value for the user's uid.
	5) gid:		   An integer value for the user's gid.

	This SELECT query should only return 1 result if the user exists,
	or no results if the user does not exist. You can use this option if
	the field names do not match the ones documented above. An example
	(must be entered on a single line in the config file):

	mysql_query SELECT pass,home,root,useruid,usergid FROM usertable
		    WHERE user='%U'

	You can also use this option if data is spread among multiple
	tables. Another example (must still be on a single line in the
	config file!):

	mysql_query SELECT P.pass,C.home,C.root,C.uid,C.gid FROM passwd P,
		    credtable C WHERE P.user=C.user AND P.user='%U'

	This gets data from the password table, and joins it with data from
	the credentials table to provide data for authlibmsql.


GROUP EFFECTS:

If authlibmsql finds a single result for a query, and the data checks out 
ok, then it will accept the username, and authenticate for it. If it finds
no result for the query, then it will pass the username onto the next group
section. If more than one result is returned, or an error occured along the
way, authlibmsql will cancel authentication for that user.

FURTHER NOTES:

	* You should avoid using plaintext stored passwords, especially
	  since anyone who can read the configuration file can steal all
	  the passwords in the mSQL database.

AUTHORS:

Beau Kuiper (support@muddleftpd.cx)
