Configure file downloads through IBM HTTP Server

Configure file downloads through IBM HTTP Server

Configure IBM HTTP Server to manage file downloads from Activities, Files, Libraries, Mobile, and Wikis. This approach is more efficient than using IBM WebSphere Application Server to manage file downloads.

Ensure that IBM HTTP Server is installed in the WebSphere Application Server environment.
Files, Mobile, and Wikis data must be stored on a shared file system, as described in the Deployment options. The Connections Content Manager uses an optional file cache on the file system for serving files through the HTTP server.
All IHSs in the deployment must have READ access to the files, and all WebSphere Application Server must have WRITE access.
For shared and remote network file system requirements, review footnotes in the system requirements.
If we choose not to configure IHS to download files, configure WebSphere Application Server to transfer data synchronously instead of asynchronously. This configuration avoids errors related to using too much memory.
In a default deployment with IHS, file download requests are passed from IHS to WAS. WAS accesses the files in a data directory on the file system, and returns them to IHS, which passes them to the browser.
When large numbers of users are downloading files, this deployment is inefficient, partly because WAS has a limited thread pool that is tuned for short-lived transactions. In addition, WAS is optimized for JEe applications and not for file downloads. In this type of deployment, you might have to create a cluster to handle downloads, especially if you have slow transfer rates.
Configure IHS to download files makes downloading much more efficient, because IHS is designed specifically for serving files. This configuration leaves WAS to carry out tasks such as security checking and cache validation.
To configure this environment, install an add-on module that directs IHS to download files. When the module is installed, download requests are passed from IHS to the WAS. But instead of responding by downloading the file, WAS adds a special header to its response. The add-on module recognizes the header and directs IHS to download the file.
This configuration requires making the Files, Mobile, and Wikis data directories available to IHS by using an alias. We can also make available the content cache directory from Connections Content Manager.) This configuration creates a security concern, so configure the access control at the IHS level. After you configure security, access to the data through IHS is denied unless a specific variable is set. Requests to the applications on WAS are then configured to set the variable. In other words, only requests that pass through WAS can access the data directory, with WAS acting as the authorizer.
If we use the add-on module, use an IHS address for the Connections inter-service URL. For information on setting an inter-service URL, see the Troubleshooting inter-server communication.
To configure IHS to download files:
Install the Connections Files, Mobile, or Wikis applications, as needed.

On the server where you installed IBM Connections (on the deployment manager), navigate to...
connections_root/plugins/ihs/mod_ibm_local_redirect/platform

...to find the module file (mod_ibm_local_redirect.so).
On supported operating systems, search the following directories:

/aix_ppc32-ap20
/aix_ppc32-ap22
/aix_ppc64-ap22
/linux390-ap20
/linux390-ap22
/linux_ia32-ap20
/linux_ia32-ap22
/linux_ppc64-ap22
/linuxs390_x64-ap22
/linux_amd64-ap22
/win_ia32-ap20
/win_ia32-ap22

For example, on Linux systems, go to the following directory:
/IBM/Connections/plugins/ihs/mod_ibm_local_redirect/linux_ia32-ap20/mod_ibm_local_redirect.so

These directories are valid whether you installed IHS from the 32-bit or 64-bit supplemental package, because the IHS process is 32-bits in both cases and requires 32-bit modules.

For IHS 6.1.x releases, use the ap20 versions; for version 7.x releases use the ap22 version.

Copy the module to the appropriate directory on the system that hosts IHS. By default, modules are stored in the IHS_ROOT/modules directory.

Open httpd.conf (in the IHS_ROOT/conf directory by default) and add the following statements to load the ibm_local_redirect_module, and the 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
By default, the mod_env module is installed in the /modules directory. It might already be loaded, or it might be a commented-out line that we can edit.

Grant access to the data directory root:

AIX or Linux: Give the IHS user READ and EXECUTE access to the data directory root.

Windows: Give the IHS user READ access to the data directory root. For optimal security, do not grant WRITE access.

We can find the data_directory_root path in the file.storage.rootDirectory attribute of the files-config.xml or wikis-config.xml file. This attribute contains either the path itself, or a WAS variable whose value is the path. For information about opening the files-config.xml or wikis-config.xml files, see the Change configuration property values topic. If the attribute contains a variable, for example, if the value is ${FILES_CONTENT_DIR}, examine the FILES_CONTENT_DIR variable in the WAS console to find the path. For more information about WebSphere variables, see the Change WAS environment variables topic.

If the Connections Mobile service is installed, also give IHS access to the FileDiff StoragePath. We can find the FileDiff StoragePath attribute in the FileDiff section of mobile-config.xml. For information about editing mobile-config.xml, see the Change configuration property values topic. This attribute contains either the path itself, or a WebSphere variable whose value is the path. For example, if the value of the variable is ${MOBILE_CONTENT_DIR}, examine the MOBILE_CONTENT_DIR variable in the WAS console to find the path. For more information about WebSphere variables, see the Change WAS environment variables topic.

For Connections Content Manager, the data directory is a shared cache directory available to both IHS and the Libraries servers (or FileNet Collaboration Services). For Connections Content Manager, the data_directory_root refers to this cache location and is configured in step 11.

In some situations, granting access at the data directory root might not work for you. For example, where the value of FILES_CONTENT_DIR is \\server\Shared\files\upload, giving READ access to the user is not useful because they do not have any rights to the share. Instead, give the user Read access at the share point of \\server\Shared.

You must give the HTTP server the appropriate level of access to each content store root defined in oa-config.xml. The content store roots are defined in the root.directory property of each <store> element.
For example:
<property name="root.directory">${ACTIVITIES_CONTENT_DIR}</property>

Libraries only: Create the <Connections_Shared>/ccmcache directory.

On all virtual hosts in the same domain as Activities, Files, Mobile, Libraries, or Wikis, including both HTTP and HTTPS, expose the data directory root:

Open httpd.conf.

To create an alias for the data directory root, add the following line:
alias /<alias> "data_directory_root"

For example, if the Files data directory root on a Linux system is /opt/IBM/Connections/Data/Files, the following line creates the files_content alias for that directory:
alias /files_content /opt/Connections/data/shared/files

A similar example for Libraries:
alias /library_content_cache /opt/IBM/Connections/data/shared/ccmcache

A similar example for Mobile:
alias /mobile_content /opt/IBM/Connections/data/shared/mobile

A similar example for Wikis:
alias /wikis_content /opt/IBM/Connections/data/shared/wikis

For Activities, we must define a separate alias for each content store root, for example:
alias /activities_content /opt/IBM/Connections/activities/content

You must create the directory used in this step.

Do not use the application context root (/connections/filediff, /dm, /files, /mobile, or /wikis) as part of the alias. We can use any other value. For example, use /files_content, but not /files/content. The application context root is the path part of the application URL. For example the application context root of a Files application with the URL www.my.myco.com/files is /files. We can find 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 quotation marks around the file path on Windows systems, and always use forward slashes, for example: "C:/IBM/Connections/Data/Files"

The example assumes the HTTP server is on the same system as IBM Connections. If the HTTP server is on a different system, specify the data directory using the network share path appropriate to the environment. For example, use a UNC network share format such as: alias /files_content "//server/sharename/Files".
To make the alias more secure, add the following lines to httpd.conf, adding them after the lines added in Step 6:
<Directory "data_directory_root">
   Order Deny,Allow
   Deny from all  Allow from env=REDIRECT_FILES_CONTENT or REDIRECT_LIBRARIES_CONTENT or REDIRECT_MOBILE_CONTENT or REDIRECT_WIKIS_CONTENT
</Directory>
For example:
<Directory "/opt/IBM/Connections/activities/content">
   Order Deny,Allow
   Deny from all  Allow from env=REDIRECT_ACTIVITIES_CONTENT
</directory>

<Directory "/opt/IBM/Connections/data/shared/files">
   Order Deny,Allow
   Deny from all  Allow from env=REDIRECT_FILES_CONTENT
 </Directory>

<Directory "/opt/IBM/Connections/data/shared/ccmcache">
   Order Deny,Allow
   Deny from all  Allow from env=REDIRECT_LIBRARIES_CONTENT
 </Directory>

<Directory "/opt/IBM/Connections/data/shared/mobile
   Order Deny,Allow
   Deny from all  Allow from env=REDIRECT_MOBILE_CONTENT
 </Directory>

<Directory "/opt/IBM/Connections/data/shared/wikis">
   Order Deny,Allow
   Deny from all  Allow from env=REDIRECT_WIKIS_CONTENT
 </Directory>
This definition secures the data by allowing requests where REDIRECT_FILES_CONTENT or REDIRECT_LIBRARIES_CONTENT or REDIRECT_MOBILE_CONTENT or REDIRECT_WIKIS_CONTENT only is specified. Use any environment variable you want, provided it is not already in the IHS environment.

The example assumes that IHS is on the same system as IBM Connections. If IHS is on a different system, specify the data directory using the network share path appropriate to the environment. For example, use a UNC network share format such as the following example: : <Directory "//server/sharename/Files">

For Activities, a separate Directory element must be defined for each content store root.
To enable the modules for Activities, Files, Mobile, and Wikis, add the following lines to httpd.conf, adding them after the lines added in Step 7:
<Location application_context_root>
 IBMLocalRedirect On  
IBMLocalRedirectKeepHeaders X-LConn-Auth,Cache-Control,Content-Type,Content-Disposition, Last-Modified,ETag,Content-Language,Set-Cookie,Title,X-UA-Compatible
 SetEnv FILES_CONTENT or LIBRARIES_CONTENT or MOBILE_CONTENT or WIKIS_CONTENTtrue
</Location>
For example:
<Location /activities>
 IBMLocalRedirect On  
IBMLocalRedirectKeepHeaders X-LConn-Auth,Cache-Control,Content-Type,Content-Disposition, Last-Modified,ETag,Content-Language,Set-Cookie,Title,X-UA-Compatible
 SetEnv ACTIVITIES_CONTENT true </Location>

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

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

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

<Location /wikis>
 IBMLocalRedirect On  
IBMLocalRedirectKeepHeaders X-LConn-Auth,Cache-Control,Content-Type,Content-Disposition, Last-Modified,ETag,Content-Language,Set-Cookie,Title,X-UA-Compatible
 SetEnv WIKIS_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.myco.com/files is /files. This root is /files, /wikis, or /dm by default, but can be changed during post-installation steps. We can find the value in the files.href.prefix property in LotusConnections-config.xml.

For mobile, the application_context_root is the FileDiff context root; by default, this root is /connections/filediff.

The location for /connections/filediff must include the X-Content-Length header.

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

If the environment requires more headers (for example for a proxy cache), we can add them to the comma-delimited IBMLocalRedirectKeepHeaders list. This addition ensures 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 the data directory requires to be accessible. It must match the value after REDIRECT_ 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.

We can think of this setting as a lock and key mechanism: only requests that go through the Files, Library, Mobile, or Wikis applications get a key, and the applications ensure that only authorized users can unlock particular files.
Test that IHS is configured properly and securely:

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

Try to access the alias directory directly at http/https:host/alias and make sure that we are denied permission. If we can access the directory, verify the Order Deny, Allow; Deny from All; Allow from env from Step 7 are all present.

Access the application, and download a file to make sure that it functions. The module is not yet enabled.
Check out the files-config.xml, mobile-config.xml, or wikis-config.xml file using the steps in the topic Change configuration property values, and specifying the following property attributes:
<download>
<modIBMLocalRedirect enabled="true" hrefPathPrefix="/alias" />
</download>
The alias must have a forward slash in front of it.

The modeIBMLocalRedirect element is in the FileDiff section of mobile-config.xml.
For Activities, add separate <download> elements to each <store> element in oa-config.xml. Each <download> element references an Alias defined in Step 6.
For example:
<store default="true" class="com.ibm.openactivities.objectstore.filesystem.ContentStore">
      <id>filesystem</id>
      <property name="use.historic">false</property>
      <property name="root.directory">${ACTIVITIES_CONTENT_DIR}</property>
      <download>
            <modIBMLocalRedirect enabled="true" hrefPathPrefix="/activities_content" />
      </download>
</store>
(Connections Content Manager only.) Use the task Configure FileNet Collaboration Services to set values for the variables cdhc_isEnabled, cdhc_urlPath, cdhc_rootPath, and cdhc_guardHeader in the Site Preference Parameters, fncs-sitePrefs.properties. Where:

cdhc_isEnabled must be set to true.

cdhc_urlPath must be the name of the alias specified in step 6.

cdhc_rootPath must correspond to the data_directory_root used in step 7.

cdhc_guardHeader must correspond to the variable used in the SetEnv command in step 8.

For example:
cdhc_isEnabled=true
cdhc_urlPath=library_content_cache
cdhc_rootPath=/opt/IBM/Connections/data/shared/ccmcache
cdhc_guardHeader=LIBRARIES_CONTENT
You must restart FileNetEngine and FNCS.
Ensure that cached items can appear in the shared directory:

Specify RequestHeader append LIBRARIES_CONTENT true in httpd.conf where LIBRARIES_CONTENT is the name specified for the cdhc_guardHeader.

Load the appropriate module by adding the following statement:
LoadModule headers_module modules/mod_headers.so

Restart Files, Libraries, Mobile, or Wikis, depending on which applications we are configuring.

Download a file to verify the new configuration works.
Test whether IHS is downloading files:
Open httpd.conf 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_CONTENT or REDIRECT_LIBRARIES_CONTENT or REDIRECT_MOBILE_CONTENT or REDIRECT_WIKIS_CONTENT

</Directory>
For example:
<Directory "/opt/IBM/Connections/data/shared/files">
Order Deny,Allow
Deny from all #Allow from env=REDIRECT_FILES_CONTENT
</Directory>

<Directory "/opt/IBM/Connections/data/shared/ccmcache">
Order Deny,Allow
Deny from all #Allow from env=REDIRECT_LIBRARIES_CONTENT
</Directory> 

<Directory "/opt/IBM/Connections/data/shared/mobile">
Order Deny,Allow
Deny from all #Allow from env=REDIRECT_MOBILE_CONTENT
</Directory> 

<Directory "/opt/Connections/data/shared/wikis">
Order Deny,Allow
Deny from all #Allow from env=REDIRECT_WIKIS_CONTENT
</Directory>
Save the file.

Try to download a file from Files, the Mobile app, or Wikis. If the new configuration is correct, the download is denied. Test over HTTP and HTTPS protocols (if HTTPS is enabled).

Open httpd.conf and remove the # characters from the last line that was specified in Step a.
Check the standard IHS error and request logs for any problems.
Ensure that Activities is downloading files from the HTTP server:

Enable the following tracing: com.ibm.openactivities.web.coreui.actions.superclass.*=all

Download a file from Activities or click More in an Activity goal or an Entry/ToDo description.

You should see a line like the following in the trace.log file: [2/5/13 16:16:18:134 EST] 00000090 OaDownloadAct 1 sun.reflect.GeneratedMethodAccessor86 invoke OaDownloadAction setting X-IBM-Local-Redirect header to : /activities_content/122/110/69aed142-0b89-4a7a-985a-cfd99cca1292

Ensure the extended description displays when we click More and that downloaded files are not 0 bytes. If we do not see extended descriptions and if downloaded files have 0 length, then the configuration was not completed correctly.
What to do next

If we get a permission denied error when we try to download a file, IHS might not have access to the content. We can temporarily disable security on the directory, and ensure we can access it directly first, then re-enable security. We can determine whether WAS or IHS is encountering an issue by the error page displayed, and by the path. If IHS is having a problem with the module that started, the path includes /<alias>.

If we get log errors about loading the module, make sure that it is only loaded once. Also, check selected the correct binary, and that we are using a supported operating system.

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

Parent topic:
Post-installation tasks

Related:
Deployment options
Configure IHS
Define IHS
Change common configuration property values
Set up Content Download Caching
Specify a separate file download domain
Files configuration properties
Wikis configuration properties