| 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/ |