IBM Support

Is it possible to run IBM HTTP Server (IHS) on the same computer as a Domino server?

Question/Answer


Question

Is it possible to run IBM HTTP Server (IHS) on the same computer as an IBM Domino server?

Answer


Starting with version 9.0, Domino has the option of running the IBM HTTP Server on the same computer as a Domino HTTP server; the purpose of this enhancement is to support the Transport Layer Security (TLS) protocol. A pass-through reverse proxy module named mod_domino is provided to forward HTTP requests to the Domino HTTP server. The pass-through reverse proxy module creates the context necessary to have the Domino HTTP server provide the HTTP request context expected by Domino Web applications, as if the Domino HTTP server were in direct contact with the browser client. Using the proxy module allows an IHS server to run "in front of" the Domino server.

NOTE: This IHS server module is supported only on Windows.

Installing the module

  1. Start the installation of the IBM Domino server.
  2. Under Choose the installation type that best suits your needs, select Customize Domino Server.
  3. Under Select the features for "IBM Domino" you would like to install, enable the check box IBM HTTP server (installed).
  4. Complete the installation, but do not start the server yet.


Configuring the IBM HTTP server to reside on the same computer as the Domino HTTP server

The IBM HTTP server configuration file that is used to start the IBM HTTP server is named domino.conf and is located in the Domino Program directory under the ihs\conf subdirectory.
The installation does not assume any port configuration. By default all listen ports are disabled in the domino.conf file. You must enable any listen ports you want the server to use.


1. To allow the IBM HTTP Server to accept HTTP connections, enable normal HTTP port 80, and remove the comment character (#) for the following line(s) in the domino.conf file:

    # IPv4 support:
    #Listen 0.0.0.0:80
    # Uncomment the following line for IPv6 support on Windows XP or Windows
    # 2003 or later.  Windows IPv6 networking must be configured first.
    # Listen [::]:80

    Example (section showing port 80 enabled for IPv4):

    # IPv4 support:
    Listen 0.0.0.0:80
    # Uncomment the following line for IPv6 support on Windows XP or Windows
    # 2003 or later.  Windows IPv6 networking must be configured first.
    # Listen [::]:80

2. To allow the IBM HTTP Server to accept HTTP SSL connections, enable the SSL/TLS port 443, and remove the comment character (#) for the following line(s) in the domino.conf file:

    # To enable ssl, uncomment and add/change the
    # appropriate directives

    #Listen 0.0.0.0:443
    ## IPv6 support:
    #Listen [::]:443
    #<VirtualHost *:443>
    #SSLEnable
    #SSLClientAuth optional
    #SSLProtocolDisable SSLv2
    #SSLProtocolDisable SSLv3
    #</VirtualHost>
    #KeyFile <
    domino_program_directory >/ihs/ihsserverkey.kdb
    #SSLDisable

    Example (section showing port 443 enabled for IPv4 with a SSL keyring file located on d:/keys/myserver.kdb):

    Listen 0.0.0.0:443
    ## IPv6 support:
    #Listen [::]:443
    <VirtualHost *:443>
    SSLEnable
    SSLClientAuth optional
    #SSLProtocolDisable SSLv2
    #SSLProtocolDisable SSLv3
    </VirtualHost>

    KeyFile d:/keys/myserver.kdb
    SSLDisable
    #


    Block attempts to use SSLv3 and SSLv2 by modifying the SSL section of the domino.conf file. Uncomment these lines in the virtual host section for <VirtualHost *:443>

    SSLProtocolDisable SSLv2
    SSLProtocolDisable SSLv3


    Listen 0.0.0.0:443
    ## IPv6 support:
    #Listen [::]:443
    <VirtualHost *:443>
    SSLEnable
    SSLProtocolDisable SSLv2
    SSLProtocolDisable SSLv3
    ##SSLClientAuth required
    .
    .
    # End of example SSL configuration


    Force all connections to IHS over HTTP to be redirected to HTTPS by modifying the global environment section of the domino.conf file. Uncomment the line

    LoadModule rewrite_module modules/mod_rewrite.so

    and below it add these lines:

    RewriteEngine on
    RewriteCond %{SERVER_PORT} =80
    RewriteRule ^(.*) https://% {S ERVER_NAME}%{REQUEST_URI} [R,L]

    This modification has documentation in the IHS technote "Rewriting HTTP (port 80) requests to HTTPS (port 443)" and references the httpd.conf for an IBM HTTP Server standalone installation.

    http://www-01.ibm.com/support/docview.wss?rs=177&context=SSEQTJ&uid=swg21114864

    These modifications require a Domino HTTP process restart.


3. To prepare the server to accept SSL/TLS connections, configure the SSL/TLS key database. Use the ikeyman utility provided with the IBM HTTP Server, and located in the Domino Program directory under ihs\bin, to create and configure the key database.

4. After the key database is created, make sure the KeyFile directive in the portion of the domino.conf file shown above points to the fully qualified file name of the key database.

NOTE: For an existing Domino server, the Domino key ring file cannot be used as a key database, and all necessary certificates that exist in the Domino key ring file must be re-imported from the originating Certificate Authorities into the IBM HTTP Server key database. See the following link for more information on the configuration of SSL/TLS in the IBM HTTP server:


Configuring the Domino HTTP server to start, stop, and run the IBM HTTP server

In the NOTES.INI file on the Domino server, add the following parameter:

HTTPIHSEnabled=1

This setting changes the Domino HTTP server to behave as follows:
  • The setting disables the usual ports configured in the Domino Directory (these are most often HTTP port 80 and the HTTPS port 443).
  • The Domino HTTP server connection settings are overridden with settings that maximize the re-use of connections between mod_domino/IBM HTTP Server and the Domino HTTP server.
  • By default, the Domino HTTP server listens on port 9288 for loop back connections from mod_domino/IBM HTTP Server.
  • The Domino HTTP server only accepts connections that originate from the same computer. By default, mod_domino uses the local loop back address of 127.0.0.1 to connect to the Domino HTTP server. Both server processes must run on the same computer.


Environment variables for startup

Before the IBM HTTP Server is started by the Domino HTTP server, the following environment variables are set automatically in this configuration; you should not need to modify any of them. These environment variables are specified in the ihs\conf\domino.conf file and are used to specify the values of IBM HTTP Server directives in the domino.conf file.

DOMINO_IHS_ROOT Set to the root directory where the IBM HTTP Server is installed. This setting cannot be changed.
DOMINO_SERVER_NAME Set to the fully qualified TCP name of the machine the Domino server is installed on. This setting cannot be changed.
DOMINO_DOCUMENT_ROOT Set to the document root where Domino HTML files are located.
This setting cannot be changed.
DOMINO_DOCUMENT_DIRECTORY Set to the base directory where Domino file system files may reside. This setting cannot be changed.
DOMINO_PORT Set to the port number that the Domino Web Server listens on for connections from mod_domino. The default port is 9288.

This setting can be changed by setting the following notes.ini value:

HTTPConnectorPort=<port number>
DOMINO_MAX_REQUESTLINE Set to the maximum request line length, this setting is derived from "Maximum URL length" field on the HTTP tab in the Domino Directory. A fix number of bytes is added to account for the HTTP method and HTTP protocol strings.
DOMINO_TECH_SUPPORT Set to the Domino Technical Support directory. This setting cannot be changed.
DOMINO_RESPONSE_TIMEOUT Set the amount of time in seconds that mod_domino plugin will wait for the initial response from the Domino HTTP server. The default is 300 seconds for a non-Notes Traveler server.

For a Notes Traveler server this setting is set to the Heartbeat Algorithm Maximum Interval: field on the IBM Notes Traveler tab in the Domino Directory.

This setting can be changed by the following notes.ini:

HTTPIHSModDominoResponseTimeout=<time out value in seconds>
DOMINO_THREADS This value is set to the number of Domino threads multiplied by three for the optimal threads to connections between mod_domino and the Domino HTTP server. This is the default for non-Notes Traveler servers.

For Notes Traveler servers this number is set to the same number of threads as the Domino HTTP server.

This setting can be changed by the following notes.ini; however, the general recommendation is to leave it alone unless there is a use case that requires a change.

HTTPIHSThreads=<number of IBM HTTP Server threads>


Serviceability settings

You can use a NOTES.INI setting to display environment variables that are used in the domino.conf configuration file.

Add the following parameter to the NOTES.INI file:

HTTPIHSDebugStartup=1

Example output:

[06F4:0002-13C4] Set IHS config environment var DOMINO_IHS_ROOT=C:/domino/ihs.
[06F4:0002-13C4] Set IHS config environment var DOMINO_SERVER_NAME=envy.swg.usma.ibm.com.
[06F4:0002-13C4] Set IHS config environment var DOMINO_DOCUMENT_ROOT=c:/domino/data/domino/html.
[06F4:0002-13C4] Set IHS config environment var DOMINO_DOCUMENT_DIRECTORY=c:/domino/data/domino.
[06F4:0002-13C4] Set IHS config environment var DOMINO_PORT=9288.
[06F4:0002-13C4] Set IHS config environment var DOMINO_MAX_REQUESTLINE=4108.
[06F4:0002-13C4] Set IHS config environment var DOMINO_TECH_SUPPORT=c:/domino/data/IBM_TECHNICAL_SUPPORT.
[06F4:0002-13C4] Set IHS config environment var DOMINO_RESPONSE_TIMEOUT=300.
[06F4:0002-13C4] Set IHS config environment var DOMINO_THREADS=120.

Troubleshooting the IBM HTTP Server

Changing the Windows Registry

On Windows systems, it is possible to hit a TCP port exhaustion condition. This can be caused by Domino Web applications that do not send a content-length or a chunked encoded header in the HTTP response. This forces the Domino HTTP server to close the loop back connection that is used by the mod_domino plugin to communicate with the Domino HTTP server. Every attempt is made to re-use the loop back connections between the mod_domino plugin and the Domino HTTP server. However, to prevent this condition from occurring, it may be necessary to add/change the following Windows TCP Registry settings.

The settings are located under the following registry key.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

Value Name:  TcpTimedWaitDelay
Value Data:  30 - Should set the value to the minimum value of 30

Value Name:   MaxUserPort
Value Data:     65534 -- Should be set to the maximum value of 65534

Modifying local firewall software

Lab testing has found that some firewall software running on the server may prevent and/or limit the number of loop back connections that can be made between the mod_domino plugin and the Domino HTTP server. It may be necessary to remove or configure local firewall software not to interfere with the operation of this plugin.

Related information

Open Mic: Implementing TLS support with Domino & IHS

Document information

More support for: IBM Domino

Component: Web Server

Software version: 9.0

Operating system(s): Windows

Software edition: All Editions

Reference #: 1612316

Modified date: 05 September 2018


Translate this page: