Configure Files and Wikis downloading for production deployments 

You can make downloading files from the Files and Wikis applications 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.

Before starting

Install an IBM HTTP Server in your WAS environment. See the topic Configure IBM HTTP Server for information.

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

If you choose not to configure the IBM HTTP Server 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.

About this task

In the default deployment with an IBM HTTP Server, file download requests are passed from the IBM HTTP Server to the WAS. The WAS accesses the binary files in a data directory on the file system and returns them to the IBM HTTP Server, 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.

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

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

This configuration requires making the Files and Wikis data directories available to the IBM HTTP Server using an alias. This creates a security concern, so configure the access control at the IBM HTTP Server level. After you configure security, access to the Files and Wikis data directories 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.

If you use the add-on module use an IBM HTTP Server address for the IBM Connections "inter-service" URL. See the topic Troubleshooting inter-server communication for information on setting an inter-service URL.

Do the following tasks to configure IBM HTTP Server downloading:

Procedure

1. Install the IBM Connections Files or Wikis applications.

2. On the server that you installed IBM Connections on, navigate to...
   <lotus_connections_root>/plugins/ihs/mod_ibm_local_redirect/<platform>

   ...to find the module file...

   mod_ibm_local_redirect.so

   ...appropriate to your IBM HTTP Server operating system. These are the platform directories:
   

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

   For example, on Linux computers:

   /opt/IBM/LotusConnections/plugins/ihs/mod_ibm_local_redirect/linux_ia32-ap20/mod_ibm_local_redirect.so

   <connections_setup_directory> is the IBM Connections setup directory where install.bat (on Microsoft Windows) or install.sh (on AIX or Linux) is located.

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

3. Copy the module to the appropriate directory location on your IBM HTTP Server. By default, modules are located in the ibm_http_server_root>/modules directory.

4. Edit and add the following statements to load the ibm_local_redirect_module, and the required mod_env environment variable module:
   LoadModule ibm_local_redirect_module <path_to_module>/mod_ibm_local_redirect.so
   
   

   • For example: LoadModule ibm_local_redirect_module modules/mod_ibm_local_redirect.so
     LoadModule env_module <path_to_mod_env>/mod_env.so
     
     

   • For example: LoadModule env_module modules/mod_env.so
     
   Note: By default, the mod_env module is installed in the /modules directory. 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 IBM HTTP Server operating system:

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

   • AIX and Linux: Give the IBM HTTP Server user READ and EXECUTE access to the data directory root.
     
   Note: You can find the data_directory_root> path in the files-config.xml or wikis-config.xml file, in the file.storage.rootDirectory attribute. This attribute 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 Change configuration property values for information on opening the files-config.xml or wikis-config.xml file.
   

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

   1. Open the httpd.conf file.

   2. Add the following to create an alias for the data directory root:
      
      Alias /<alias> <data_directory_root>

      For example, if the Files data directory root is /opt/IBM/LotusConnections/Data/Files (on Linux), the following line creates the alias files_content for that directory:

      Alias /files_content /opt/IBM/LotusConnections/Data/Files

   Note:
   

   • 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 /files_content, but not /files/content. The application context root is the last part of the application URL, for example the application context root of a Files application with the URL www.my.enterprise.com/files is /files. You can see the value in the files.href.prefix property in LotusConnections-config.xml. See the topic Change common configuration property values for information on opening the configuration file.

   •  Include quotes around the file path on Windows computers, and always use forward slashes, for example: "C:/Program Files/IBM/LotusConnections/Data/Files"

   • The example assumes the HTTP server is on the same computer as IBM Connections. If the HTTP server is on a different computer (as is common), specify the data directory using the network share path appropriate to your environment. For example, use a UNC network share format such as:
     Alias /files_content "//<server>/<sharename>/Files"

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>

   For example:

   <Directory "/opt/IBM/LotusConnections/Data/Files">

   Order Deny,Allow Deny from all Allow from env=REDIRECT_FILES_CONTENT </Directory>

   Note:
   

   • This secures the data by only allowing requests where REDIRECT_FILES_CONTENT or REDIRECT_WIKIS_CONTENT is specified. Use any environment variable you want, as long as it is not already in the IBM HTTP Server environment.

   • The example assumes the HTTP server is on the same computer as IBM Connections. If the HTTP server is on a different computer (as is common), specify the data directory using the network share path appropriate to your environment. For example, use a UNC network share format such as:

     <Directory "//<server>/<sharename>/Files">

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

   For example:

   <Location /files>
   

   IBMLocalRedirect On IBMLocalRedirectKeepHeaders X-LConn-Auth,Cache-Control,Content-Type,Content-Disposition, Last-Modified,ETag,Content-Language,Set-Cookie SetEnv FILES_CONTENT true </Location>

   The <application_context_root> value is the last part of the application URL, for example the application context root of a Files application with the URL www.my.enterprise.com/files is /files. 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 LotusConnections-config.xml. See the topic Change 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 IBM HTTP Server 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 data directory 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 true.

   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.

   • Do the following to test that the IBM HTTP Server is configured properly and securely:

     1. Restart the IBM HTTP Server. 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 directory directly at http/https:<host>/<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. The module is not yet enabled.
        

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

     <download>

     <modIBMLocalRedirect enabled="true" hrefPathPrefix="/<alias>" /> </download>

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

   • Restart Files or Wikis.

   • Download a file to make sure it works.

   • Do the following to test whether the IBM HTTP Server is downloading the files:

     1. Open the httpd.conf file and add # characters to comment out the last line 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>

        For example:

        <Directory "C:\Program Files\IBM\LotusConnections\Data\Files">

        Order Deny,Allow Deny from all #Allow from env=REDIRECT_FILES_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 line specified in Step a.
        
     Check the standard IBM HTTP Server error and request logs for any problems.
     

What to do next

• If you get a permission denied error trying to download a file, IBM HTTP Server may not have access to the content. You can temporarily disable security on the directory, and ensure you can access it directly first, then re-enable security. Note that you can tell if WebSphere or IBM HTTP Server is encountering an issue by the error page displayed, and by the path. If IBM HTTP Server is having a problem with the module invoked, the path will include /<alias>.

• If you get log errors about loading the module, make sure that it is only loaded once, that you have selected the right binary, and that you are on a supported platform.

• If it works for HTTP but not HTTPS (or vice versa), make sure that the configuration lines are in a global context or in each virtual host, depending on your setup.

Parent topic

Optional post-installation tasks

Related concepts
Installing
Configure IBM HTTP Server

Related tasks

Install IBM Connections 3.0.1
Change common configuration property values
Change Files configuration property values
Define IBM HTTP Server
Specify a separate file download domain

Related reference
Files configuration properties
Wikis configuration properties

+

Search Tips   |   Advanced Search