spelling corrections in readme files
[openafs.git] / src / afsweb / README.BETA2
1 Copyright 2000, International Business Machines Corporation and others.
2 All Rights Reserved.
3
4 This software has been released under the terms of the IBM Public
5 License.  For details, see the LICENSE file in the top-level source
6 directory or online at http://www.openafs.org/dl/license10.html
7
8 AFS Web Security Pack Version 1.0 for the Apache Web Server.
9
10 Release Notes
11
12 I. Introduction
13
14 AFS Web Security Pack is an extension available for selected Web servers 
15 that enables system administrators to provide secure access via a 
16 Web browser to documents stored in the AFS filespace. This document 
17 summarizes the changes made to AFS Web Security for this release, and 
18 provides installation and configuration instructions. 
19
20 Note: Due the long filenames and file extensions used for the AFS Web 
21 Security Pack distribution files, download of the AFS Web Security Pack
22  product to a PC sometimes results in incorrect filenames. Note that all 
23 AFS Web Security Pack distribution files are g-zipped tar files, even if the 
24 *.tar.gz file extension is lost during the download process. 
25
26 II. Installation Prerequisites
27
28 Your system must meet the following software and disk space requirements 
29 to install this version of AFS Web Security Pack.
30
31 Operating system:        Solaris 2.5.1, AIX 4.1, AIX 4.2, or AIX 4.2.1 
32 Web server:              Apache 1.2.6 
33 AFS (client):            AFS Client 3.4a 
34 Disk Space:              650 KB 
35
36 Note: Due to security considerations, OpenAFS strongly recommends that 
37 AFS Web Security Pack be used only on a server enabled with Secure 
38 Sockets Layer (SSL).
39
40 III. New Features and Product Changes
41
42 The following list describes new features and changes that are included 
43 in this version of AFS Web Security Pack.
44
45 *  Configuration of AFS Web Security Pack is now easier and more flexible. The 
46 AFSMountPointDir and AFSLocation directives are no longer required. 
47 Instead, during configuration of AFS Web Security Pack, an authorization type 
48 (AFSAuthType) of AFS is now specified. (See the Installation and Configuration 
49 instructions that follow for additional details.)
50
51 *  The Log In dialog box that is displayed when users attempt to access 
52 the AFS file space via a web browser can now be customized adding the 
53 AFSLoginPrompt directive to the Apache server runtime configuration 
54 file. (See the Installation and Configuration instructions that follow for 
55 additional details.)
56
57
58
59 *  AFS Web Security Pack now provides the ability to log attempts to 
60 access AFS in which permission is denied. This logging can be used to 
61 determine if users are attempting to access information that they are not
62  authorized to view. To configure this logging, you must add the
63  SetAFSAccessLog directive to the Apache server runtime configuration file. 
64 (See the Installation and Configuration instructions that follow for 
65 additional details.)
66
67 *  AFS Web Security Pack now provides the ability to translate and access user 
68 directories that are specified with a special character such as a tilde (~), 
69 for example. http://www.yourcompany.com/~smith. To enable this feature, you 
70 must add the User Directory directive to the Apache server runtime 
71 configuration file. (See the Installation and Configuration instructions 
72 that follow for additional details.)
73
74 *  The previous version of AFS Web Security Pack did not correctly permit 
75 directory indexing of directories for which a user was assigned lookup 
76 permission. In addition, the Parent Link in directory indexes did not 
77 always work correctly. This version of AFS Web Security Pack corrects these 
78 problems.
79
80 *  This version of AFS Web Security Pack corrects a problem with the token cache 
81 that occasionally caused access to AFS to be incorrectly denied.
82
83 *  The previous version of AFS Web Security Pack did not accept AFS passwords 
84 that included a space. This version of AFS Web Security Pack corrects this problem.
85
86 *  This version of AFS Web Security Pack corrects a communication (pipe) problem 
87 that occasionally caused the message SERVER_ERROR to be returned. In 
88 addition, this version improves performance of AFS Web Security Pack.
89
90 IV. Known Defects and Limitations 
91
92 * Due to a preexisting problem in the AFS UNIX product, the Apache 
93 server Fancy Indexing option does not function as expected when AFS 
94 directories are displayed. If the Fancy Indexing option is enabled 
95 on the Apache server, when a user initially browses an ACL-protected 
96 directory (with "system:anyuser l" access), the user is able to see 
97 file details for directories and links, but not for files. Once the 
98 user selects a file and enters a username and password, details for 
99 the files are then displayed. This problem is not caused by AFS Web 
100 Security Pack or the Apache server, but is due to a defect in the UNIX-based 
101 AFS code. We are working to address this problem and will make an 
102 announcement when a corrected version is available. In the interim, 
103 please be aware of this limitation as you continue testing. 
104
105 V. Upgrade Instructions for AFS Web Security Pack for the Apache Web Server 
106
107 Note: Use the following instructions to upgrade AFS Web Security Pack on 
108 your Apache Web Server if Beta Version 1 or Beta Version 2 of the product 
109 is already installed. (If this is the first time you are installing AFS Web 
110 Security Pack, follow the instructions in the next section, Installing and 
111 Configuring AFS Web Security PAck 1.0 for the Apache Web Server.)
112
113 1. Replace the existing versions of the weblog, weblog_starter and 
114 libapacheafs.a files with the new files provided with this version 
115 of AFS Web Security Pack 1.0. Also, in the Apache src directory, 
116 replace the mod_afs.c or afs_module.c file with the new AFS Web Security Pack
117 Module, afs_module.c. 
118
119 2. In the Apache server Configuration file, change the line that 
120 references the AFS Web Security Pack module so that the line appears as 
121 follows:
122
123     Module afs_module       afs_module.o
124
125 Note: If you want to enable AFS Web Security Pack to translate and access user
126  home directories, you must include the userdir_module when you build 
127 the Apache server. For information on including modules when building 
128 the Apache server, consult you Apache server documentation.
129
130 3. In the Apache server src directory, run the Configure script to 
131 create a new configuration Makefile for your operating system. 
132
133 4. Stop the Apache server process (httpd). Then, issue the make 
134 command to compile the Apache server. 
135
136 5. In the Apache server runtime configuration file, remove (or comment 
137 out) the following two lines:
138
139     SetAFSMountpointDir /afs_mountpoint_directory
140     SetAFSLocation /afs_location
141
142 6. In the Apache server runtime configuration file, replace (or 
143 comment out) the SetHandler afs-authentication parameter with the 
144 AFSAuthType AFS parameter, so that the Location directive appears as 
145 follows:
146
147     <Location /afs>
148     AFSAuthType AFS
149     </Location>
150
151 where /afs is the directory (or symbolic link to the directory) 
152 that contains the mount points to AFS to be used by the Apache 
153 server and AFS Web Security Pack. 
154
155 Note: You can specify AFSAuthType AFS for multiple locations to indicate 
156 that AFS Web Security Pack authentication must be used when a user attempts to
157 access a specific location. (In specifying a location, you can use wildcard 
158 characters if desired.)
159
160 7. (Optional) To customize the authorization dialog box that is 
161 displayed when users attempt to access the AFS file space via a 
162 web browser, add the following line within the Location directive:
163
164     AFSLoginPrompt [Custom Text]
165
166 where [Custom Text] is the text that you want to appear in the dialog 
167 box that prompts users to enter a user name and password to access AFS 
168 filespace.
169
170 8. (Optional) To enable AFS Web Security Pack to access user directories, 
171 add the following lines to the Apache server runtime configuration 
172 file. This directive specifies the syntax used to access user 
173 directories and indicates that attempts to access user directories 
174 in the AFS filespace must be passed to AFS Web Security Pack:
175
176     <Location /~*>
177     AFSAuthtype AFS
178     </Location>
179
180 Then, add the following line to the Apache server runtime configuration 
181 file to indicate the location of user directories in AFS:
182
183     UserDir [Users Directory]
184
185 where Users Directory indicates the location of user's home directories.
186
187 Note: To enable user directory access in this manner, the Apache Server 
188 must include the UserDir module. For information on including this 
189 module when building the Apache server, consult you Apache server 
190 documentation.
191
192 9. (Optional) To enable logging of attempts to access AFS in which 
193 permission is denied, add the SetAFSAccessLog directive to the Apache 
194 server runtime configuration file as follows:
195
196     SetAFSAccessLog [Access Log File]
197
198 where [Access Log File] is the full path log file in which failed access 
199 attempts are to be recorded. 
200
201 10. If necessary, rename the symbolic link to the AFS filespace in the 
202 Apache server's document root directory with the name specified in the 
203 Location directive for the AFS filespace in the server's runtime 
204 configuration file. 
205
206 VI. Installing and Configuring AFS Web Security Pack 1.0 for the Apache Web Server
207
208 This section provides brief installation and configuration instructions 
209 for Apache AFS Web Security Pack (Version 1.0 for Apache version 1.2.6 
210 and Apache version 1.3.1). See the product documentation for complete installation 
211 and configuration instructions and for details about using the configuration script to 
212 set up AFS Web Security Pack on the Apache server.
213
214 1. Uncompress and extract the files from the .tar.gz file, placing the 
215 files in the following locations, where Apache Installation Directory 
216 is the full pathname of the directory where the Apache Web server is 
217 installed:
218
219 -    Place both the weblog and weblog_starter files in one directory, 
220 for example, Apache Installation Directory/afswebsecurity. These files 
221 can be placed in any directory as long as they remain together. However, 
222 if the weblog and weblog_starter files are placed in a directory in AFS, 
223 ensure that either the user that the Apache Web server runs as, or the 
224 AFS group system:anyuser is designated as having read and lookup privileges 
225 on the directory's Access Control List (ACL). 
226
227 -    Place the libapacheafs.a file in any directory, for example, 
228 Apache Installation Directory/afswebsecurity. 
229
230 -    Place the afs_module.c file in the Apache src directory (Apache version 1.2.6)
231 or in the src/modules/extra directory (Apache version 1.3.1)
232 (generally located directly beneath the Apache Installation Directory). 
233
234 In addition, note the location of the AFS library file, libsys.a. This 
235 file is installed with the AFS client, and is generally located in the 
236 /usr/afsws/lib/afs directory. 
237
238 2. Modify the Apache Server Configuration File as follows.
239
240 Locate the EXTRA_LIBS line in the file, and add the paths to the 
241 libapacheafs.a and libsys.a libraries so that the line reads as follows: 
242
243     EXTRA_LIBS=[full path to libapacheafs.a] [full path to libsys.a]
244
245 In the Module configuration section of the file, add a reference to the 
246 AFS Web Security Pack module. It is recommended that the AFS Web Security Pack 
247 module be the first Authentication module.
248 To add the AFS module to the list of Apache server modules, add the following line 
249 to the Configuration file: 
250
251     Module afs_module         afs_module.o
252
253 Note: If you want the server to attempt to stop completely if AFS 
254 initialization fails, also add -DSHUTDOWN_IF_AFS_FAILS to the 
255 EXTRA_CFLAGS line in this file. Otherwise, on startup if the 
256 initialization procedure fails on startup, the Apache server 
257 will continue to run but AFS authentication will always fail.
258
259 3. Modify the Apache Server Runtime Configuration File (for example, 
260 httpd.conf) as follows.
261
262 Add the following lines to the runtime configuration file: 
263
264     SetAFSDefault [Cell cellname]
265     SetAFSCacheExpiration [cache_expiration]
266     SetAFSTokenExpiration [token_expiration]
267     SetAFSWeblogPath [weblog_starter_path]
268
269 where the arguments for these Apache server directives are as follows: 
270
271 [cellname] - The name of the default AFS cell to be accessed via the 
272 Apache server and AFS Web Security Pack.
273
274 [cache_expiration] -The maximum lifetime in seconds of an AFS token 
275 that is stored in the local cache. The default recommendation for 
276 this argument is 300 seconds (5 minutes). 
277
278 [token_expiration] -The maximum lifetime in seconds of an AFS token 
279 that is stored in the AFS kernel Cache Manager. The default 
280 recommendation for this argument is 60 seconds (1 minute). 
281
282 [weblog_starter_path] -The path to the AFS Web Security Pack weblog_starter program. 
283 Specify the full path or a path relative to the path set by the ServerRoot Apache
284 directive. 
285
286 Note: To enable logging of failed attempts to access AFS in which permission 
287 is denied, also add the directive:
288
289     SetAFSAccessLog [Access Log File]
290
291 where [Access Log File] is the full path of the log file in which 
292 failed access attempts are to be recorded.
293
294 Then, add the following additional lines to the runtime configuration file:
295
296     <Location /[afs]>
297     AFSAuthType AFS
298     </Location>
299
300 where [afs] is the request provided by users in combination with the 
301 server hostname and domain in order to access AFS filespace.
302
303 Note: This directive only works within Location (and LocationMatch for Apache 1.3.1)
304 tags and not in any other tags such as Directory or File.
305
306 Note: You can specify AFSAuthType AFS for multiple locations to indicate 
307 that AFS Web Security Pack authentication must be used when a user attempts to
308 access a specific location. (In specifying a location, you can use wildcard 
309 characters if desired.)
310
311 (Optional) To customize the authorization dialog box that is displayed 
312 when a user attempts to access the AFS file space via a web browser, 
313 add the following line to the Location directive added in the previous 
314 step. The Location directive then appears as follows: 
315
316     AFSLoginPrompt [Custom Text]
317
318 where [Custom Text] is the text that you want to appear in the dialog box 
319 that prompts users to enter an AFS user name and password to access the 
320 AFS filespace. 
321
322 (Optional) To enable AFS Web Security Pack to access user directories, add the 
323 following additional Location directive to the Apache server runtime 
324 configuration file. 
325
326     <Location /~*>
327     AFSAuthType AFS
328     </Location>
329
330 Then, also add the following additional line to the Apache server runtime 
331 configuration file to indicate the location of user directories in AFS. 
332
333     UserDir [Users Directory]
334
335 where [Users Directory] indicates the location of user's home 
336 directories in AFS. The location is specified relative to the 
337 server document root directory. 
338
339 Note: To enable user directory access in this manner, the Apache 
340 server must include the User Dir module. 
341
342 Save and close the modified runtime configuration file. 
343
344 4.  Stop the Apache server process (httpd). Then, configure and make 
345 the Apache server and start it up with the new runtime configuration 
346 file.
347
348 5. Add the following to the shutdown or stopd file to shutdown the 
349 weblog_starter process BEFORE the kill -TERM for httpd.pid:
350
351     kill -TERM `cat [path to httpd.pid].afs`
352
353 For example, if the httpd.pid file is in 
354 /local/stronghold/apache/logs/httpd.pid, then the stopd file should 
355 look something like this:
356
357     kill -TERM `cat /local/stronghold/apache/logs/httpd.pid.afs`
358     kill -TERM `cat /local/stronghold/apache/logs/httpd.pid` 
359
360 VII. AFS Web Security Pack Documentation
361
362 Postscript and HTML versions of the documentation for the initial 
363 Beta release AFS Web Security Pack are available in the doc directory. 
364
365 VIII. Additional Information about Apache and SSL
366
367 The following sites on the World Wide Web provide additional information 
368 about the Apache Web Server and SSL.
369
370 * Apache Home Page http://www.apache.org 
371 * Stronghold Home http://www.c2.net 
372 * Stronghold International http://www.int.c2.net 
373 * Apache-SSL Home http://www.apache-ssl.org 
374 * SSLeay FAQ http://www.psy.uq.edu.au:8080/~ftp/Crypto/