Home

 

Configure Files and Wikis downloading for production deployments


Overview

You can make downloading files from the Files and Wikis features much more efficient by configuring an IBM HTTP Server to handle most of the download instead of the WAS. It is strongly recommended that you configure production deployments this way.

Install an IHS in your WAS environment. See the topic Configuring IHS for information.

In network deployments, Files and Wikis content must be stored on a shared file system, as described in the topic Installing the first node of a cluster. All IHSs in the deployment must have read access to the files, and all WASs must have write access.

If you choose not to configure the IHS to download files, configure the WAS to transfer data synchronously instead of asynchronously in order to avoid errors related to using too much memory. See the tech note Excessive native memory use in IBM WAS for instructions.

With IHS configured to download files, active content filtering no longer strips scripts out of XHTML or HTML files when they are downloaded from Files or attachments downloaded from Wikis. The activeContentFilter property in both files-config.xml and wikis-config.xml is ignored. (Active content filtering continues to run on Wiki pages.) Active content filtering is a security measure against cross-site scripting attacks. To protect against cross-site scripting attacks when IHS is configured to perform downloads, create a sub-domain. See the topic Minimizing cross-site scripting attacks for information on creating sub-domains.

In the default deployment with an IHS, file download requests are passed from the IHS to the WAS. The WAS accesses the binary files in a data content on the file system and returns them to the IHS, which passes them to the browser.

This is inefficient in deployments where large numbers of users are downloading files, partly because WAS has a limited thread pool that is tuned for short-lived transactions, and optimized for J2EE applications and not file downloads. In this environment it is possible that you would need to create a cluster to handle downloads, especially if you have slow transfer rates, for example caused by people in different geographies downloading 2MB at 2KB per second. This would cause problems, such as making it impractical to properly tune the thread pool.

Configure the IHS to download the binary files instead makes downloading far more efficient, since IHS is designed specifically for serving files. This leaves WAS to perform tasks such as security checking and cache validation while leaving downloading to the IHS.

To configure this environment, you install an add-on module to the IHS. As in typical deployments, download requests are passed from the IHS to the WAS. But instead of responding with the binary content, the WAS only adds a special header to its response. The add-on module recognizes the header and directs the IHS to download the binary data.

This configuration requires making the Files and Wikis data available to the IHS using an alias. This creates a security concern, so configure the access control at the IHS level. After you configure security, access to the Files and Wikis data is denied unless a specific environment variable is set. Requests to the Files and Wikis applications on WAS are then configured to set the variable. In other words, only requests passing through WAS are able to access the data directory, with WAS acting as the authorizer.


Configure IHS downloading

  1. Install the IBM Lotus Connections Files or Wikis features.

  2. On the server that you installed Lotus Connections on, navigate to...

      <connections_setup_directory>/plugins/ihs/mod_ibm_local_redirect/<platform>

    ..to find the module file...

      mod_ibm_local_redirect.so

    ..appropriate to your IHS operating system. These are the platform sub-directories:

    • /aix_ppc32-ap20
    • /aix_ppc32-ap22
    • /linux_ia32-ap20
    • /linux_ia32-ap22
    • /win_ia32-ap20
    • /win_ia32-ap22

    For example:

      <connections_setup_directory>/plugins/ihs/mod_ibm_local_redirect/ aix_ppc32-ap20/mod_ibm_local_redirect.so

    You can use these whether you installed IHS from the 32-bit or 64-bit supplemental package on all supported platforms, as the IHS process is 32-bits in both cases and requires 32-bit modules. See this support document for more information on this topic. For IHS 6.1.x releases, use the ap20 versions; for version 7.x releases use the ap22 version.

    <connections_setup_directory> is the Lotus Connections set-up where install.bat (on Microsoft Windows®) or install.sh (on AIX or Linux®) is located.

  3. Copy the module to the appropriate location on your IHS. By default, modules are located in...

  4. Open the IHS httpd.conf file...

    ..and add the following statements to load the ibm_local_redirect_module, and the required mod_env content cache storage manager module:

    • LoadModule ibm_local_redirect_module <path_to_module>/ mod_ibm_local_redirect.so
    • LoadModule env_module <path_to_mod_env>/mod_env.so

    By default, the mod_env module is installed in the /module It may already be loaded, or it may be a commented-out line that you can remove comments from to load.

  5. Do one of the following, according to your IHS operating system:

    • Microsoft Windows: Give the IHS user READ access to the data directory. For optimal security, do not give the user WRITE access.

    • AIX and Linux: Give the IHS user READ and EXECUTE access to the data

  6. On all virtual hosts in the same domain as Files or Wikis, including both HTTP and HTTPS, do the following to expose the content directory:

    1. Open the httpd.conf file.

    2. Add the following to create an alias for the content directory:

    • Do not use the application context root (/files or /wikis by default) as part of the alias, but you can use any other value. For example, use /data, but not /files/data.

    • <data_directory_root> is an absolute (not relative) path to the root data where files are stored. It must not include the /files or /temp sub-directories just below the root, which are created if the application has been started.

    • You can find the <data_directory_root> path in the {files or wikis}-config.xml file, in the file.storage.rootDirectory element. This element will contain either the path itself, or a WAS variable whose value is the path. If it contains a variable, you can find the path by opening the WAS console, clicking Environment > WebSphere Variables, and finding the variable. For example, if the element's value is ${FILES_CONTENT_DIR}, find FILES_CONTENT_DIR in the console to find the path. See the topic Changing configuration property values for information on opening the {files or wikis}-config.xml file.

  7. In the httpd.conf file, add these lines below the lines you added in Step 6, to make the alias more secure: 

      <Directory "<data_directory_root>">
 Order Deny,Allow
 Deny from all
 Allow from env=REDIRECT_{FILES or WIKIS}_CONTENT
 </Directory>

    • This secures the content by only showing it to requests where REDIRECT_{FILES or WIKIS}_CONTENT is specified (for example REDIRECT_FILES_CONTENT). Use any environment variable you want, as long as it is not already in the IHS environment.

  8. In the httpd.conf file, add these lines below the lines you added in Step 7, to enable the module for Files or Wikis: 

      <Location <context_root>>
 IBMLocalRedirect On
 IBMLocalRedirectKeepHeaders X-LConn-Auth,Cache-Control,Content-Type,Content-Disposition,Last-Modified,ETag,Content-Language,Set-Cookie
 SetEnv {FILES or WIKIS}_CONTENT true
</Location>

    • The <context_root> value is the context root for the application. This is /files or /wikis by default, but can be changed during post-installation steps. You can see the value in the files.href.prefix property in the LotusConnections-config.xml file. See the topic Changing common configuration property values for information on opening the configuration file.

    • Specify IBMLocalRedirectKeepHeaders instructs the plugin to keep the specified headers from the application server, instead of recomputing them. This is critical because the applications set such directives as the content-type and content-disposition that the IHS would not know about.

    • If your environment requires additional headers (for example for a proxy cache), you can add them to the comma-delimited IBMLocalRedirectKeepHeaders list above to ensure that the module retains them during redirection.

    • Header names must be comma-delimited with no space before or after commas. Also, all header names must be on one line regardless of how many there are.

    • The SetEnv value sets the token that the content requires to be accessible. It must match the value after

      REDIRECT_

      that you set in Allow from env= in Step 7. For example, if you set

      REDIRECT_FILES_CONTENT

      in Step 7, this value must be

      SetEnv FILES_CONTENT

    • You can think of this as a lock and key mechanism: only requests that go through the Files or Wikis applications get a key, and the applications ensure that only the right users can unlock particular files.

  9. Do the following to test that the IHS is configured properly and securely:

    1. Restart the IHS. Make sure it loads properly and there are no log errors about loading modules or configuration. If there are problems, make sure the load module and configuration directives do not contain typos.

    2. Try to access the alias directly at http/https:<host>/<{wikis or files}_alias> and make sure you are denied permission. If you can access the directory, make sure that the Order Deny, Allow; Deny from All; Allow from env from Step 7 are all there.

    3. Access the application and download a file to make sure it functions.

  10. Check out the files-config.xml or wikis-config.xml file using the steps in the topic Changing configuration property values, and specify the following property attributes: 

      <download><modIBMLocalRedirect enabled="true" hrefPathPrefix="/<{wikis or files}_alias>" /></download>

    The alias must have a forward slash in front of it.

  11. Restart Files or Wikis.

  12. Download a file to make sure it works.

  13. Do the following to test whether the IHS is downloading the files:

    1. Open the httpd.conf file and add # characters to comment out the last two lines in the <Directory> element, for example: 

        <Directory "<data_directory_root>">
 Order Deny,Allow
 Deny from all
 #Allow from env=REDIRECT_{FILES or WIKIS}_CONTENT
</Directory>

    2. Save the file.

    3. Try to download a file from Files or Wikis. You should be denied. Test over both HTTP and HTTPS protocols (if HTTPS is enabled).

    4. Open the httpd.conf file and remove the # characters from the last two lines specified in Step a.

    Check the standard IHS error and request logs for any problems.


Performing feature-specific tasks

 

Related tasks

Installing
Configure IHS
Install the first node of a cluster
Specify a separate file download domain
Change common configuration property values
Change configuration property values
Specify a separate file download domain
Files configuration properties
Wikis configuration properties

+

Search Tips   |   Advanced Search