Steps for updating the IBM HTTP Server V7.0 configuration files

PKI Services ships four sample HTTP Server configuration files

The main configuration file (httpd.conf)
Three virtual host files (vhostportnumber.conf)

These files are used by the IP-based virtual hosting feature of the HTTP Server. IP-based virtual hosting is a method to apply different directives that are based on the IP address and port on which a request is received. PKI Services provides sample virtual host files for non-SSL requests, SSL requests, and SSL requests with client authentication on different ports.

Table 1 summarizes the virtual host files that are used for normal HTTP traffic and SSL traffic with specific ports.

Table 1. Virtual host files
Virtual host configuration file	Protocol	SSL	Server authentication	Client authentication	Port number
vhost80.conf	HTTP	No	No	No	80
vhost443.conf	HTTPS	Yes	Yes	No	443
vhost1443.conf	HTTPS	Yes	Yes	Yes	1443

Before you begin

You must perform these steps only if you are configuring IBM® HTTP Server 7.0 for PKI Services for the first time. If you are using IBM HTTP Server 7.0 and you are now updating the configuration for use with PKI Services, some of the following steps are not required.
This information assumes that you used the installer program (bin/install_ihs) to install IBM HTTP Server 7.0. You must know the installation directory for the server instance, which is referred to as ihs-install-dir in the sample commands. (This directory must be different from the product directory, usually /usr/lpp/IHSA/V7R0/server).
You must know the file system installation directory (the file system directory where the MVS™ programmer installed PKI Services), called pki-install-dir in the commands that follow. The default is /usr/lpp/pkiserv/. The MVS programmer was asked to record any changes to the defaults; see Table 1.

You must know the following LDAP information. Record the information in the rightmost column of Table 2.

Note: The default name of the LDAP server configuration file is ds.conf for the LDAP server that is provided by IBM Tivoli® Directory Server.

Table 2. LDAP information you need for tailoring IBM HTTP Server 7.0 configuration
LDAP information	Explanation	Value
Administrator's distinguished name	The distinguished name to use for LDAP binding. (For a definition of distinguished name, see Table 1.) The LDAP administrator defines the administrator's distinguished name with the adminDN keyword in the LDAP server configuration file. For example, the value is "`cn=Admin`" in `adminDN "cn=Admin"`
Administrator password	The password to use for LDAP binding. The LDAP programmer can set this password in several ways; for example: By specifying the password as a TDBM entry by using the `userPassword` attribute in the ldif2tdbm load utility By using the adminPW keyword in the LDAP server configuration file (not suggested)
LDAP fully qualified domain name	The IP address on which the LDAP server is listening, for example, `ldap.widgets.com`. See Table 1 for a definition of fully qualified domain name.
LDAP port	The port for LDAP, for example, `389` in `ldap.widgets.com:389`

Procedure

Perform the following steps to update the IBM HTTP Server V7.0 configuration files:

Copy the IBM HTTP Server directives from the PKI Services samples configuration file, pki-install-dir/samples/ihs7/httpd.conf to the HTTP server configuration file, ihs-install-dir/conf/httpd.conf, and make the following updates.
Note: The file pki-install-dir/samples/ihs7/httpd.conf is not a complete httpd.conf file. It contains only the directives that might not be present in your httpd.conf file and that might be unique to the PKI Services CGI scripts and programs.
1. Use the Load Module directive to add the required modules to the list of modules, if they do not exist:
  - rewrite_module modules/mod_rewrite.so
  - authnz_saf_module modules/mod_authnz_saf.so
  - authz_default_module modules/mod_authz_default.so
  - ibm_ssl_module modules/mod_ibm_ssl.so
  - alias_module modules/mod_alias.so
2. Add the addtype directives to your list of addtypes if they do not exist:
```
AddType application/x-x509-user-cert .cer
AddType application/x-x509-ca-cert   .der
AddType application/octet-stream     .msi
AddType application/pkix-crl         .crl
```
3. Copy the Keyfile and the Include directives as is, replacing any existing values.
4. If your organization customized the value of web_ring (see Table 1), change SSLring in the Keyfile directive in the following line to the customized value:
```
Keyfile /saf SSLring
```
If the virtual host files (vhost80.conf, vhost443.conf, vhost1443.conf) do not exist, create them by copying them from pki-install-dir/samples/ihs7 to ihs-install-dir/conf/vhost80.conf, ihs-install-dir/conf/vhost443.conf, and ihs-install-dir/conf/vhost1443.conf. For example, assuming the default pki-install-dir and an ihs-install-dir of /etc/websrv1, the following command copies all three vhost files to the /etc/websrv1/conf directory:
```
cp /usr/lpp/pkiserv/samples/ihs7/vhost*.conf /etc/websrv1/conf
```
Make the following updates to each of the three virtual host files:
1. Change all instances of server-domain-name to your web server's fully qualified domain name, for example, www.ibm.com. (For information about your web server's fully qualified domain name, see Table 1.)
2. Change all instances of application-root to the value of pki-install-dir, which is usr/lpp/pkiserv by default.
3. If necessary, change the environment variable _PKISERV_CONFIG_PATH to identify the runtime directory of your CA domain (See Table 1.)
4. (Optional) If you intend to have a dedicated set of administrators for each CA domain, add an environment variable that specifies the runtime directory for each administrative domain. (See Table 1.)
  Example:
```
_PKISERV_CONFIG_PATH_PKISERV=/etc/pkiserv
```
Note: In the vhost80.conf file, which defines directives for non-SSL requests, a Listen directive is not specified. It is assumed that the Listen directive is defined in the main httpd.conf file that tells the server to accept incoming requests on the specified port. If you do not have a Listen directive in the httpd.conf file, add the Listen 80 directive on the line before the VirtualHost *:80 directive in the vhost80.conf file.
Perform the following step to update the vhost443.conf virtual host configuration file.
1. If your organization customized the value of web_ring (see Table 1), change SSLring in the Keyfile directive in the following line to the customized value:
```
Keyfile /saf SSLring
```
Perform the following steps to update the vhost1443.conf virtual host configuration file.
1. If your organization customized the value of web_ring (see Table 1), change SSLring in the Keyfile directive in the following line to the customized value:
```
Keyfile /saf SSLring
```
2. Add the following directives after the SSLClientAuth directive:
  - SSLCRLHostName
  - SSLCRLPort
  - SSLCRLUserID
  - SSLStashfile
  Note: SSLStashfile is the fully qualified path to the file that contains the password for the user name on the LDAP server. This directive is not required for an anonymous bind. Use it when you specify a user ID. Use the sslstash command, which is located in the bin directory of IBM HTTP Server, to create your CRL password stash file. Specify the password that you use to log in to your LDAP server as the password on the sslstash command. The format of the sslstash command is:
```
sslstash [-c] file function password
```
  where:
  -c
  
  Creates a new stash file. If not specified, an existing file is updated.
  
  file
  
  Is the fully qualified name of the file to create or update.
  
  function
  
  Indicates the function for which the password is to be used. Valid values include crl and crypto.
  
  password
  
  Is the password to stash.