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/