ODBCAuth Manual
-----------------

Setting           | Default
----------------------------
database_driver   | ODBCAuth
database_user     |
database_pass     |
database_table    | maildb
field_username    | username
field_password    | password
field_translate   |
field_block       |
field_send        |
field_droppath    |
field_ipmask      |
select_extras     |
use_sha           | false
check_crypt       | false
strip_pass_spaces |
loglevel          | info
debug             | false
domain            | 

database_driver:   This is the name of the ODBC data source.

database_user:     This is the login username for the ODBC data source.

database_pass:     This is the login password for the ODBC data source.

database_table:    This is the table within the ODBC data source to use.

field_username:    This is the name of the field that contains the users username.

field_password:    This is the name of the field what contains the users password.

field_translate:   This setting allows you to translate field names, for example
                   "field_translate forward fwd" will cause ODBCAuth to read
                   the "forward" field from the database and return it as "fwd",
                   the opposite is true if you set a user and set fwd="foo" then
                   ODBCAuth will set the forward field to "foo".

field_droppath:    This setting specifies a field name, ODBCAuth will report that
                   field as being the users drop path, the drop path is returned 
                   in lookup and check commands, it comes just after the username,
                   before the uid and the rest of the users information.

field_ipmask:      This setting specifies a field name, ODBCAuth will fail a user 
                   check even if the password was entered correctly but only if the
                   ip address reported by the checking entity does not match the mask
                   in this field.
                 
field_block:       This setting allows you to specify fields that are in the database
                   but are not to be returned by ODBCAuth on a lookup,check or search.
           
field_block:       This setting allows you to specify fields that are to be returned
                   only fields in this list or field_translate fields are returned.
                   (you can only use this one OR field_block not both.)

select_extras:     This setting allows you to pass extra requirements on all select
                   statements to the database, for example if you wanted this select
                   statement:
                   SELECT Login, Password FROM tblService ,tblServiceInfoResponse
                   WHERE Login = 'mike' AND (tblService.ServiceKey = 
                   tblServiceInfoResponse.ServiceKey) AND (Status='A' OR Status='N'
                   OR Status='O')
                 
                   Then you would set select_extras to (tblService.ServiceKey = 
                   tblServiceInfoResponse.ServiceKey) AND (Status='A' OR Status='N'
                   OR Status='O')

use_sha:           This setting enables the use of ssha encrypted passwords, odbcauth
                   will add users passwords to the database encrypted. Old plain text
                   or crypt'ed passwords will still check correctly but next time they
                   are set they will be encrypted.

check_crypt:       This setting requests that odbcauth attempts to match the password as
                   if it was crypt'ed, if that fails it checks it as if it was plain text,
                   if either success the check is successful.
                   This does not effect ssha passwords, they will not be checked as if 
                   crypt'ed.
                   This setting allows you to migrate nwauth user/password pairs into 
                   an odbc database and use odbcauth.
                 
strip_pass_spaces: This setting will cause ODBCAuth to strip any trailing spaces from
                   the password retrieved from the database before comparing it with
                   the one given in the check command.

loglevel:          The amount of data to log, error logs only errors, info logs 
                   errors and info, debug logs everything.
             
debug:             If set to "true" has same effect as "loglevel debug".

domain:            The domain name, if set this domain name is appended to all 
                   usernames returned by all the commands. It is NOT appended to
                   usernames added to the system.
             
Command line options
--------------------

-path        Tells ODBCAuth where to create it's logfile and where to find it's
             config file.
             
-debug       Sets the logging level to debug.


Supported commands
------------------

check <user> <pass> [<ipaddress>]
lookup <user>
set <user> <pass>|(NULL) [label="value"]
del <user>
search <string> [-from n] [-max m]
version
help
quit
exit

check        Verifies user <user> has password <pass>, this command also
             returns the users other field values.
             
lookup       Verifies the existance of user <user> and returns users fields
             as the check field above does.
             
set          Add new user or modify an existing user. The special case (NULL)
             is used to modify a users info without re-setting the password.
             Label="value" is the format used to set the other database fields.

del          Deletes a user.

search       Returns a list of users matching the search <string>, the string
             may contain a * or ? wildcard, if it does the string is matched
             as if it was a wildcard string, otherwise a match is found only
             if the username contains the string.

version      Returns the version number.

help         Returns the above list of commands

quit         Ends session

exit         Ends session


Command responses
-----------------

A command will usually respond with a one line response, that response will
start with +OK or -ERR, example:
  +OK test@domain.com created successfully
  -ERR test@domain.com create failed, ...
Check and Lookup commands return the username, drop path, user id and misc
user info, example:
  +OK test@domain <drop path> <uid> info...
eg.
  +OK test@domain config 0 info...
  +OK test@domain c:\users\domain\test 0 info...

If a command wants to return more that one line as a response it will send
lines starting with +DATA before the final +OK or -ERR response, example:
  +DATA test@domain.com config 0
  +DATA test2@domain.com config 0
  +OK Search Complete 2 items found out of 80

If UnixAuth has a fatal error while trying to initialise then it will return
a -DEAD message like the following...
  -DEAD Failed to load config settings, access denied
  
If you have any questions about ODBCAuth please don't hesitate to contact:
  support-netauth@netwinsite.com
