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.
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.
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.
Configuring file
downloading for Activities, Files, Libraries, Mobile, and Wikis applications
is not supported on IBM i.
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/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
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\configmanager\profiles 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.
- From the Deployment Manager Integrated Solutions Console, restart
the FileNetEngine and fncs applications.
- 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/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.