Commit | Line | Data |
---|---|---|
805e021f CE |
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/ |