Increase priority
[debian/mod-auth-mysql] / DIRECTIVES
1 All the directives understood by this version of mod-auth-mysql are listed
2 below.  The huge number of synonym directives is due to the merging of two
3 separate versions of the program, both of which had subtly different usage
4 symantics.  I'm sure there will be rationalisation in the near future.
5
6 Auth_MySQL_Info <host> <user> <password>
7         Server-wide config option to specify the database host, username,
8         and password used to connect to the MySQL server.
9
10         This option affects all directories which do not override it via
11         AuthMySQL_Host, AuthMySQL_User, and/or AuthMySQL_Password.
12
13 AuthMySQL_DefaultHost <hostname>
14         Specifies the MySQL server to use for authentication.
15         
16         This option affects all directories which do not override it via
17         AuthMySQL_Host.
18
19 AuthMySQL_Host <hostname>
20         Synonym for AuthMySQL_DefaultHost, to be used in .htaccess files and
21         directory-specific entries.
22
23 Auth_MySQL_DefaultPort <portnum>
24         Specifies a port to use to talk to a MySQL server.  If left empty,
25         the default (3306) will be used.
26
27         This option affects all directories which do not override it via
28         Auth_MySQL_Port.
29
30 Auth_MySQL_Port <portnum>
31         Specifies a non-default port to use (other than 3306) when talking
32         to the MySQL server on AuthMySQL_Host or AuthMySQL_DefaultHost.
33
34 Auth_MySQL_DefaultSocket <socketname>
35         If using a local MySQL server, you can
36         specify a non-default named pipe to use instead of the default pipe
37         name compiled into your MySQL client library.
38
39         This option affects all directories which do not override it via
40         Auth_MySQL_Socket.
41
42 Auth_MySQL_Socket <socketname>
43         If using a local MySQL server, you can specify a non-default named
44         pipe to use instead of the default one compiled into MySQL with this
45         option.
46
47 AuthMySQL_DefaultUser <username>
48         Specifies the username for connection to the MySQL server.
49
50 AuthMySQL_User <username>
51         Synonym for AuthMySQL_DefaultUser, to be used in .htaccess files and
52         directory-specific entries.
53         
54 AuthMySQL_DefaultPassword <password>
55         Specifies the password user together with the above user.
56
57 AuthMySQL_Password <password>
58         Synonym for AuthMySQL_Password, to be used in .htaccess files and
59         directory-specific entries.
60
61 Auth_MySQL_General_DB <database_name>
62         Server-wide, specifies a default database name to use.
63
64 Auth_MySQL_DB <database_name>
65         Synonym for Auth_MySQL_General_DB, to be used in .htaccess files and
66         directory-specific entries.
67
68 AuthMySQL_DefaultDB <database_name>
69         Synonym for Auth_MySQL_General_DB.
70
71 AuthMySQL_DB <database_name>
72         Synonym for Auth_MySQL_General_DB, to be used in .htaccess files and
73         directory-specific entries.
74
75 AuthName "<Realm>"
76         Describes the data you're guarding.
77
78 AuthType <type>
79         The authentication process used in the transaction.  Stick with
80         Basic, no others work at present.
81
82 require <type> <identifier(s)>
83         Specify what is considered a valid authentication.  <type> can be
84         either user, group, or valid-user.  valid-user is the simplest -
85         anyone who gets the username and password right gets in.  Otherwise,
86         the user must either have a username in the space-separated list of
87         identifiers (if using user) or must be a member of a group in the
88         list of identifiers (if user group).
89         
90         Multiple require statements are allowed; if multiple require
91         statements are present in a configuration, then the user will be
92         considered authenticated if they can satisfy any of the require
93         statements supplied.
94
95 Auth_MySQL_Password_Table <password_table_name>
96         The name of the MySQL table in the specified database which stores
97         username:password pairs.  By default, it is 'mysql_auth'.
98
99 AuthMySQL_Password_Table <password_table_name>
100         Synonym for Auth_MySQL_Password_Table.
101
102 Auth_MySQL_Group_Table <group_table_name>
103         As per ...Password_Table above, stores username:group pairs. 
104         Normally you'll store username:password:group triplets in the one
105         table, but we are nothing if not flexible.  Defaults to
106         'mysql_auth'.
107
108 AuthMySQL_Group_Table <group_table_name>
109         Synonym for Auth_MySQL_Group_Table.
110
111 Auth_MySQL_Username_Field <username_field_name>
112         The name of the field which stores usernames.  Defaults to
113         'username'. The username/password combo specified in Auth_MySQL_Info
114         must have select privileges to this field in the Password and Group
115         tables.
116
117 AuthMySQL_Username_Field <username_field_name>
118         Synonym for Auth_MySQL_Username_Field.
119
120 Auth_MySQL_Password_Field <password_field_name>
121         As per ...Username_Field above, but for passwords.  Same MySQL
122         access privileges.  Defaults to 'password'.
123
124 AuthMySQL_Password_Field <password_field_name>
125         Synonym for Auth_MySQL_Password_Field.
126
127 Auth_MySQL_Group_Field <group_field_name>
128         As per ...Username_Field above.  Defaults to 'groups'.
129         
130 AuthMySQL_Group_Field <group_field_name>
131         Synonym for Auth_MySQL_Group_Field.
132         
133 Auth_MySQL_Group_User_Field <field_name>
134         The name of the field in the groups table which stores the username. 
135         Defaults to the field name specified for usernames in the passwords
136         table.
137
138 AuthMySQL_Group_User_Field <field_name>
139         Synonym for Auth_MySQL_Group_User_Field.
140
141 Auth_MySQL_Password_Clause <SQL fragment>
142         Adds arbitrary clause to username:password matching query, for example:
143         " AND Allowed=1". Clause has to start with space. Default is empty.
144
145 Auth_MySQL_Group_Clause <SQL fragment>
146         Adds arbitrary clause to username:group matching query, for example:
147         " AND Allowed=1". Clause has to start with space. Default is empty.
148  
149 Auth_MySQL_Empty_Passwords <on/off>
150         Whether or not to allow empty passwords.  If the password field is
151         empty (equals to '') and this option is 'on', users would be able to
152         access the page by just specifying their username WITHOUT ANY
153         PASSWORD CHECKING.  If this is 'off', they would be denied access. 
154         Default: 'on'.
155
156 AuthMySQL_Empty_Passwords <on/off>
157         Synonym for Auth_MySQL_Empty_Passwords.
158
159 Auth_MySQL_Encryption_Types <type_list>
160
161         Select which types of encryption to check, and in which order to
162         check them.  It overrides the legacy Auth_MySQL_Scrambled_Passwords
163         and Auth_MySQL_Encrypted_Passwords directives.  Multiple encryption
164         types may be specified, to instruct the module to check each
165         password in multiple encryption schemes - a useful feature for
166         legacy transitions.  For example:
167
168         Auth_MySQL_Encryption_Types Plaintext Crypt_DES
169
170         Would instruct the module to do a direct comparison of the entered
171         password with the contents of the password field, and if that fails,
172         to do a DES crypt() check, a la Unix password handling.  
173
174         The available encryption types supported at this time are:
175         
176         Plaintext
177                 Pretty self-explanatory.  Not recommended.
178                 
179         Crypt_DES
180                 Check the password via the standard Unix crypt() call, using
181                 DES hashing.
182
183         Crypt_MD5
184                 Check the password via the standard Unix crypt() call, using
185                 an MD5 hash.
186         
187         Crypt
188                 Check the password via the standard Unix crypt() call,
189                 without preference for the hashing scheme employed.  This is
190                 the generally preferred means of checking crypt()ed
191                 passwords, because it allows you to use other schemes which
192                 may be available on your system, such as blowfish.
193                 
194         PHP_MD5
195                 Compares with an MD5 hash, encoded in the way that PHP and
196                 MySQL handle MD5 hashes - 32 character hex code, with
197                 lowercase letters.
198
199         SHA1Sum
200                 Compares with a SHA1 hash, encoded the way that MySQL, PHP,
201                 and the sha1sum command produce their output (a 40 character
202                 lowercase hex representation).
203
204         MySQL
205                 The hashing scheme used by the MySQL PASSWORD() function.
206                 
207 AuthMySQL_Encryption_Types <type_list>
208         Synonym for Auth_MySQL_Encryption_Types.
209
210 Auth_MySQL_Encrypted_Passwords <on/off> (DEPRECATED)
211         Equivalent to: Auth_MySQL_Encryption_Types Crypt_DES
212         Only used if ...Encryption_Types is not set.  Defaults to 'on'.  If
213         both this option and ...Scrambled_Passwords are 'off' and
214         ...Encryption_Types is not set, passwords are expected to be in
215         plaintext.
216
217 AuthMySQL_Encrypted_Passwords <on/off> (DEPRECATED)
218         Synonym for Auth_MySQL_Encrypted_Passwords.
219
220 Auth_MySQL_Scrambled_Passwords <on/off> (DEPRECATED)
221         Equivalent to: Auth_MySQL_Encryption_Types MySQL
222         The same restrictions apply to this directive as to
223         ...Encrypted_Passwords.
224
225 AuthMySQL_Scrambled_Passwords <on/off> (DEPRECATED)
226         Synonym for Auth_MySQL_Scrambled_Passwords.
227
228 Auth_MySQL_Authoritative <on/off>
229         Whether or not to use other authentication schemes if the user is
230         successfully authenticated.  That is, if the user passes the MySQL
231         authentication, they may still be rejected by a later module if this
232         option is set 'off'.  The default is 'on' (i.e. if the user passes
233         the MySQL module, they're considered OK).
234
235 AuthMySQL_Authoritative <on/off>
236         Synonym for Auth_MySQL_Authoritative.
237
238 Auth_MySQL_Non_Persistent <on/off>
239         If set to 'on', the link to the MySQL server is explicitly closed
240         after each authentication request.  Note that I can't think of any
241         possible good reason to do this, unless your platform makes MySQL go
242         crazy when it has plenty of simultaneous threads (bad handling of
243         file descriptors may cause that).  In my opinion, one should
244         increase the maximum number of simultaneous threads in MySQL and
245         keep this option off.  Default: off, and for good reason.
246
247 AuthMySQL_Persistent <on/off>
248         An antonym for Auth_MySQL_Non_Persistent.
249
250 AuthMySQL_AllowOverride <on/off>
251         Whether or not .htaccess files are allowed to use their own
252         Host/User/Password/DB specifications.  If set to 'off', then the
253         defaults specified in the httpd.conf cannot be overridden.
254
255 Auth_MYSQL <on/off>
256         Whether or not to enable MySQL authentication.  If it's off, the
257         MySQL authentication will simply pass authentication off to other
258         modules defined.
259
260 AuthMySQL <on/off>
261         Synonym for Auth_MYSQL.