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 serve file downloads.
Before you begin
Activities, Files, Libraries, Mobile, and Wikis data must be stored on a shared file system, as
described in the Deployment options topic. The Connections Content Manager uses an
optional file cache on the file system for serving files through the HTTP server.
All IBM HTTP Servers in the deployment must have READ
access to the files, and all WebSphere Application
Servers must have WRITE access. This task is required after installing Connections whether you
configure an IBM HTTP Server as part of the install or not.
Note: For shared and remote network file
system requirements, review the footnotes for each supported operating system in the detailed
system requirements.
If you choose not to configure IBM HTTP Server to download
files, you must configure WebSphere Application Server
to transfer data synchronously instead of asynchronously. This configuration avoids errors that are
related to using too much memory. For more information, see the Excessive native
memory use in IBM
WebSphere Application Server technote.
About this task
In a default deployment with IBM HTTP Server, file download
requests are passed from IBM HTTP Server to WebSphere Application Server. WebSphere Application Server accesses the files in a data directory on the file system and
returns them to IBM HTTP Server, which passes them to the
browser.
When large numbers of users are downloading files, this deployment is inefficient, partly because
WebSphere Application Server has a limited thread pool
that is tuned for short-lived transactions. In addition, WebSphere Application Server is optimized for Java
Platform, Enterprise Edition 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.
Configuring IBM HTTP Server to download files makes
downloading much more efficient, because IBM HTTP Server is
designed specifically for serving files. This configuration leaves WebSphere Application Server to carry out tasks such as security checking
and cache validation.
To configure this environment, install an add-on module that directs IBM HTTP Server to download files. When the module is installed, download
requests are passed from IBM HTTP Server to the WebSphere Application Server. But instead of responding by
downloading the file, WebSphere Application Server adds
a special header to its response. The add-on module recognizes the header and directs IBM HTTP Server to download the file.
This configuration requires making the Files, Mobile, and Wikis data directories available to IBM HTTP Server by using an alias. (Optionally, you can also make
available the content cache directory from Connections Content Manager.) This configuration creates
a security concern, so you must configure the access control at the IBM HTTP Server level. After you configure security, access to the data through IBM HTTP Server is denied unless a specific variable is set.
Requests to the applications on WebSphere Application
Server are then configured to set the variable. In other words, only requests that pass through WebSphere Application Server can access the data directory,
with WebSphere Application Server acting as the
authorizer.
If you use the add-on module, you must use an IBM HTTP
Server address for the IBM Connections inter-service URL. For
information on setting an inter-service URL, see the Troubleshooting inter-server
communication topic.
To configure IBM HTTP Server to download files, complete
the following steps:
- Install the IBM Connections applications you plan to
configure for file downloads if you have not already done so: Activities, Files, Libraries, Mobile,
or Wikis.
- On the server where you installed IBM Connections (on the
deployment manager), navigate to the connections_root/plugins/ihs/mod_ibm_local_redirect/platform
directory to find the module file (mod_ibm_local_redirect.so). On supported
operating systems, search the following directories:
- /aix_ppc32-ap22
- /aix_ppc64-ap22
- /linux390-ap22
- /linux_ia32-ap22
- /linux_ppc64-ap22
- /linuxs390_x64-ap22
- /linux_amd64-ap22
- /win_ia32-ap22
For example, on Linux systems, go to the following
directory:
/IBM/Connections/plugins/ihs/mod_ibm_local_redirect/linux_ia32-ap22/mod_ibm_local_redirect.so
Notes: - These directories are valid whether you installed IBM HTTP
Server from the 32-bit or 64-bit supplemental package, because the IBM HTTP Server process is 32-bits in both cases and requires 32-bit modules.
- Copy the module to the appropriate directory on the system that hosts IBM HTTP Server. By default, modules are stored in the ibm_http_server_root/modules directory.
- Open the httpd.conf file (in the ibm_http_server_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
Note: 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 you can edit.
- Grant access to the data directory root:
- AIX or Linux:
Give the IBM HTTP Server user READ and EXECUTE access to the
data directory root.
- Microsoft
Windows: Give the IBM
HTTP Server user READ access to the data directory root. For optimal security, do not grant WRITE
access.
Notes: - You can find the data_directory_root path by searching for "storage
rootDirectory" in the files-config.xml or
wikis-config.xml file. This attribute contains either the path itself, or a WebSphere Application Server variable whose value is the
path. For information about opening the files-config.xml or
wikis-config.xml files, see the Changing 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 WebSphere Application Server console to find the
path. For more information about WebSphere variables,
see the Changing WebSphere Application Server
environment variables topic.
- If the Connections Mobile service is installed, you must also give IBM HTTP Server access to the FileDiff StoragePath. You can find the FileDiff
StoragePath attribute in the FileDiff section of the mobile-config.xml file.
For information about editing the mobile-config.xml file, see the
Changing 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 WebSphere Application Server console to
find the path. For more information about WebSphere
variables, see the Changing WebSphere Application
Server environment variables topic.
- For IBM Connections Content Manager, the data directory is
a shared cache directory available to both IBM HTTP Server 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 the oa-config.xml file. 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 /ccmcache directory in the shared_data_directory_root.
Windows:
drive:\Program Files\IBM\Connections\data\shared\ccmcache
AIX or Linux:
/opt/IBM/Connections/data/shared/ccmcache
- 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 the httpd.conf file.
- 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/IBM/Connections/data/shared/files/upload
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/upload
Note: - Do not use the application context root (/connections/filediff,
/dm, /files, /mobile, or
/wikis) as part of the alias. You 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.example.com/files is
/files. 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.
- Include quotation marks around the file path on Windows
systems, and always use forward slashes, for example: "C:/Program
Files/IBM/Connections/Data/Files"
- The example assumes that the HTTP server is on the same system as IBM Connections. If the HTTP server is on a different system, specify the data
directory by 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".
- To make the alias more secure, add the following lines to the httpd.conf file,
adding them after the lines that you added in Step 7:
<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>
Notes: - 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 that you want, provided it is not already in the IBM HTTP Server environment.
- The example assumes that IBM HTTP Server is on the same
system as IBM Connections. If IBM HTTP Server is on a different system, specify the data directory by using the network
share path appropriate to your 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 the
httpd.conf file, adding them after the lines that you added in Step 8:
<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>
Notes: - 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.example.com/files is /files. This root is
/files, /wikis, or /dm 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.
- 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.
- Specifying 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
that the IBM HTTP Server would not know about.
- If your environment requires more headers (for example for a proxy cache), you can add them to
the comma-delimited IBMLocalRedirectKeepHeaders list. This addition ensures 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 8. For example, if you set REDIRECT_FILES_CONTENT in Step 7, this value
must be SetEnv FILES_CONTENT true.
- You 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 IBM HTTP Server is configured properly and
securely:
- Restart IBM HTTP Server. Make sure that it loads properly
and there are no log errors about loading modules or configuration. If there are problems, make sure
that 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 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 8 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,
oa-config.xml, or wikis-config.xml file by using the steps in the
topic Editing configuration files, and specifying the following property
attributes:
<download>
<modIBMLocalRedirect enabled="true" hrefPathPrefix="/alias" />
</download>
Notes: - The alias must have a forward slash in front of it.
- The modBMLocalRedirect element is in the FileDiff section of the
mobile-config.xml file.
- For Activities, you must add separate <download> elements to each
<store> element in oa-config.xml. Each
<download> element references an Alias defined in Step 7.
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) Edit the FileNet site preferences file to add properties
that match your environment.
- In a text editor, open the fncs-sitePrefs.properties file, stored in the
FNCS_HOME/configure/explodedformat/fncs/WEB-INF/classes/
directory.
- Set values for the following properties in the Site Preference Parameters to match your
environment.
- cdhc_isEnabled must be set to true.
- cdhc_urlPath must be the name of the alias that is specified in Step 7.
- cdhc_rootPath must correspond to the
shared_data_directory_root used in Step 6.
- cdhc_guardHeader must correspond to the variable used in the SetEnv command
in Step 9.
For example, on Windows:
cdhc_isEnabled=true
cdhc_urlPath=/library_content_cache
cdhc_rootPath="C:/Program Files/IBM/Connections/data/shared/ccmcache"
cdhc_guardHeader=LIBRARIES_CONTENT
- Close and save the file.
- Rebuild and redeploy the navigator application. For more information, see Reconfiguring FileNet
Collaboration Services 2.0.3 and later.
- Ensure that cached items can appear in the shared directory:
- Specify RequestHeader append LIBRARIES_CONTENT true in the
httpd.conf file where LIBRARIES_CONTENT is the name that
you specified for the cdhc_guardHeader.
- Load the appropriate module by adding the following statement:
LoadModule headers_module modules/mod_headers.so
- Restart Activities, Files, Libraries, Mobile, or Wikis, depending on which applications you are
configuring.
- Download a file to make sure that the new configuration works.
- Test whether IBM HTTP Server is downloading files:
- 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_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/IBM/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, your download is denied. Test over HTTP and HTTPS protocols (if HTTPS is enabled).
- Open the httpd.conf file and remove the # characters from the last line that
was specified in Step a.
Check the standard IBM HTTP Server 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 that the extended description displays when you click More and
that downloaded files are not 0 bytes. If you do not see extended descriptions and if downloaded files have 0 length, then the
configuration was not completed correctly.