Steps for updating the IBM HTTP Server configuration files

PKI Services uses two modes of SSL, and these two modes require running two instances of the IBM HTTP Server. Although the two instances share a single server certificate and private key, they use two different configuration files.

The first configuration file is your existing configuration file (created earlier, see Steps for setting up the IBM HTTP Server for PKI Services). It specifies port 80 for normal HTTP traffic and port 443 for the SSL traffic port.
The second configuration file, /etc/httpd1443.conf, specifies SSL traffic only on port 1443, with client authentication. (If this file does not exist, you create it by copying the first file.)

The following table summarizes the configuration and usage of each Web server:

Table 1. Summary of configuration and usage of each Web server instance
Server instance	Protocol	SSL	Server authentication	Client authentication	Port number
First instance	HTTP	No	No	No	80
First instance	HTTPS	Yes	Yes	No	443
Second instance	HTTPS	Yes	Yes	Yes	1443

Before you begin

Important: You need to perform these steps only if you are configuring PKI Services for the first time.
You need to know the file system install directory (the file system directory where the MVS™ programmer installed PKI Services), called 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 need to know the following LDAP information. Record the information in the rightmost row of Table 2. Note that the default name of the LDAP server configuration file is ds.conf for the IBM Tivoli Directory Server for z/OS LDAP server.

Table 2. LDAP information you need for tailoring IBM HTTP Server configuration
LDAP information	Explanation	Value
Administrator's distinguished name	This is 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 the following: `adminDN "cn=Admin"`
Administrator password	This is the password to use for LDAP binding. The LDAP programmer can set this 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	This is the IP address on which the LDAP server is listening, for example, for `ldap.widgets.com`. See Table 1 for a definition of fully qualified domain name.
LDAP port	This is the port for LDAP, for example, `389` in `ldap.widgets.com:389`

Procedure

Perform the following steps to update the IBM HTTP Server configuration files (if you are configuring PKI Services for the first time):

If the second configuration file does not yet exist, create it by copying the first configuration file with the following command:
```
cp -p /etc/httpd.conf /etc/httpd1443.conf
```
_______________________________________________________________
Copy the first set of sample IBM HTTP Server configuration directives (from the PKI Services samples directory, /install-dir/samples/httpd.conf file) into the default configuration file, /etc/httpd.conf.
Note: The install-dir, your file system installation directory, by default is /usr/lpp/pkiserv. The MVS programmer determines whether to change this default. (See Table 1.)
1. Copy the keyfile, sslmode, sslport, and normalmode directives as is, replacing any existing values.
2. 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 SSLring SAF
```
3. Optionally, copy the userId directive as is, replacing any existing value.
  Guideline: Copy the userId directive (as shown in the following example) into your file as is. However, if you already have a value in your file for this, you are not required to change it.
```
UserId %%CLIENT%%
```
4. Copy the protection and protect directives after any protection and protect directives you already have. Do not change the order in which these directives appear.
5. Copy the redirect directives after any redirect directives you already have. Do not change the order in which these directives appear. Make sure that the redirect directives are placed before the pass and exec directives.
6. Copy the pass and exec directives before any pass and exec directives you already have.
7. Add the addtype directives to your list of addtypes if they don't already exist.
8. 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.)
9. Change all instances of application-root to your file system installation directory, which is usr/lpp/pkiserv by default.
  Note: Your file system installation directory by default is /usr/lpp/pkiserv. The MVS programmer determines whether to change this default. (See Table 1.)
_______________________________________________________________
Copy the second set of IBM HTTP Server configuration directives (from the PKI Services samples directory, /install-dir/samples/httpd2.conf) into the /etc/httpd1443.conf file.
Note: The install-dir, your file system installation directory, by default is /usr/lpp/pkiserv. The MVS programmer determines whether to change this default. (See Table 1.)
1. If you created this file by copying the first httpd.conf file, delete all existing protection, protect, redirect, pass, exec, and FastCGI directives.
2. Copy the userId, keyfile, sslmode, sslport, sslclientauth, normalmode, and SSLX500CARoots directives as is, replacing any existing values.
3. 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 SSLring SAF
```
4. Add the following directives after the SSLX500CARoots directive:
  - SSLX500Host
  - SSLX500Port
  - SSLX500UserID
  - SSLX500Password
  Replace the <> placeholders with the actual values from Table 2.
5. Copy the protection and protect directives after any protection and protect directives you already have. Do not change the order in which these directives appear.
6. Copy the redirect directives after any redirect directives you already have. Do not change the order in which these directives appear.
7. Copy the exec directives before any pass and exec directives you already have.
8. 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.)
9. Change all instances of application-root to your file system installation directory.
  Note: Your file system installation directory by default is /usr/lpp/pkiserv. The MVS programmer determines whether to change this default. (See Table 1.)
10. If you created httpd1443.conf by copying httpd.conf, optionally change the directories in httpd1443.conf for the report, log, and pid files.
  Guideline: Perform this step to ensure the two servers are not using the same files at the same time.
  1. Create a new directory for the httpd1443 files by using the following command:
```
mkdir /etc/internet/logs1443
```
  2. Assign ownership to WEBSRV with the following command:
```
chown websrv /etc/internet/logs1443
```
  3. Edit the *Log directives in the new httpd1443.conf file to provide unique pathnames.
    For example, if the first httpd.conf file has:
```
AccessLog     /etc/internet/logs/httpd-log 
AgentLog      /etc/internet/logs/agent-log 
RefererLog    /etc/internet/logs/referer-log 
ErrorLog      /etc/internet/logs/httpd-errors 
CgiErrorLog   /etc/internet/logs/cgi-errors  
```
    change the httpd1443.conf *Logs to:
```
AccessLog     /etc/internet/logs1443/httpd-log 
AgentLog      /etc/internet/logs1443/agent-log 
RefererLog    /etc/internet/logs1443/referer-log 
ErrorLog      /etc/internet/logs1443/httpd-errors 
CgiErrorLog   /etc/internet/logs1443/cgi-errors
```
_______________________________________________________________
If you plan to use an OCSP responder, SCEP, or the certificate management protocol (CMP) CGI programs, add /usr/lpp/pkiserv/lib to the LIBPATH environment variable in the file httpd.envvars.
_______________________________________________________________