Contents of /mod_auth_ibmdb2/mod_authnz_ibmdb2/README

$Id: README,v 1.11 2008/01/08 04:47:35 tessus Exp $

Copyright (c) 2006-2008 Helmut K. C. Tessarek
written by Helmut K. C. Tessarek

http://mod-auth-ibmdb2.sourceforge.net

Contents:
---------

1)  Description of the module
2)  File descriptions

1) Description of the module
-----------------------------

mod_authnz_ibmdb2 is an Apache authentication module using IBM DB2 as the backend database for
storing user and group information.

Here is a list of the new directives that come with the module:

AuthIBMDB2User          user for connecting to the DB2 database (no default)

AuthIBMDB2Password      password for connecting to the DB2 database (no default)

AuthIBMDB2Database      database name (no default)

AuthIBMDB2UserTable         name of the user table (no default)

AuthIBMDB2GroupTable        name of the group table (no default)

AuthIBMDB2NameField         name of the user field within the table (defaults to 'username')

AuthIBMDB2GroupField        name of the group field within the table (defaults to 'groupname')

AuthIBMDB2PasswordField     name of the password field within the table (defaults to 'password')

AuthIBMDB2CryptedPasswords  passwords are stored encrypted (defaults to yes) 

AuthIBMDB2KeepAlive         connection kept open across requests (defaults to yes)

AuthIBMDB2Authoritative     lookup is authoritative (defaults to yes) 

AuthIBMDB2NoPasswd      just check, if user is in usertable (defaults to no)

AuthIBMDB2UserCondition     restrict result set (no default)

AuthIBMDB2GroupCondition    restrict result set (no default)

AuthIBMDB2UserProc      stored procedure for user authentication (no default)

AuthIBMDB2GroupProc     stored procedure for group authentication (no default)

AuthIBMDB2Caching       user credentials are cached (defaults to off)

AuthIBMDB2GroupCaching      group information is cached (defaults to off)

AuthIBMDB2CacheFile     path to cache file (defaults to /tmp/auth_cred_cache )

AuthIBMDB2CacheLifetime     cache lifetime in seconds (defaults to 300)


Example how to use the module in the httpd.conf:

<Directory "/var/www/my_test_dir">
    AuthName            "DB2 Authentication"
    AuthType            Basic
    AuthBasicProvider   ibmdb2

    AuthIBMDB2User               db2inst1
    AuthIBMDB2Password           ibmdb2
    AuthIBMDB2Database           auth
    AuthIBMDB2UserTable          web.users
    AuthIBMDB2NameField          username
    AuthIBMDB2PasswordField      passwd

    AuthIBMDB2CryptedPasswords   On
    AuthIBMDB2KeepAlive          On
    AuthIBMDB2Authoritative      On
    AuthIBMDB2NoPasswd           Off

    AuthIBMDB2GroupTable         web.groups
    AuthIBMDB2GroupField         groupname

    #require                     valid-user
    require                      group admin
    AllowOverride                None
</Directory>

or

<Directory "/var/www/my_test_dir">
    AuthName            "DB2 Authentication"
    AuthType            Basic
    AuthBasicProvider   ibmdb2

    AuthIBMDB2User               db2inst1
    AuthIBMDB2Password           ibmdb2
    AuthIBMDB2Database           auth
    AuthIBMDB2UserProc           user_sp
    AuthIBMDB2GroupProc          group_sp

    AuthIBMDB2Caching            On
    AuthIBMDB2GroupCaching       On

    require                      group admin
    AllowOverride                None
</Directory>

where the stored procedures must have the following parameter format:

CREATE PROCEDURE user_sp  ( IN VARCHAR, OUT VARCHAR )
CREATE PROCEDURE group_sp ( IN VARCHAR )

The stored procedure for user authentication must return exact one value -
the password. If AuthIBMDB2NoPasswd is set to yes, then the username has
to be returned instead of the password.

The stored procedure for group authentication must return an open cursor
to the resultset.

Two examples for stored procedures are given in the documentation.

2) File descriptions
--------------------

mod_authnz_ibmdb2.c the Apache module
mod_authnz_ibmdb2.h the Apache module's header file
caching.h       include file for caching mechanism
makemod         bash script to compile the module
makemod.bat     script to compile the module under win32
README          this file
INSTALL         compiling and installing instructions
CHANGES         change log
man/maninstall      bash script to install the manpages
1	$Id: README,v 1.11 2008/01/08 04:47:35 tessus Exp $
2
3	Copyright (c) 2006-2008 Helmut K. C. Tessarek
4	written by Helmut K. C. Tessarek
5
6	http://mod-auth-ibmdb2.sourceforge.net
7
8	Contents:
9	---------
10
11	1) Description of the module
12	2) File descriptions
13
14	1) Description of the module
15	-----------------------------
16
17	mod_authnz_ibmdb2 is an Apache authentication module using IBM DB2 as the backend database for
18	storing user and group information.
19
20	Here is a list of the new directives that come with the module:
21
22	AuthIBMDB2User user for connecting to the DB2 database (no default)
23
24	AuthIBMDB2Password password for connecting to the DB2 database (no default)
25
26	AuthIBMDB2Database database name (no default)
27
28	AuthIBMDB2UserTable name of the user table (no default)
29
30	AuthIBMDB2GroupTable name of the group table (no default)
31
32	AuthIBMDB2NameField name of the user field within the table (defaults to 'username')
33
34	AuthIBMDB2GroupField name of the group field within the table (defaults to 'groupname')
35
36	AuthIBMDB2PasswordField name of the password field within the table (defaults to 'password')
37
38	AuthIBMDB2CryptedPasswords passwords are stored encrypted (defaults to yes)
39
40	AuthIBMDB2KeepAlive connection kept open across requests (defaults to yes)
41
42	AuthIBMDB2Authoritative lookup is authoritative (defaults to yes)
43
44	AuthIBMDB2NoPasswd just check, if user is in usertable (defaults to no)
45
46	AuthIBMDB2UserCondition restrict result set (no default)
47
48	AuthIBMDB2GroupCondition restrict result set (no default)
49
50	AuthIBMDB2UserProc stored procedure for user authentication (no default)
51
52	AuthIBMDB2GroupProc stored procedure for group authentication (no default)
53
54	AuthIBMDB2Caching user credentials are cached (defaults to off)
55
56	AuthIBMDB2GroupCaching group information is cached (defaults to off)
57
58	AuthIBMDB2CacheFile path to cache file (defaults to /tmp/auth_cred_cache )
59
60	AuthIBMDB2CacheLifetime cache lifetime in seconds (defaults to 300)
61
62
63
64	Example how to use the module in the httpd.conf:
65
66	<Directory "/var/www/my_test_dir">
67	AuthName "DB2 Authentication"
68	AuthType Basic
69	AuthBasicProvider ibmdb2
70
71	AuthIBMDB2User db2inst1
72	AuthIBMDB2Password ibmdb2
73	AuthIBMDB2Database auth
74	AuthIBMDB2UserTable web.users
75	AuthIBMDB2NameField username
76	AuthIBMDB2PasswordField passwd
77
78	AuthIBMDB2CryptedPasswords On
79	AuthIBMDB2KeepAlive On
80	AuthIBMDB2Authoritative On
81	AuthIBMDB2NoPasswd Off
82
83	AuthIBMDB2GroupTable web.groups
84	AuthIBMDB2GroupField groupname
85
86	#require valid-user
87	require group admin
88	AllowOverride None
89	</Directory>
90
91	or
92
93	<Directory "/var/www/my_test_dir">
94	AuthName "DB2 Authentication"
95	AuthType Basic
96	AuthBasicProvider ibmdb2
97
98	AuthIBMDB2User db2inst1
99	AuthIBMDB2Password ibmdb2
100	AuthIBMDB2Database auth
101	AuthIBMDB2UserProc user_sp
102	AuthIBMDB2GroupProc group_sp
103
104	AuthIBMDB2Caching On
105	AuthIBMDB2GroupCaching On
106
107	require group admin
108	AllowOverride None
109	</Directory>
110
111	where the stored procedures must have the following parameter format:
112
113	CREATE PROCEDURE user_sp ( IN VARCHAR, OUT VARCHAR )
114	CREATE PROCEDURE group_sp ( IN VARCHAR )
115
116	The stored procedure for user authentication must return exact one value -
117	the password. If AuthIBMDB2NoPasswd is set to yes, then the username has
118	to be returned instead of the password.
119
120	The stored procedure for group authentication must return an open cursor
121	to the resultset.
122
123	Two examples for stored procedures are given in the documentation.
124
125	2) File descriptions
126	--------------------
127
128	mod_authnz_ibmdb2.c the Apache module
129	mod_authnz_ibmdb2.h the Apache module's header file
130	caching.h include file for caching mechanism
131	makemod bash script to compile the module
132	makemod.bat script to compile the module under win32
133	README this file
134	INSTALL compiling and installing instructions
135	CHANGES change log
136	man/maninstall bash script to install the manpages