Domino for S/390 and Web Server Integration
Roland Trauner, Tony Llopis, Brian Milkes, DJ Sher
International Technical Support Organization
www.redbooks.ibm.com
SG24-5437-00
SG24-5437-00
International Technical Support Organization
Domino for S/390 and Web Server Integration
May 2000
Take Note!
Before using this information and the product it supports, be sure to read the general information in
Appendix E, “Special notices” on page 179.
First Edition (May 2000)
This edition applies to Domino for IBM HTTP Server V1, part of Lotus Domino for OS/390 V5.0.1 for use
with the IBM HTTP Server 5.1 in OS/390 R7
This document created or updated on 09.05.2000.
Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. HYJ Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2000. All rights reserved.
Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is
subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix
Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
The team that wrote this Redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Chapter 1. Domino for IBM HTTP Server introduction . . . . . .
1.1 Reasons to use the Domino for IBM HTTP Server connector
1.2 Reasons not to use the Domino for IBM HTTP Server . . . . .
1.3 Use both Web interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.1
.1
.2
.2
Chapter 2. Configuring the Domino for IBM HTTP Server . . . . . . . . . . . 5
2.1 Configuration parameters values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Updating the Domino server configuration . . . . . . . . . . . . . . . . . . . . . . 7
2.2.1 Verifying the ServerKeyFilename setting . . . . . . . . . . . . . . . . . . . 7
2.2.2 Enforcing unique name resolution. . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.3 Allowing HTTP server access to selected Domino files . . . . . . . . . 7
2.2.4 Setting program-controlled attribute for Domino binaries . . . . . . . 8
2.2.5 Adding a Domino user ID to the HTTP server group . . . . . . . . . . . 9
2.3 Updating the IBM HTTP Server configuration . . . . . . . . . . . . . . . . . . . 10
2.3.1 Updating the IBM HTTP Server permissions . . . . . . . . . . . . . . . . 10
2.3.2 Updating the IBM HTTP Server environment variables . . . . . . . . 10
2.3.3 Activating the connector plug-in (Standard Domino authentication)
11
Chapter 3. Domino server installation . . . . . . . . . . . . . . . . .
3.1 Required hardware and software . . . . . . . . . . . . . . . . . . . .
3.1.1 DASD space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Preparing the OS/390 operating environment . . . . . . . . . . .
3.2.1 Authorizing a user who will install the Domino server .
3.2.2 Authorizing the Domino server . . . . . . . . . . . . . . . . . .
3.3 Preparing to install the Domino server code . . . . . . . . . . . .
3.3.1 Allocate the OS/390 data sets . . . . . . . . . . . . . . . . . .
3.3.2 Transferring the files using FTP . . . . . . . . . . . . . . . . .
3.3.3 Allocating HFS data sets (ALOCPROD) . . . . . . . . . . .
3.3.4 Transferring the Domino server TAR file . . . . . . . . . . .
3.3.5 Integrating the MOUNT statements from MDFYBPXP.
3.4 Running the install program . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 Provide Domino installation parameters . . . . . . . . . . .
© Copyright IBM Corp. 2000
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 15
. 16
. 17
. 18
. 18
. 18
. 19
. 19
. 20
. 20
. 21
. 21
. 22
. 22
iii
iv
3.5 Verifying path statements . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Configuring a new Domino server. . . . . . . . . . . . . . . . . . . . .
3.6.1 Understanding a “First Server in Domain” configuration
3.6.2 Starting the HTTP task in server configuration mode . .
3.6.3 Using the browser to configure a first server in domain.
3.7 Preparing a dynamic LPA . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.1 Starting the server . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 24
. 24
. 24
. 26
. 26
. 33
. 34
Chapter 4. Basic IBM HTTP Server installation .
4.1 Defining the Web server directory structure
4.2 Copying the Web server configuration files. . . .
4.3 Preparing the Web server configuration files . .
4.4 Defining the security environment . . . . . . . . . .
4.5 Defining the started procedure . . . . . . . . . . . . .
4.6 Authorizing the started procedure to RACF . . .
4.7 Creating a homepage . . . . . . . . . . . . . . . . . . . .
4.8 Starting the Web server . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 35
. 36
. 37
. 37
. 41
. 43
. 44
. 44
. 44
Chapter 5. Operating the Domino for IBM HTTP Server . . . . . . . .
5.1 Starting Domino for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 User ID considerations for starting the Domino server . . . .
5.1.2 Starting the server with Telnet . . . . . . . . . . . . . . . . . . . . . .
5.1.3 DOMCON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Stopping Domino for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 Stopping Domino from the telnet or rlogin session . . . . . . .
5.2.2 Stopping Domino with DOMCON . . . . . . . . . . . . . . . . . . . .
5.3 Operating the Domino server . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 Operating the server from Telnet . . . . . . . . . . . . . . . . . . . .
5.3.2 Domino administration client. . . . . . . . . . . . . . . . . . . . . . . .
5.3.3 Web administrator client . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.4 Operating the server with DOMCON . . . . . . . . . . . . . . . . . .
5.3.5 Recommendations for Domino operation . . . . . . . . . . . . . .
5.4 Monitoring the status of the Domino server . . . . . . . . . . . . . . . .
5.4.1 Issuing server commands from a telnet/rlogin session . . . .
5.4.2 Issuing server commands with DOMCON . . . . . . . . . . . . . .
5.4.3 Valuable OS/390 console commands . . . . . . . . . . . . . . . . .
5.4.4 UNIX System Services environment . . . . . . . . . . . . . . . . . .
5.5 Coordinating server start/stop sequence for the Web connector .
5.5.1 Coordinating a start/stop sequence with DOMCON . . . . . .
5.6 Dealing with abnormal terminations . . . . . . . . . . . . . . . . . . . . . .
5.6.1 Attempt to force a shut down of the server . . . . . . . . . . . . .
5.6.2 Forced cleanup with DOMINK. . . . . . . . . . . . . . . . . . . . . . .
5.6.3 Forced cleanup with nsd.sh . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 45
. 45
. 46
. 47
. 48
. 52
. 52
. 52
. 54
. 55
. 55
. 55
. 55
. 56
. 56
. 56
. 56
. 57
. 57
. 57
. 58
. 58
. 59
. 59
. 59
Domino for S/390 and Web Server Integration
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5.6.4 Explicit kill of Domino processes. . . . . . . . . . . . . . . . . .
5.6.5 Explicit release of Domino resources . . . . . . . . . . . . . .
5.7 Starting the IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . .
5.7.1 Stopping the IBM HTTP Server. . . . . . . . . . . . . . . . . . .
5.7.2 Controlling the IBM HTTP Server . . . . . . . . . . . . . . . . .
5.7.3 Monitoring the IBM HTTP Server . . . . . . . . . . . . . . . . .
5.7.4 Accessing IBM HTTP Server administration . . . . . . . . .
5.7.5 Functions of the configuration and administration forms
5.7.6 Using the Web Server Administration interface . . . . . . .
5.7.7 Mapping Web Server Administration functions . . . . . . .
5.7.8 Administration security considerations . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 60
. 61
. 63
. 63
. 64
. 65
. 65
. 67
. 68
. 75
. 76
Chapter 6. OS/390 authentication support for Domino . . . . . . . . .
6.1 Web access authentication overview . . . . . . . . . . . . . . . . . . . . . .
6.1.1 HTTP basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2 SSL client certificate authentication . . . . . . . . . . . . . . . . . . .
6.1.3 Domino session authentication option . . . . . . . . . . . . . . . . .
6.1.4 Authentication summary . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Overview of authentication with the Domino for IBM HTTP Server
6.2.1 Using Domino authentication . . . . . . . . . . . . . . . . . . . . . . . .
6.2.2 Using OS/390 authentication . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Authentication processing details . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.1 Standard Domino authentication . . . . . . . . . . . . . . . . . . . . . .
6.3.2 OS/390 authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Enabling OS/390 RACF-based authentication . . . . . . . . . . . . . . .
6.5 Practical considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 79
. 79
. 79
. 80
. 80
. 80
. 81
. 81
. 82
. 84
. 84
. 88
. 95
. 95
Chapter 7. Setting up a secure Web server . . . . . . . . . . . . .
7.1 Decision on server certificates . . . . . . . . . . . . . . . . . . . . . .
7.2 Creating a server certificate using IKEYMAN . . . . . . . . . . .
7.2.1 Accessing the IKEYMAN utility . . . . . . . . . . . . . . . . . .
7.2.2 Generating and installing a self-signed certificate . . . .
7.3 Creating the server certificate using the Domino CA. . . . . .
7.3.1 Creating and submitting the server certificate request
7.3.2 Signing the certificate with the Domino CA . . . . . . . . .
7.3.3 Retrieving and receiving the signed certificate . . . . . .
7.4 Configuring the Web server for SSL . . . . . . . . . . . . . . . . . .
7.4.1 SSL troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 8. Setting up client certificates . . . . . . . . . . . . . . . . . .
8.1 Setting up the Domino Certificate Authority . . . . . . . . . . . . . .
8.1.1 Creating the Domino Certificate Authority application . . .
8.1.2 Creating the Certificate Authority key ring and certificate
8.1.3 Configuring the Domino Certificate Authority profile . . . .
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . 97
. . 97
. . 98
. . 98
. . 98
. 102
. 103
. 105
. 106
. 108
. 109
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 111
. 111
. 112
. 112
. 114
.
.
.
.
.
v
8.1.4 Setting up SSL on the Domino CA server . . . . . . . . . . . . . . .
8.2 Creating client certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.1 Creating a Person entry in Domino directory. . . . . . . . . . . . .
8.2.2 Requesting the client certificate . . . . . . . . . . . . . . . . . . . . . .
8.2.3 Signing the certificate and adding it to the Domino directory.
8.2.4 Merging the signed client certificate . . . . . . . . . . . . . . . . . . .
8.2.5 Accepting the Domino CA in the client’s browser . . . . . . . . .
8.3 Adding the Domino CA trusted root to the HTTP Server . . . . . . . .
8.4 Setting up the Domino Server to accept electronic certificates . . .
8.5 Setting up the IBM HTTP Server to accept electronic certificates .
vi
.
.
.
.
.
.
.
.
.
.
. 114
. 117
. 117
. 118
. 120
. 121
. 122
. 123
. 125
. 126
Chapter 9. Configuration scenarios . . . . . . . . . . . . . . . . . . . . . . . . .
9.1 Configuration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.1 TCP/IP addresses/ports when running multiple servers . . . . .
9.1.2 Same IP address on both servers . . . . . . . . . . . . . . . . . . . . . .
9.1.3 Supporting HTTP on both servers. . . . . . . . . . . . . . . . . . . . . .
9.1.4 Domain name server support . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.5 Client authentication options. . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.6 Server start/stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.7 Scalable Web server considerations . . . . . . . . . . . . . . . . . . . .
9.1.8 Internet cluster manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.9 One connector to one Domino server . . . . . . . . . . . . . . . . . . .
9.2 Basic Domino for IBM HTTP Server configuration . . . . . . . . . . . . .
9.2.1 Sample configuration: Basic Domino for IBM HTTP Server . . .
9.3 Multiple instances of the Domino for IBM HTTP Server . . . . . . . . .
9.3.1 Sample configuration: Second Domino for IBM HTTP Server .
9.4 Two or more IBM HTTP Servers connected to one Domino server .
9.4.1 Configuration Considerations . . . . . . . . . . . . . . . . . . . . . . . . .
9.4.2 Sample configuration: Additional IBM HTTP Server . . . . . . . .
. 127
. 127
. 127
. 128
. 128
. 129
. 129
. 129
. 129
. 130
. 130
. 131
. 132
. 134
. 136
. 139
. 139
. 141
Chapter 10. Migrating to the Domino for IBM HTTP Server .
10.1 Security considerations . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2 Migrating the configuration . . . . . . . . . . . . . . . . . . . . . . . .
10.3 Features not supported by the Web connector . . . . . . . . .
10.4 Testing a migrated application . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 143
. 143
. 144
. 144
. 145
Chapter 11. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1 Domino for IBM HTTP Server dependencies . . . . . . . . . . .
11.1.1 Software and required maintenance . . . . . . . . . . . . . .
11.1.2 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.4 Availability of system resources . . . . . . . . . . . . . . . . .
11.2 Error categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.2.1 Possible causes of Web connector initialization errors
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 151
. 151
. 151
. 152
. 152
. 152
. 153
. 153
Domino for S/390 and Web Server Integration
11.2.2 Possible causes of abends . . . . . . . . . . . . . . . . . . . . . . . .
11.2.3 Possible causes of connectivity problems . . . . . . . . . . . . .
11.2.4 Failure to access Domino resources . . . . . . . . . . . . . . . . .
11.3 Tools for problem determination . . . . . . . . . . . . . . . . . . . . . . . .
11.3.1 Error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.3.2 Installation verification checklist . . . . . . . . . . . . . . . . . . . .
11.3.3 RACF security reference materials . . . . . . . . . . . . . . . . . .
11.3.4 Activating Web connector trace messages . . . . . . . . . . . .
11.3.5 Activating the HTTP server trace . . . . . . . . . . . . . . . . . . .
11.4 IBM HTTP Server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.4.1 Troubleshooting Web connector startup errors . . . . . . . . .
11.5 Troubleshooting Web connector GWAPI initialization errors . .
11.5.1 Symptoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.5.2 Solutions for Web connector GWAPI initialization errors . .
11.6 Troubleshooting connectivity problems . . . . . . . . . . . . . . . . . . .
11.6.1 Symptoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.6.2 Solutions for connectivity problems. . . . . . . . . . . . . . . . . .
11.7 Troubleshooting authentication problems . . . . . . . . . . . . . . . . .
11.7.1 Symptoms of security-related problems . . . . . . . . . . . . . .
11.7.2 Solutions for security problems . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 153
. 153
. 154
. 154
. 154
. 154
. 154
. 155
. 156
. 156
. 157
. 160
. 160
. 161
. 162
. 162
. 163
. 165
. 165
. 166
Appendix A. Web connector initialization error messages . . . . . . . . . 169
A.1 DOMIHTTP-001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
A.2 ICH408I (Insufficient access authority) for BPX.SRV.userid profile . . . . 171
A.3 Browser Error 500: IMW0240E Access denied. . . . . . . . . . . . . . . . . . . . 172
Appendix B. Configuration value chart . . . . . . . . . . . . . . . . . . . . . . . . . 173
Appendix C. Installation verification checklist . . . . . . . . . . . . . . . . . . . 175
C.1 Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Appendix D. RACF security charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Appendix E. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Appendix F. Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
F.1 IBM Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
F.2 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
F.3 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
F.4 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
F.5 Lotus documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
How to Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
IBM Redbook Fax Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
vii
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
IBM Redbooks review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
viii
Domino for S/390 and Web Server Integration
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
Connector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Server audience Web page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Administration Settings Web page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Suggested IBM HTTP Server directory structure. . . . . . . . . . . . . . . . . . . . 36
Web server configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
httpd.conf preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
httpd.envvars preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Web server security setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Web server started procedure setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Authorizing the Started Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
A simple homepage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Listing interprocess communication resources . . . . . . . . . . . . . . . . . . . . . 61
Starting the IBM HTTP Server from the OS/390 console . . . . . . . . . . . . . 63
Stopping the IBM HTTP Server from the OS/390 console. . . . . . . . . . . . . 63
Use of the OS/390 MODIFY command to display server information . . . . 64
Use of the OS/390 MODIFY command to restart the IBM HTTP Server . . 64
Enabling Java options in Netscape Navigator . . . . . . . . . . . . . . . . . . . . . . 66
Enabling Java options in Microsoft Internet Explorer. . . . . . . . . . . . . . . . . 67
IBM HTTP Server configuration and administration authentication . . . . . . 69
IBM HTTP Server introduction page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Sample IBM HTTP Server administration form . . . . . . . . . . . . . . . . . . . . . 71
Sample IBM HTTP Server administration form help . . . . . . . . . . . . . . . . . 72
IBM HTTP Server help contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
IBM HTTP Server help index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Web Server administration flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Person document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Anonymous request with Domino standard authentication . . . . . . . . . . . . 85
Basic authentication request with Domino standard authentication. . . . . . 86
Client certificates with Domino standard authentication . . . . . . . . . . . . . . 87
Basic authentication request with OS/390-based authentication . . . . . . . . 88
Basic OS/390 authentication request using RACF . . . . . . . . . . . . . . . . . . 89
Client certificates with OS/390-based authentication. . . . . . . . . . . . . . . . . 91
X.509 and basic authentication with OS/390 authentication . . . . . . . . . . . 93
IKEYMAN entry panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
IKEYMAN: Key database menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
IKEYMAN: Create a self-signed certificate . . . . . . . . . . . . . . . . . . . . . . . 101
IKEYMAN: Key database menu - option 11. . . . . . . . . . . . . . . . . . . . . . . 102
Requesting a server certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Domino certificate processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
httpd.conf setting for SSL mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
© Copyright IBM Corp. 2000
ix
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
x
VV trace for correct SSL setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Create Domino database authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Create Certificate Authority key ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Creating CA server key ring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Transferring the key ring using FTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Creating a new Person entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Request a client certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Pick up signed client certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Certificate pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Basic Domino for IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Section of httpd.envvars for IBM HTTP sample 1 . . . . . . . . . . . . . . . . . . 133
httpd.conf for IBM HTTP sample 1 with standard Domino authentication 133
Two separate instances of the Domino for IBM HTTP Server . . . . . . . . . 134
Section of httpd.envvars for IBM HTTP sample 2 . . . . . . . . . . . . . . . . . . 137
Section of httpd.conf for IBM HTTP sample 2 . . . . . . . . . . . . . . . . . . . . . 138
Two IBM HTTP Servers to one Domino server . . . . . . . . . . . . . . . . . . . . 139
Multiple IBM HTTP Servers to one Domino server . . . . . . . . . . . . . . . . . 140
Section of httpd.envvars for second (additional) HTTP server . . . . . . . . 142
Section of httpd.conf for second (additional) IBM HTTP Server . . . . . . . 142
Using both Domino for IBM HTTP connector & Domino HTTP task . . . . 146
HTML code for a Web page with different links . . . . . . . . . . . . . . . . . . . . 147
HTML page with links to different servers and comparison . . . . . . . . . . . 147
HTML code to display the comparison in frames. . . . . . . . . . . . . . . . . . . 148
HTML output to the frames comparison. . . . . . . . . . . . . . . . . . . . . . . . . . 149
RACF parameters for IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . 177
RACF parameters for Domino for IBM HTTP Server connector . . . . . . . 177
RACF parameters for Domino and DOMCON for OS/390. . . . . . . . . . . . 178
Domino for S/390 and Web Server Integration
Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
Configuration values used in examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Sample parameter values for httpd.conf configuration . . . . . . . . . . . . . . . 12
Data set allocations from the installation JCL (3390-3 cylinders) . . . . . . . 17
Allocation values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Installation parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
First Server in Domain configuration parameter values . . . . . . . . . . . . . . . 26
MODIFY command options using Web server administration forms . . . . . 76
Basic Domino for IBM HTTP Server sample configuration parameters . 132
Second Domino for IBM HTTP Server sample configuration parameters 136
Additional IBM HTTP Server sample configuration parameters . . . . . . . 141
© Copyright IBM Corp. 2000
xi
xii
Domino for S/390 and Web Server Integration
Preface
This redbook describes how to customize and use the Domino for IBM HTTP
Server, a component available in Domino R5.0.1. This component supports
the use of the IBM HTTP Server for OS/390 to process HTTP requests for
Domino databases. In this book we refer to the Domino for IBM HTTP Server
as the “Web connector”.
This book briefly describes the setup of the environment needed to run the
Domino for IBM HTTP Server, including Domino 5.0.1 for OS/390 and the IBM
HTTP Server 5.1 for OS/390. We describe the differences between the
Domino internal HTTP task and the Web connector, as well as how to migrate
from the Domino HTTP task to the Web connector.
To help you decide how and when to use the Domino for IBM HTTP Server,
we also provide you with different scenarios and usage examples. We give
detailed information about security, authentication, and electronic certificates
to be used with Domino through the Web connector. We also provide
troubleshooting tips in case you run into any problems.
We amassed a lot of experience while using these products and testing the
different scenarios. All this experience is presented in this book and will help
you to set up a Domino for IBM HTTP Server environment very smoothly.
We wrote this redbook for Domino administrators, Webmasters and systems
programmers who install or customize the Domino for IBM HTTP Server on
OS/390 or migrate to this environment. It will also help the operations staff to
run the environment.
The team that wrote this Redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization Poughkeepsie
Center.
Roland Trauner is an IT consultant and professional expert at the
International Technical Support Organization, Poughkeepsie Center. He
writes extensively and teaches IBM classes worldwide on all areas of OS/390
e-business and network computing. Before joining the ITSO in 1998, Roland
worked on the IBM S/390 technical support team in Germany for IBM EMEA
Central Region. Roland joined IBM in 1979. If you have questions or
comments regarding this book, you may contact him at trauner@us.ibm.com.
© Copyright IBM Corp. 2000
xiii
Tony Llopis is a Consulting Information Technology Specialist. He has many
years of experience in the OS/390 area. Tony works in the IBM Lotus
Integration Center in Dallas, Texas as part of the ILIC Domino/390 team. He
has been involved with Domino/390 since the very first beta release. Tony is a
Certified Lotus Principal in Notes System Administration.
Brian Mikes is a Systems Engineer in the US. He holds a bachelors degree
in Management Information Systems from the University of Florida. His areas
of expertise include OS/390 UNIX System Services and OS/390 Web server.
DJ Sher is a Senior Information Technology Specialist with the IBM Global
Services organization in the United States. She has 17 years of experience in
the large systems software field. Her areas of expertise include Domino/390
installation, OS/390 UNIX System Services enablement, and Web server
implementation. For the past two years she has assisted large customers to
enable the e-business platform on S/390 Enterprise servers.
Thanks to the following people for their invaluable contributions to this
project:
Mike Ebbers
International Technical Support Organization, Poughkeepsie Center
James A. Ray
IBM USA, Poughkeepsie
Joe Gdaniec
IBM USA, Endicott
Don. R. Resnik
IBM USA, Poughkeepsie
Thomas Bradley
IBM USA, Poughkeepsie
Laura Smith
IBM USA, Albany
Bill Schnyder
IBM USA, St. Louis
Jacques Fusilier
IBM USA, Dallas
xiv
Domino for S/390 and Web Server Integration
James Caffrey
IBM USA, Poughkeepsie
Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Please send us your
comments about this or other Redbooks in one of the following ways:
• Fax the evaluation form found in “IBM Redbooks review” on page 197 to
the fax number shown on the form.
• Use the online evaluation form found at http://www.redbooks.ibm.com/
• Send your comments in an Internet note to redbook@us.ibm.com
xv
xvi
Domino for S/390 and Web Server Integration
Chapter 1. Domino for IBM HTTP Server introduction
The Domino for IBM HTTP Server is an IBM HTTP Server API (GWAPI)
program that connects Domino 5.0.1 to the IBM HTTP Server. In this book we
usually refer to it as the “Web connector”. The Web connector allows you to
access Domino databases using a Web browser that is connected to a Web
server on OS/390 Web (IBM HTTP Server for OS/390). The Web connector
runs as a GWAPI program in the IBM HTTP Server tasks and accesses
Domino databases using Domino APIs.
Based on the GWAPI construct, most of the workload is shifted from the
Domino Server to the IBM HTTP Server.
Domino for OS/390 R5 still provides the internal Web server in addition to this
new feature. The preferred option to access Domino is to use the Domino
client software; it is still the most efficient way to access Domino applications.
The Web server connectivity option is preferred for thin clients.
Now, since there are two different methods of accessing Domino databases
using the Web interface, your question will very likely be, which interface
should you choose?
In Chapter 9, “Configuration scenarios” on page 127, we list pros and cons of
several configuration scenarios. That chapter can help you to decide which
configuration you need in your environment.
1.1 Reasons to use the Domino for IBM HTTP Server connector
You probably want to use the Domino for IBM HTTP Server interface in the
following cases:
• If you want to use Domino data or Domino access as part of a Web site
that will also contain other fancy Web elements such as animation or
multimedia. In this case you probably want to serve pictures, frames,
multimedia and other components directly from the IBM HTTP Server
without having Domino involved, and display the Domino application as
part of a browser frame. This can be important in terms of performance
since the IBM HTTP Server has several performance features like the
FRCA cache.
In this redbook project, we did not measure the performance differences
between accessing Domino applications through the internal Domino
HTTP task or through the Web connector. It appeared to us, however, as if
both access methods were about equal in performance.
© Copyright IBM Corp. 2000
1
When it comes to static Web serving however, such as accessing pictures
and other static objects, then there is an advantage in using the OS/390
Web server.
• If you want to run servlets and Java Server Pages through the IBM
WebSphere Application server rather than through the Domino Servlet
Manager.
• If you want to be more flexible and have more influence on workload
balancing by using the scalable Web server or by splitting the Domino
application so it can be accessed through different Web servers.
• If you want to use OS/390 user authentication as described in Chapter 6,
“OS/390 authentication support for Domino” on page 79.
1.2 Reasons not to use the Domino for IBM HTTP Server
You probably would not want to use the Domino for IBM HTTP Server
interface in the following cases:
• If you only need to Web-enable the Domino database access and you are
not experienced in the OS/390 UNIX environment, especially not in the
OS/390 Web server-OS/390 WebSphere Application Server environment,
you will probably just set up the internal Domino Web interface. This
option also has the advantage of being consistent across the platforms
that support Domino.
• If you are mostly accessing Domino using the client software and the few
Web accesses would look too different from the client interface
appearance.
• If you want to use the Domino Internet Cluster Manager.
• If you want to use the Domino Web server API (DSAPI) filters.
See also 10.3, “Features not supported by the Web connector” on page 144
for other considerations.
1.3 Use both Web interfaces
There is no “exclusive or” to use either the internal Domino Web interface or
the Web connector. You may in fact combine both methods if you need to use
functions provided by one or the other.
This can be easily achieved, for example, by running the IBM HTTP Server
and Domino using the internal Web interface on the same system using
different IP addresses (defined through TCP/IP VIPA). By using HTTP
2
Domino for S/390 and Web Server Integration
hyperlinks to access these services, the end user is not necessarily even
aware that he or she is working with different servers.
Domino for IBM HTTP Server introduction
3
4
Domino for S/390 and Web Server Integration
Chapter 2. Configuring the Domino for IBM HTTP Server
This chapter guides you through the process of setting up the Domino for IBM
HTTP Server (Web connector) configuration using the standard Domino Web
authentication model, in which the user’s credentials are validated against
information stored in the Domino directory. The following sections focus on
the steps required to connect the IBM HTTP Server to a Domino server when
they are both already pre-installed.
However, since this may not be the case, we will also direct you to the
following chapters, covering the installation of either of the servers. Complete
the following steps to set up the Domino for IBM HTTP Server:
1. If you do not have the Domino/390 server operational, proceed to install,
set it up, and test it as described in Chapter 3, “Domino server installation”
on page 15.
2. If the IBM HTTP Server instance that will run the Web connector does not
exist yet, proceed to install, set it up and test it as described in Chapter 4,
“Basic IBM HTTP Server installation” on page 35.
Important
Due to the way that Domino and the Domino for IBM HTTP Server share
data, it is necessary to stop the IBM HTTP Server that is running the
Web connector when the Domino server is stopped or terminates
abnormally. Because of this, we recommend that you do not run Domino
for IBM HTTP Server in the same IBM HTTP Server instance as you run
other Web applications with critical availability requirements.
Similarly, if you are running the IBM HTTP Server as a scalable server,
you should not run the Web connector in the same queue server
instance as other Web applications with critical availability
requirements.
3. Update the Domino/390 server configuration to prepare to run with the
Web connector as described in 2.2, “Updating the Domino server
configuration” on page 7.
4. Update the IBM HTTP Server configuration to adjust its permissions and
environment variables, and to activate the Web connector as a GWAPI
plug-in module. This is described in 2.3, “Updating the IBM HTTP Server
configuration” on page 10.
© Copyright IBM Corp. 2000
5
Once the Domino for IBM HTTP Server has been configured properly, it is
time to start it by starting both servers, Domino and the IBM HTTP Server.
Then it will be appropriate to perform initial testing by accessing some
Domino databases through the Web connector, including both public
databases and databases that require authentication. For details about
operation, refer to Chapter 5, “Operating the Domino for IBM HTTP Server”
on page 45.
2.1 Configuration parameters values
The sections that describe setting up and running the Domino for IBM HTTP
Server make references to many parameters which are given specific values
for a particular configuration instance, such as the location of HFS
directories, user IDs for the Domino and IBM HTTP servers, and so on. Table
1 illustrates values that are generally used throughout the book. When
configuring your Domino for IBM HTTP Server, be sure to replace these
values with the proper ones for use in your system.
Table 1. Configuration values used in examples
Parameter
6
Value as used in examples
Domino product install directory
/usr/lpp/lotus
Domino product executables directory
/usr/lpp/lotus/notes/latest/os390
Domino data directory
/notesdata1
Domino directory database
names.nsf
Domino Server User ID (RACF)
DOMINO1
Domino UNIX group
NOTESGRP
Domino Server name
domweb1/itsoweb
Domino Server TCP Host Name
domweb1.itso.ibm.com
IBM HTTP Server install directory
/usr/lpp/internet
IBM HTTP Server server-root directory
/usr/lpp/internet/server_root
IBM HTTP Server User Id(RACF)
WEBSRV
IBM HTTP Server UNIX group
IMWEB
IBM HTTP Server TCP Host Name
domweb1.itso.ibm.com
IBM HTTP Server configuration
/etc/httpd.conf
IBM HTTP Server environment variable
/etc/httpd.envvars
Domino for S/390 and Web Server Integration
2.2 Updating the Domino server configuration
After you have installed and set up the Domino for OS/390 server and verified
that it works correctly, make the following changes to the Domino server
environment in order to prepare for running in a Domino for IBM HTTP Server
configuration.
2.2.1 Verifying the ServerKeyFilename setting
If the Domino server ID file (typically called server.id) is not located in the
Domino data directory, the notes.ini file for the server must include a
fully-qualified path to the server ID file in the ServerKeyFilename setting.You
should examine notes.ini and update this setting if necessary. Since notes.ini
is an ASCII file, you must use the proper tool to preserve the character set.
Two commonly used tools are:
• From the telnet shell, use viascii, which provides a vi-like interface.
• From the USS shell, use oeditascii. It has an ISPF editor look and feel.
2.2.2 Enforcing unique name resolution
Because of the authentication processing and mapping that the connector
does when the optional OS/390 authentication support is in use, security
exposures exist if Domino Web user name lookup is allowed to resolve a Web
user name to more than one Person document. The notes.ini variable
NoAmbiguousWebNames with the proper setting can be used to prevent
successful Web user name lookup if the results are not unique. Edit notes.ini,
and add the following setting to the file:
NoAmbiguousWebNames=1
The Web connector enforces that this setting is in effect by checking it at
initialization time. The connector’s initialization will fail if this setting does not
exist in the notes.ini file for the Domino server. Verify that the server ID file
does not use a password. You cannot enter a password when the IBM HTTP
Server starts up the Web connector.
2.2.3 Allowing HTTP server access to selected Domino files
Make sure the OS/390 user ID under which the IBM HTTP Server runs
(WEBSRV, in our case) has read-write access to the following files in the
Domino data directory (i.e. /notesdata1):
Configuring the Domino for IBM HTTP Server
7
-rw-------rw-------rw-------rw-------
1
1
1
1
DOMINO1
DOMINO1
DOMINO1
DOMINO1
NOTESGRP 4980736 Aug 17 12:06
NOTESGRP
2033 Aug 17 11:55
NOTESGRP
2307 Aug 13 08:41
NOTESGRP
2307 Aug 13 08:41
names.nsf
notes.ini
server.id
log.nsf
Depending on the authority of the IBM HTTP Server user ID, you may need to
take action:
• When it is configured as usual as a UNIX superuser, no special action has
to be taken to grant it read-write access to the above files because a UNIX
superuser can access any file in the HFS regardless of permission-bit
settings.
• If, however, the IBM HTTP Server user ID is not a superuser, then you
should modify the group and permission bits associated with these files so
that they are owned by the Domino UNIX group (i.e. NOTESGRP) and
permit read-write access to members of that group. You should also
ensure that members of the Domino UNIX group have read-write access
to the Domino data directory itself. In our project, the IBM HTTP Server
was configured as superuser, but if that is not your case, the following
UNIX shell commands would do the job:
$
$
$
$
$
cd /notesdata1
chgrp NOTESGRP $PWD
chmod g+rwx $PWD
chgrp NOTESGRP server.id notes.ini names.nsf log.nsf
chmod g+rw server.id notes.ini names.nsf log.nsf
The IBM HTTP Server user ID must also be added to the Domino UNIX
group NOTESGRP, as described in 2.3, “Updating the IBM HTTP Server
configuration” on page 10.
2.2.4 Setting program-controlled attribute for Domino binaries
Make sure that the Domino executable libraries all have the
program-controlled extended attribute set. This is needed so that they can be
successfully used by the Web connector GWAPI plug-in module running
within the IBM HTTP Server process. You can set this attribute by performing
the following OS/390 UNIX shell commands while logged on as a user ID with
superuser privileges:
8
Domino for S/390 and Web Server Integration
$ cd /usr/lpp/lotus/notes/latest/os390
$ extattr +p *
... ...
$ ls -E inotes*
-rwxr-xr-x -ps 1 BPXROOT NOTESGRP 7077888 Apr 3 17:39 inotes
As shown above, you can verify that the program-controlled extended
attribute has been set by using the UNIX shell ls -E command. The
program-controlled extended attribute is indicated by the p flag.
Note that use of the extattr command is controlled by a RACF profile, so the
user ID issuing the extattr command must be permitted to that profile, even if
it is a superuser. If the extattr command reports errors on its chattr() calls,
you probably do not have permission. Issue the following RACF TSO
commands from a user ID that has RACF SPECIAL permission:
permit bpx.fileattr.progctl class(facility) id(<yourid>) access(read)
setropts raclist(facility) refresh
Important
There are a number of reasons that will cause the program-controlled
attribute to be reset. If that happens, you must repeat the above process to
properly set the attribute.
A common reason for the reset is re-installing the Domino binaries, either
by adding a new server or upgrading the code level. Also a reset will occur
when the modules are subject to a change in ownership or group.
2.2.5 Adding a Domino user ID to the HTTP server group
Modify the attributes of the Domino server user ID (DOMINO1) so that it is
connected to the IBM HTTP Server RACF/UNIX group (IMWEB). This is
required for proper sharing of IPC resources between the Domino server and
the IBM HTTP Server running the connector. You can accomplish this by
executing the following TSO RACF command from a user ID with RACF
SPECIAL authority:
connect DOMINO1 group(IMWEB)
Configuring the Domino for IBM HTTP Server
9
2.3 Updating the IBM HTTP Server configuration
After you have completed the basic installation and setup of the IBM HTTP
Server instance that will run the Domino for IBM HTTP Server connector and
verified that it works, make the following changes to the IBM HTTP Server
configuration to prepare for running the Web connector and to activate the
connector GWAPI plug-in module:
2.3.1 Updating the IBM HTTP Server permissions
Modify the attributes of the IBM HTTP Server user ID (WEBSRV) so that it is
connected to the Domino RACF/UNIX group (NOTESGRP). This is required
for proper sharing of IPC resources between the Domino server and the IBM
HTTP Server running the connector. You can accomplish this by executing
the following TSO RACF command from a user ID with RACF SPECIAL
authority:
connect WEBSRV group(NOTESGRP)
Ensure that the IBM HTTP Server user ID (WEBSRV) has authority to act as
a surrogate for the Domino server user ID (DOMINO1). This ability is
controlled by a RACF profile in the SURROGAT class. To create the profile (if
necessary) and grant the WEBSRV user ID access to it, execute the following
TSO RACF commands:
permit bpx.server class(facility) id(WEBSRV) acc(read)
setropts raclist(facility) refresh
rdefine surrogat bpx.srv.DOMINO1 uacc(none)
permit bpx.srv.DOMINO1 class(surrogat) id(WEBSRV) acc(read)
setropts classact(surrogat)
See Chapter 14 of OS/390 UNIX System Services Planning, SC28-1890, for
background information on surrogate user setup.
Note: If you were using SERVER as the Domino server user ID, this could
lead to confusion, because the occurrence of SERVER in both bpx.server
and bpx.srv.SERVER would be just a coincidence. The term bpx.server is the
redefined name of a special FACILITY-class profile used to control the
permission of server applications on OS/390. On the other hand,
bpx.srv.SERVER would be the name of a the SURROGAT-class profile for the
particular Domino user ID called SERVER.
2.3.2 Updating the IBM HTTP Server environment variables
Update the IBM HTTP Server environment variable settings to add the
directories required by the Web connector. If you are running the IBM HTTP
10
Domino for S/390 and Web Server Integration
Server from a started procedure using the standard setup described in the
IBM HTTP Server publications, then the IBM HTTP Server obtains its initial
environment variables from the file /etc/httpd.envvars and you change its
environment variables by editing that file. If you are running with some
alternate setup, then you probably have a private httpd.envvars file. In
addition, if you are running the IBM HTTP Server from a UNIX shell session,
you may be inheriting environment variable settings from that shell
environment. In any case, make the following changes:
• Update the PATH environment variable to include the Domino data
directory, the Domino product executables directory, and the Domino
resources directory for your language. For example, if you are using the
North American or International English version of Domino installed in the
default locations, add the following directories to the PATH environment
variable:
/notesdata1
/usr/Lpp/lotus/notes/latest/os390
/usr/Lpp/lotus/notes/latest/os390/res/C
• Update the LIBPATH environment variable to include the Domino product
executable directory. For example, if you have installed Domino in the
default locations, add the following directory to the LIBPATH environment
variable:
/usr/lpp/lotus/notes/latest/os390
2.3.3 Activating the connector plug-in (Standard Domino authentication)
Update the IBM HTTP Server configuration file to add directives to activate
the connector GWAPI plug-in module and route requests for Domino
databases to it. If you are running the IBM HTTP Server from a started
procedure and are using the standard setup, the IBM HTTP Server
configuration file is /etc/httpd.conf. If you are running with some alternate
setup, then you probably have a private httpd.conf for that setup. In either
case, add the set of directives shown in Figure 1 on page 12 to the httpd.conf
file in sequence before the default Pass rule:
Configuring the Domino for IBM HTTP Server
11
NameTrans /icons/* DOM_INST_DIR/notes/latest/os390/domihttp:DomIcons
NameTrans /
DOM_INST_DIR/notes/latest/os390/domihttp:DomRootCmds
Protection DOMINO-CONNECTOR-SETUP {
Mask
Anybody
UserId
DOM_SERVER_ID
}
Protect
Protect
Protect
Protect
*.nsf
*.nsf/*
/domicons/*
/domjava/*
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
ServerInit DOM_INST_DIR/notes/latest/os390/domihttp:ServerInit "-sslport SSL_PORT"
Service *.nsf DOM_INST_DIR/notes/latest/os390/domihttp:Service
Service *.nsf/* DOM_INST_DIR/notes/latest/os390/domihttp:Service
ServerTerm DOM_INST_DIR/notes/latest/os390/domihttp:ServerTerm
Pass
Pass
/domicons/* DOM_DATA_DIR/domino/icons/*
/domjava/* DOM_DATA_DIR/domino/java/*
Figure 1. Connector definition
When adding these directives to the httpd.conf file, replace the placeholders
shown in italics (e.g. DOM_INST_DIR) with the values in use for your
configuration. In our case we used the ones shown in Table 2.
Table 2. Sample parameter values for httpd.conf configuration
Placeholder
Represents
Sample Value
DOM_DATA_DIR
Domino data directory
/notesdata1
DOM_INST_DIR
Domino product
directory
/usr/lpp/lotus
DOM_SERVER_ID
Domino server user ID
DOMINO1
SSL_PORT
SSL-mode port number
443
installation
The IBM HTTP Server processes its configuration file in an order-dependent
manner. Because of this, it is important that the relative order of the directives
as shown above be preserved. Also, it is important that the block of directives
shown above must appear before the configuration files default Pass rule (the
"Pass /* <someplace>" rule); otherwise, they will not have the correct effect.
Notes: The connector will automatically detect the normal-mode and
SSL-mode ports being used by the Web server when it processes the first
normal-mode and SSL-mode requests, respectively. However, it is possible
that the connector will need the SSL-mode port number before it has
processed the first SSL-mode request. This will occur if Domino tries to
12
Domino for S/390 and Web Server Integration
redirect a non-SSL connection to be an SSL one before the connector has
processed the first explicitly-specified SSL request.
The -sslport option on the Web connectors ServerInit directive is used to
inform the connector of the SSL-mode port numbers in use by your Web
server to handle this specific situation. You must include the -sslport option
on the ServerInit directive if your Web server is using an SSL-mode port other
than 443. Note that the -sslmode option does not change the SSL-mode port
number being used by the Web server.
Be aware that the entire set of initialization options on the ServerInit directive
(everything following the domihttp:ServerInit part) must be enclosed in
double quotes so that the entire string is passed to the connector, rather than
just the first blank-delimited token. If you do not enclose the initialization
string in quotes, the Web connector will report syntax errors with the
initialization options.
The purpose of the Mask Anybody directive shown Figure 1 on page 12 is to
request that the IBM HTTP Server perform no access-control checking for
requests that it passes through to the connector. However, all normal Domino
security mechanisms apply because they are enforced by the connector and
Domino while processing the request.
Configuring the Domino for IBM HTTP Server
13
14
Domino for S/390 and Web Server Integration
Chapter 3. Domino server installation
This chapter describes the setup of the Lotus Domino server on S/390. The
information here was composed using the Domino Installation Guide and
Lotus Domino for S/390 Release 5: Installation, Customization and
Administration, SG24-2083 which we suggest as your work basis. Note,
however, that a redbook is not the real installation documentation, but an
augmented publication. Although it may include more detail than the real
installation guide included in the CD, it does not represent the latest
installation information.
Important
For the latest information, and before Installing Domino for S/390, you must
read the following documentation included in the Domino for OS/390 CD.
You can read txt files with Notepad, nsf with an R5 Notes Client, and PDFs
with the Adobe Acrobat Reader:
• Getting started instructions in file Start.txt
• Last-minute comments in file readme.txt
• Release Notes: Domino for System 390 (readmes.nsf or readmes.pdf)
• Installation Guide: Domino for System 390 (srvs390.nsf or srvs390.pdf)
• For the latest maintenance, use a Web browser to access URL:
www.s390.ibm.com/products/domino/domptf.html
The following sections cover a “quick and proper” installation of a First in
Domain Domino for S/390 server. Due to this scope, a number of install
choices have been made, leaving unexplored a number of alternative
installation paths. If your plans call for any of these alternative options, refer
to the above documentation sources for proper guidance. Our Domino/390
installation can be summarized in the following steps:
• Check hardware and software requirements.
• Prepare the OS/390 operating environment.
• Transfer files from the Domino CD to the system and allocate data sets.
• Run the install program interactively.
• Verify path statements (PATH, LIBPATH, AND CLASSPATH).
• Configure the Domino server using the HTTP server/browser interface.
• Prepare the dynamic LPA library.
© Copyright IBM Corp. 2000
15
3.1 Required hardware and software
Lotus Domino for S/390 Release 5 requires the following software and
hardware:
• OS/390 Version 2 Release 6 or higher and the required PTFs listed at:
http://www.s390.ibm.com/products/domino/domptf.html
• Java Development Kit (JDK) 1.1.6 or higher.
Note: Java for OS/390 is an optional product. It is orderable in SMP/E
format through your normal IBM software ordering channels. It is also
available for download at: http://www.ibm.com/s390/java. You only need to
install the JDK if you will use HTTP, DIIOP or Java agents, but we
recommend that you install it anyway, because you may not require these
functions now but may want to use them in the future.
• The OS/390 C/C++ IBM Open class library installed. No license for the
C/C++ feature of OS/390 is required.
• High-level-qualifier.SCLBDLL must be in the program search order (for
example, in the SYS1.PARMLIB member, LNKLSTxx or PROGxx).
• A workstation with a CD-ROM and a connection to the S/390 where
Domino will be installed.
• TCP/IP networking support.
• DASD volumes for the HFS datasets where Domino data will reside.
Note: It is recommended that your installation enables the DASD
fast-write function, which provides control unit caching for the Notes data.
See 3990/9390 Planning, Installation, and Storage Administration Guide,
GA32-0100, or the equivalent for your storage subsystem, for more
information. DFSMS 1.5 also improves HFS performance.
These OS/390 publications will be helpful to you during installation:
• Lotus Domino for S/390 Release 5: Installation, Customization and
Administration, SG24-2083
• OS/390 Planning for Installation, GC28-1726
• Program Directory for OS/390
• OS/390 UNIX System Services Planning, SC28-1890
16
Domino for S/390 and Web Server Integration
3.1.1 DASD space
Table 3 show the minimum DASD space that is needed for the initial
installation of the Domino server on S/390. This space is in three HFS data
sets. We recommend that you use DASD fast-write caching or other fast
access methods for these volumes.
Table 3. Data set allocations from the installation JCL (3390-3 cylinders)
Data Type
HFS Data Set
Mount point
Default allocation
Dynamic LPA
yyyy.LPAPDSE
-----------------------
65 CYL
Product files
xxxx.PROD
/usr/lpp/lotus
600 CYL
Notes control files,
databases and
templates
xxxx.DATA
/notesdata1
500 CYL
Notes mail files
xxxx.MAIL
/notesdata1/mail
500 CYL
These data sets are allocated with the supplied job ALOCPROD. Although the
space allocations in the supplied job may be larger than the values actually
required for the install, it is suggested you use the defaults in the supplied JCL
because the Domino R5 install process does a preliminary check to determine
if the existing allocation will be sufficient for a successful install, in which case
it will proceed. Otherwise it will terminate with an error and you will be forced
to delete and reallocate the datasets.
Note that the install script does not see the possibility of creating secondary
extends. Also, be aware that to go into production, you will likely need to
significantly increase the DATA and MAIL allocations. We recommend that
you size your production requirements carefully and design your HFS data
sets and directory structure accordingly.
Domino server installation
17
3.2 Preparing the OS/390 operating environment
Once you have installed OS/390 and the UNIX environment, there are
specific customization steps required for Domino. See Domino for S/390
Install Guide for Servers for the latest parameter setting information.
Warning
The most common reasons for server start failure after installing Domino
are:
• Not all required PTFs were applied.
• One or more BPXPRMxx parameters were not set to the recommended
value.
We strongly recommend that you apply all PTFs and set the parameters
exactly as specified in Domino for S/390 Install Guide.
Note: For hints and tips on errors you might encounter while setting up
Domino R5, see the “Troubleshooting and Hints & Tips” section of Lotus
Domino for S/390 Release 5, SG24-2083.
3.2.1 Authorizing a user who will install the Domino server
The user ID which is used to install the Domino server on OS/390 must be
defined to RACF with a valid OMVS segment (a valid UID and GID) and must
have a UID of 0 (superuser) to be able to mount the HFS data sets. The user
may either be defined with a permanent UID of 0 or be permitted READ
access to the BPX.SUPERUSER RACF FACILITY class, thus enabling the
use of the su command.
3.2.2 Authorizing the Domino server
The Domino server runs as a user on OS/390. The user ID is the one that is
used to start the server. This user ID must be defined to RACF with a valid
OMVS segment (a valid UID and a valid GID). The user ID must have
authority to access all of the Domino server files on the HFS, including:
• The server’s notes data directory.
• All the files under the notes data directory.
• The notes.ini file.
• The /usr/lpp/lotus directory.
• All the files under the /usr/lpp/lotus directory.
18
Domino for S/390 and Web Server Integration
• Write access to /tmp.
• Read access to the BPX.STOR.SWAP RACF FACILITY class (if the
installation has a requirement to run the server non-swappable).
• Read access to BPX.SMF RACF FACILITY class (if you want the Domino
server to create SMF 108 records).
Note: You will also need to update the SMFPRMxx PARMLIB member to
include SYS(TYPE(108)).
Attention
Never run the Domino server from a user ID with a UID of 0. The server
runs agents on behalf of users, so it is possible that a user could run an
agent with superuser authority. In addition, cleanup of leftover IPCS
resources would be practically impossible if using a UID of 0.
If needed, you can change the owning user ID and group ID for a file by
issuing the UNIX command chown.
3.3 Preparing to install the Domino server code
This section discusses the first stage of the installation of the Domino Server
code on the S/390 server. These tasks will typically be done by an OS/390
system programmer and others familiar with OS/390.
3.3.1 Allocate the OS/390 data sets
Use TSO and use ISPF (option 3.2) to allocate two OS/390 data sets to
receive the data from the CDROM:
• Allocate a partitioned data set (PDS) to store the JCL and PARMLIB files.
Use the values in Table 4.
Table 4. Allocation values
Attribute
Value
Space units
BLOCKS
Primary quantity
10
Secondary quantity
1
Directory blocks
5
Record format
FB
Record length
80
Domino server installation
19
Attribute
Value
Block size
3120
Note: You can specify any permitted PDS name. DOMINO.R501.JCL.CNTL
was used in the following instructions.
3.3.2 Transferring the files using FTP
Four files must be uploaded from your workstation to an OS/390 PDS using
FTP in binary mode. Follow the FTP example for step-by-step instructions to
send the installation files into an OS/390 PDS.
FTP example from PC-DOS command prompt:
1. Begin an FTP session from the workstation to OS/390 UNIX System
Services:
FTP WTSC59
<= WTSC59 is the TCP name of our OS/390 server
2. Enter in your user ID and password.
3. Transfer the files in binary.
bin
<= Switch to binary mode and press enter.
4. Change to the target location of the PDS.
cd ’domino.r501.jcl.cntl’
5. Change to the drive where the CD is located.
lcd E:\
6. Transfer the sample files from the CD-ROM on your workstation to the
pre-allocated OS/390 PDS.
put
put
put
put
alocprod.501
mdfybpxp.501
mdfyprog.501
putinlpa.501
alocprod
mdfybpxp
mdfyprog
putinlpa
7. Check that the PDS contains these files and that they are readable.
3.3.3 Allocating HFS data sets (ALOCPROD)
Modify the contents of the sample ALOCPROD job using the instructions in
the file and these guidelines:
• If this is the first-time Domino install, the job will allocate and provide
mount points for /usr/lpp/lotus, /notesdata, and /notesdata/mail. You can
modify the amount of DASD space allocated for /notesdata and
20
Domino for S/390 and Web Server Integration
/notesdata/mail, as well as change the mount points to your liking (for
example, to /notesdata1 and /notesdata1/mail).
• If this is a migration (upgrade) from a previous release, modify the job so
that only /usr/lpp/lotus and a new Dynamic LPA data set is allocated. You
will use the existing /notesdata and /notesdata/mail directories.
Submit the ALOCPROD job to allocate the product HFS data set and the
dynamic LPA PDS/E. Additionally, ALOCPROD will create the HFS mount
points and temporarily mount the HFS data sets at these mount points. Check
the results of the ALOCPROD job to ensure no errors have occurred.
3.3.4 Transferring the Domino server TAR file
This step will load the server code tar file into the Hierarchical File System
(HFS). The tar file must be transferred in binary mode.
FTP example:
• On the workstation, start an FTP session to the OS/390 UNIX System
Services FTP server.
• Enter bin to have the file transferred in binary.
• Enter cd /usr/lpp/lotus to change to the target location of the HFS.
• Using the LCD command, change to the appropriate drive where the CD is
located.
• Enter put xxx.tar to transfer this file.
Check to make sure the file size matches that of the original on the CD-ROM.
To untar the xxx.tar file, go into the OS/390 UNIX System Services shell by
entering OMVS from PDF option 6. From the OS/390 UNIX shell, enter:
cd /usr/lpp/lotus
tar -xvozf xxx.tar
Note: This will unpack the file and place the packed files in the correct paths
below the /usr/lpp/lotus path. This will take a couple of minutes.
Now enter ls -al to validate that the sub-paths exist. If the files are there, you
can delete the tar file from the HFS to save space by entering rm xxx.tar. You
can always reload the tar file from the CD.
3.3.5 Integrating the MOUNT statements from MDFYBPXP
When you re-IPL the system, the mounts you did in the ALOCPROD job will
be lost. You need to make sure that the mount commands are issued every
time the system is re-IPLed.
Domino server installation
21
To accomplish this, you need to copy the mount statements from the
MDFYBPXP file into SYS1.PARMLIB(BPXPRMxx). The mount statements will
then be processed at IPL time. The MDFYBPXP file needs to be checked to
verify that the data set and directory names match those you used when you
ran ALOCPROD.
3.4 Running the install program
This section describes how to run the Domino server installation and
configuration programs. These tasks will typically be done by a Notes
administrator with some help from an OS/390 systems programmer.
We chose to use the interactive version, as opposed to the background script
version of the install program. To start the process follow these steps:
• Log in to the OS/390 UNIX environment with a RACF user ID that has
UID=0.
Important
You must log in using rlogin or Telnet. Running install from the OMVS
shell is not supported.
• Type /usr/lpp/lotus/os390/install
At this point you will be prompted for the information needed to install the
server.
3.4.1 Provide Domino installation parameters
As you proceed with the installation, you will be asked to provide values for
the installation parameters summarized in Table 5 :
Table 5. Installation parameter values
22
Parameter
Value
Setup type
Domino Enterprise Server
Program directory setting
/usr/lpp/lotus
Run partitioned servers
NO
Path name of data directory
/notesdata1
Domino UNIX user (RACF)
DOMINO1
Domino UNIX group (RACF)
LOTUSGRP
Domino for S/390 and Web Server Integration
Setup type
You can choose whether to install a Domino Mail Server, a Domino
Application Server, or a Domino Enterprise Server. For our purpose we
chose to install the Domino Enterprise Server.
Program directory setting
Specify a directory in an OS/390 UNIX HFS for the Domino server
program files. The default directory as created by the ALOCPROD job is
/usr/lpp/lotus.
Run partitioned servers
You can run more than one Domino server on the same OS/390 Logical
Partition or LPAR. This feature is called Domino Partitioned Servers and
requires separate notes data directories for each Domino server.
Number of data directories
If you selected partitioned servers, you have to specify the number of
servers or notes partitions.
Notesdata values
For each of the servers (either just one if not running partitioned, or
otherwise for each one of the partitions), you will be prompted for the path
and owner/group of the notesdata directory:
Path name for data directory
Select a value that makes sense to you. We used /notesdata1,
/notesdata2.
Domino UNIX user that will own the data directory
Identify the RACF UNIX user ID under which the Domino server will
run. This user ID will become the owner of the server notesdata
elements: directory and objects contained under it.
Domino UNIX group
This is the RACF group to which the previous server ID pertains. Note
that all server IDs must be part of the same group, as well as the
DOMCON ID if the MVS Domino console package is to be used.
Once the notesdata values have been provided, you will be given the
chance to review the settings that you have made. Then, either rework the
answers if you made a mistake, or if satisfied, press the TAB key to let the
installation proceed. The installation process may take an extended period
Domino server installation
23
of time, depending on the size of your machine, system load, and the
number of Domino servers you are building.
3.5 Verifying path statements
After installing the Domino server, verify that the paths are set up correctly for
the user that you specified during the install program. If the path statements
are not correct, change them as necessary.
To set environment variables for a UNIX user, you must edit the .profile file
that is in their HOME directory.
The PATH and LIBPATH statements must contain the location of the
native_threads subdirectory of the Java Development Kit (JDK). The
CLASSPATH must include the classes.zip subdirectory.
Use the echo command to review the PATH. For example, use echo $LIBPATH
to review LIBPATH.
Note: The PATH statements are installation-dependent. The Java path is only
necessary if you require Java support, but you may as well put it in to avoid
error messages at server initialization.
PATH=/usr/lpp/lotus/bin:/usr/lpp/lotus/bin/tools:/bin:/usr/lpp/java/
J1.1/bin:/usr/lpp/java/J1.1/lib/mvs/native_threads:
LIBPATH= /usr/lpp/java/J1.1/lib/mvs/native_threads:
CLASSPATH=/usr/lpp/java/J1.1/lib/classes.zip
After completing this step, you are ready to configure the new Domino
server(s) using the Domino HTTP server task and a Web browser.
3.6 Configuring a new Domino server
After installing the Domino for OS/390 binaries and populating the server’s
notesdata directory, you are ready to perform the configuration of the server
as a “First Server in Domain”. First we explain what happens when a First
Server in Domain is created, then we proceed with the configuration steps.
3.6.1 Understanding a “First Server in Domain” configuration
This is an overview of what happens when you run the first server
configuration.
24
Domino for S/390 and Web Server Integration
Configuring the first Domino server does the following:
• It creates a new domain for the Domino servers.
• It enables the appropriate network and serial ports.
• It creates the Domino directory for the domain. The configuration program
uses the PUBNAMES.NTF template to create the Domino directory in the
same directory you choose for Domino data files, and gives it the default
name NAMES.NSF.
• It creates a certifier ID for your organization. The configuration program
saves the certifier ID in the same directory you choose for Domino data
files and gives it the default name CERT.ID.
• It creates a certifier document in the Domino directory. This document
describes the certifier ID.
• Creates a server ID for the new server. The configuration program saves
the server ID in the same directory you chose for Domino data files and
gives it the default name SERVER.ID.
• Certifies the server ID with the organization certifier ID.
• Creates a server document in the Domino directory. This document
describes the first server based on information that you specify during
configuration.
• Creates a person document in the Domino directory for the Domino
administrator specified during configuration.
• Creates a user ID and a password for the Domino administrator and
attaches it as a file named user.id to the administrator’s person document
in the Domino directory.
• Certifies the administrator’s user ID with the organization certifier ID.
• Adds the administrator’s name and the server's name as managers in the
access control list of the Domino directory.
• Adds the server name to the LocalDomainServers group in the Domino
directory.
• Creates a mail directory in the Domino data directory and a mail file in that
directory for the Domino administrator.
Domino server installation
25
3.6.2 Starting the HTTP task in server configuration mode
1. Logon to the system as the Domino user ID that was specified during the
install.
Important
This user ID should not be UID=0. It should also be not the same
user ID that was used to install the code.
2. Change to the Notes data directory.
3. Enter the following to start the HTTP server:
/usr/lpp/lotus/bin/http httpsetup
Note: The httpsetup program must be run from the Notes Data Directory
for each server being configured. If three Notes data directories were
populated during install, /notesdata1, /notesdata2, /notesdata3, httpsetup
would be run three times, each time logging on as the owner of a
particular notes data directory.
4. When prompted, connect to the server with a Web browser, such as
Netscape Communicator. Use the port specified by the configuration
program. For example, if the server is domweb1.itso.ibm.com with
corresponding IP address 192.168.5.97 and the specified port is 8081,
you would enter the following in the Web browser’s location entry field:
http://domweb1.itso.ibm.com:8081
or
http://192.168.5.97:8081
3.6.3 Using the browser to configure a first server in domain
After connecting to the HTTP server with a Web browser, you can proceed to
configure the new server. You can quit the configuration at any time and
return later with your information preserved by clicking Save & Quit in the top
right of the screen. For more information about the choices you make, click
the Quick Help on the right side of the screen. As you go through the process
you will be presented with the following Web pages and asked to provide
required parameters and options. Table 6 summarizes the values we used for
the most significant parameters.
Table 6. First Server in Domain configuration parameter values
26
Parameter
Value
Domain name
Itsoweb
Certifier name (organization)
Itsoweb
Domino for S/390 and Web Server Integration
Parameter
Value
Server name
Domweb1
Server’s hostname
domweb1.itso.ibm.com
3.6.3.1 Creating a new Domino server
The first prompt allows you to select whether you are about to create the first
server or an additional server in the Domain.
In general, you select a First Server in Domain if you do not have Domino in
your organization, or if you need to create a new domain. Since we need to
create a new domain, we will select this option and proceed to the next step.
3.6.3.2 Server audience Web page
In this page you define who, besides Notes users, will be users of this server;
refer to Figure 2 on page 28. The page is structured into sections:
Standard services
This lists server tasks that are automatically configured on the Domino
server in the Standard services section. You cannot modify this section
because these tasks are essential for the server to function.
Additional services (Optional services for Domino servers)
If you want to use the calendar and scheduling features on this server, you
select both the Schedule Manager and the Calendar Connector options.
The Schedule Manager server task is responsible for creating the Free
Time database and handling free time lookups for users in the server. The
Calendar connector server task enables Domino to look up free time
information for a user on another server.
If you want to use event monitoring, select both the Event Manager and
Statistics options. This will enable the Event server task, which is
responsible for reporting report server errors and alarms, and the Report
task, which is responsible for collecting statistics about server activities
such as mail, available disk space and memory usage.
Domino server installation
27
Figure 2. Server audience Web page
Web Browsers section
If you want browsers such as Netscape Navigator to access data on the
server, select HTTP to install the HyperText Transfer Protocol (HTTP)
server task.
If you want Domino to handle client IIOP requests, select IIOP to install
the Domino Object Request Broker (ORB), which allows Domino objects
to respond to IIOP requests.
If you select HTTP, choose the primary activity for clients connecting to
this Domino server over HTTP. You can choose either Web Mail or Web
Applications, or both Web Mail and Applications.
If you wish to manually set the HTTP settings for this server, select
Advanced (Custom Settings). This selection sets the Domino HTTP
settings for optimal performance for the activities Web clients will perform
on the server.
Internet Mail packages section
If you want mail clients using Internet Message Access Protocol (IMAP)
and/or Post Office Protocol 3 (POP3) to access mail on the server, select
the option IMAP and/or POP3. These options will enable the
corresponding server tasks.
28
Domino for S/390 and Web Server Integration
If you selected IMAP or POP3, you also need to select SMTP if you want
to do mailing.
Internet directory services
If you want clients using Lightweight Directory Access Protocol (LDAP) to
access directory information on the server, select LDAP to install the
LDAP server task.
News readers
If you want news readers using Network News Transfer Protocol (NNTP)
to access news groups and discussions on the server, select NNTP to
install the NNTP server task.
Enterprise Connection Services
If you want to access data stored outside a Domino database, such as in a
relational database or enterprise resource planning system, click the
arrow and select DECS to install Domino Enterprise Connection Services.
Once you have made your selections on the Server Audience screen, press
the right arrow button located at the top of the Server Audience page. This
will take you to the next page, as shown in Figure 3 on page 30.
Domino server installation
29
Figure 3. Administration Settings Web page
3.6.3.3 Administration Settings Web page
In the Administration Settings page, do any or all of the following:
Organization identity section
Enter a domain name. This is the name of a brand-new Domino domain to
be created, to which the new server will belong. Other servers may be
added later on.
Enter a certifier name. This is the name of the organization certifier used
to stamp Notes ID files so that you can authenticate their identity.
Enter a country code for your certifier (optional).
Select whether to create a new certifier ID or use an existing one. If your
organization does not yet have a certifier ID, create a new one. If you
30
Domino for S/390 and Web Server Integration
select to use an existing certifier ID, enter the file name for the certifier ID
you want to use.
Enter a certifier password. The password must be at least eight
characters. (Lotus recommends using mixed-case passwords of at least
13 characters.) If you are performing Advanced Configuration and select
to use an existing certifier ID, you do not need to specify a password.
New server identity section
Enter a server name (for example, Domweb1). This is the name of the new
Domino server. Users and other servers access the server using this
name.
Enter a server hostname: this the fully qualified TCP/IP host domain name
(in our case, domweb1.itso.ibm.com).
Select whether to create a new server ID or use an existing one (in our
case, we want to a new server ID).
Administrators identity section
Enter a first name, middle initial (M.I.), and last name for the server
administrator.
Select whether to create an administrator ID or use an existing one (in our
case, we created a new one).
Enter the password for the administrator’s ID. The password must be at
least eight characters. (Lotus recommends using a mixed-case password
of at least 13 characters.)
Press the right arrow button to continue to the next page, which is Network
and Communication Settings.
3.6.3.4 Network and Communications Settings Web page
In the Network and Communication Settings section, do any or all of the
following:
1. In the Network Options section, select whether to use all available ports or
to select ports.
2. If you choose to select ports, do the following for each port:
• Choose a protocol by clicking the down arrow, selecting a protocol, and
clicking OK.
• Enter a network address.
• Click the down arrow and select to enable or disable the port.
3. No input is required in the Communications Port Options section.
Domino server installation
31
4. Verify that the server settings are correct and click Finish.
After you finish configuring the server, a Congratulations screen is displayed.
Notes prompts you to write down the server ID password, certifier ID
password, and administrator’s ID password. Be careful to keep these
passwords secure.
Clicking the EXIT button on the Congratulations window on the browser will
cause the HTTP Server task to shut down on the server, at which point the
configuration process is complete.
3.6.3.5 Setting up the Domino administrator client
Now you need to prepare a client workstation from which to administer the
newly created Domino domain.
• If you do not have a workstation with the Domino administrator client you
will have to set one up; during the course of the setup, the administrator ID
file will be retrieved from the corresponding person record in the Domino
directory in the server. This process requires you to have the server
started and operational.
• In our case, we had a workstation with the Notes clients installed. We had
to download the ID which is stapled to the Person document in the Domino
directory. There are two options to do so:
• Use FTP to download to the workstation names.nsf, the Domino
directory, taking care not to overwrite the local address book. Using the
Notes client, open the downloaded address book and detach the
user.id file from the administrator document. We suggest you rename
the file to a more meaningful name.
• Start the server, enabling the HTTP task. Then point a Web browser to
the server’s Domino directory by using the proper URL format. In our
case, it was the following:
http://domweb1.itso.ibm.com/names.nsf
Once in the Address Book page, navigate to People, select the
administrator document, and when it displays, click the attached
UserID. This will trigger a download process.
Note: Be sure to assign an appropriate name to the saved file;
otherwise you will end with an .html instead of an .id file extension.
Once the administrator ID file is in the workstation, you should be able to
access the server using the Domino administrator client. However, to register
users or additional servers, you also need to bring down cert.id, the
32
Domino for S/390 and Web Server Integration
Organization’s Certifier ID. This can be done using plain FTP in binary. Again,
think about renaming this file to a more descriptive name.
3.7 Preparing a dynamic LPA
At this point you need to place selected Domino binaries in LPA. This is done
to ensure a single in-storage copy of each binary is shared among processes.
If this was not done, each process would need to load its own copy of the
code.
1. Modify and submit the PUTINLPA job to relink the DLLs into the PDS/E
previously allocated by the ALOCPROD job. Check the results of the
PUTINLPA job to ensure that no errors have occurred.
2. After the re-link is complete, verify that the copied executables have their
sticky bit turned on. If the PUTINLPA job ran successfully, the sticky bits
should be on. To verify, login to the USS shell and issue the following
commands from /usr/lpp/lotus/notes/latest/os390:
ls -l libnotes
ls -l ftgtr
ls -l decsext
A t should be displayed in the last position of the file permission bits if the
sticky bit is turned on. If not, you can use the chmod command to turn it
on:
chmod o+t /usr/lpp/lotus/notes/latest/os390/libnotes
3. Copy the sample, MDFYPROG, into your existing or new
SYS1.PARMLIB(PROGxx) member. Ensure the PDS/E name specified in
PROGxx is consistent with the PDS/E name previously allocated by the
ALOCPROD job. Since it is not possible to activate dynamic LPA entries
from the PROG= statement in IEASYSxx (as you would for regular LPA),
you must add the following entry to SYS1.PARMLIB(COMMNDxx) to
activate the dynamic LPA at IPL time:
COM=’SET PROG=xx’
SYS1.PARMLIB(IEASYSxx) must point to COMMNDxx.
4. If you were using a previous release of Domino, remove the previous LPA
data set from the LPALSTxx PARMLIB member. You will have to perform
an IPL with CLPA (clear link pack area).
5. On the OS/390 console, issue SET PROG=xx to activate the dynamic
LPA.
Domino server installation
33
3.7.1 Starting the server
Now you are ready to start the Domino server and exercise some basic
functions by accessing it from the Lotus Notes Administration client. Refer to
Chapter 5, “Operating the Domino for IBM HTTP Server” on page 45 for
operational details.
34
Domino for S/390 and Web Server Integration
Chapter 4. Basic IBM HTTP Server installation
This chapter describes the setup of the IBM HTTP Server for OS/390 as a
single Web server to be used for the Domino connector. This server is
intended to run in normal mode only (no SSL encryption). Setting up a secure
server needs some extra steps, as described in Chapter 7, “Setting up a
secure Web server” on page 97.
You may configure the server using a Web browser and the remote
administration configuration method as described in Planning, Installing, and
Using, SC31-8690, or you may update the server configuration file using a
text editor. The manual Planning, Installing, and Using in the section titled
“Using the Configuration and Administration forms” describes the steps to
follow when using the remote server administration forms.
The following descriptions are based on the use of a text editor instead of the
remote server administration forms.
We assume that:
• OS/390 UNIX System Services is set up.
• TCP/IP is running.
• The code for IBM HTTP Server 5.1 for OS/390 has been SMP/E installed
as outlined in the Program Directory for OS/390 V2R7.0, GI10-4001. The
current version of this document can be found at:
http://www.s390.ibm.com:80/bookmgr-cgi/bookmgr.cmd/BOOKS/IEA1PD05/CCONT
ENTS
The SMP/E installation will place the code for IBM HTTP Server 5.1 for
OS/390 in the directory /usr/lpp/internet.
Our proposed “quick and proper” customization consists of the following
steps:
• 4.1, “Defining the Web server directory structure” on page 36
• 4.2, “Copying the Web server configuration files” on page 37
• 4.3, “Preparing the Web server configuration files” on page 37
• 4.4, “Defining the security environment” on page 41
• 4.5, “Defining the started procedure” on page 43
• 4.6, “Authorizing the started procedure to RACF” on page 44
• 4.7, “Creating a homepage” on page 44
• 4.8, “Starting the Web server” on page 44
© Copyright IBM Corp. 2000
35
4.1 Defining the Web server directory structure
We suggest you use a directory structure similar to the following outlined in
Figure 4.
/web/server1/pub
/images
/sec
/logs
/reports
/ocgi
/servlets
/rexx
/web/server2/pub
...
Figure 4. Suggested IBM HTTP Server directory structure
This directory structure should contain some separate Hierachical File
Systems (HFSs) which serve the following purpose:
/web
- root directory for Web servers
/web/server1
- working directory for server1
- small HFS
- contains all Web server configuration files
- directory for Web content (html etc.)
- extra HFS
......./images - directory for images used by Web content
.../pub
.../sec
- directory for security related files (certificates, group
files etc.)
.../logs
- contains all Web server logs
- extra HFS
.../reports
- contains all Web server reporting files
- extra HFS
.../ocgi
- directory for CGI programs
- extra HFS if needed
.../servlets
- directory for Java Servlets
- extra HFS if needed
.../rexx
- directory for GWAPI REXX
- extra HFS if needed
During the residency we defined /web/apple, /web/bean, /web/candy, and so
on. They may seem like funny names, but they allow for an easy identification
36
Domino for S/390 and Web Server Integration
of the Web servers. Each of these Web servers had its own start procedure
named WEBAPPLE, WEBBEAN, and so forth, as you will see later.
Why did we choose to use so many separate HFSs? The reasons are:
• We found separate HFSs more convenient to maintain.
• Once set up, several HFSs can be mounted READ ONLY for security
reasons if desired.
• At a minimum, the /logs, the /reports and the /pub directory should reside
in an extra HFS because of their unpredictable size.
Our reasons for choosing this particular directory structure were:
• In several projects at the ITSO, and with customers, we found this a good
general structure.
• At the ITSO Poughkeepsie, we run multiple Web servers concurrently and,
more often than not, on different software levels. The structure helps to
manage them easily and keep the configurations and configuration files
separate.
• Maintenance, which normally will overwrite files in /usr/lpp/internet, does
not affect the individual Web server configurations file, but the
maintenance becomes effective for all servers.
4.2 Copying the Web server configuration files
Copy the Web server configuration files into the individual Web server
working directory; that is, copy the files shown in Figure 5 from the
/usr/lpp/internet/samples/config to /web/server1, /web/server2, and so on.
httpd.conf
httpd.envvars
mvsds.conf
ics_pics.conf
javelin.conf
socks.conf
lgw_fcgi.conf
IMWSendMail.cfg
-
Web Server main configuration files
Web Server environment variables
MVSDS function config file
PICS Rating file
Web Traffic Express (Proxy) config file
another Proxy config file
Fast CGI config file
"old" SendMail config file
Figure 5. Web server configuration files
4.3 Preparing the Web server configuration files
Initially only two configuration files need to be changed:
Basic IBM HTTP Server installation
37
• httpd.conf
• httpd.envvars
Note that httpd.conf is the Web server main configuration file. The httpd.conf
configuration example is shown in Figure 6, and prepares for a globally
accessible Web server in accordance with our suggested structure. We
suggest that you never overwrite a parameter but rather repeat it on a new
line, comment out the original line, and change the repeated line. Only the
minimum changes necessary are shown:
------------------------- httpd.conf --------------------------------InstallPath /usr/lpp/internet
<-default
# ServerRoot server_root
ServerRoot /web/server1
<-default
<-changed
Port 80
<-default.
Change the Port directive if you like to run multiple
Web servers on the same IP address.
The port can also be defined with the -p parameter in
the Web server started procedure
# UserId %%CLIENT%%
UserId PUBLIC
<-default
<-changed to allow
"anonymous" without user
identification
# PidFile /usr/lpp/internet/server_root/httpd-pid <-default
PidFile /web/server1/httpd-pid
<-changed
# AccessLog /usr/lpp/internet/server_root/logs/httpd-log
# AgentLog /usr/lpp/internet/server_root/logs/agent-log
# RefererLog /usr/lpp/internet/server_root/logs/referer-log
# ErrorLog /usr/lpp/internet/server_root/logs/httpd-errors
# CgiErrorLog /usr/lpp/internet/server_root/logs/cgi-error
AccessLog
/web/server1/logs/httpd-log
AgentLog
/web/server1/logs/agent-log
RefererLog
/web/server1/logs/referer-log
ErrorLog
/web/server1/logs/httpd-errors
CgiErrorLog /web/server1/logs/cgi-error
# AccessLogArchive none
# ErrorLogArchive none
AccessLogArchive purge
ErrorLogArchive purge
38
Domino for S/390 and Web Server Integration
<-default
<-default
<-default
<-default
<-default
<-changed
<-changed
<-changed
<-changed
<-changed
<-default
<-default
<-changed
<-changed
Purge the logs on condition
Condition defined later.
# AccessLogExpire 0
# ErrorLogExpire 0
AccessLogExpire 10
ErrorLogExpire 10
<-default
<-default
<-changed
<-changed
Purge the logs on condition.
Keep the last 10 logs.
# AccessReportRoot /usr/lpp/internet/server_root/pub/reports <-default
AccessReportRoot /web/server1/reports
<-changed
# ReportDataArchive none
ReportDataArchive purge
<-default
<-changed
Purge the reports on condition.
Condition defined later.
# ReportDataExpire 0
ReportDataExpire 40
<-default
<-changed
Purge condition:
Keep the reports for 40 days
# LoggingReportingProgram /usr/lpp/internet/sbin/htlogrep
# LoggingReportingProgramOptions -c/etc/httpd.conf
LoggingReportingProgram /usr/lpp/internet/sbin/htlogrep
LoggingReportingProgramOptions -c/web/server1/httpd.conf
<-default
<-default
<-changed
<-changed
Enable
Reporting
Change the following 4 statements
Disable Web Traffic Express (special Proxy functions)
if not needed. Performance/Resource option
#
#
#
#
ServerInit /usr/lpp/internet/bin/Jav_dll.so:Javelin_init
Service
/cgi-bin/dogc.icapi /usr/lpp/internet/bin/Jav_dll.so:doGC
PreExit
/usr/lpp/internet/bin/Jav_dll.so:Javelin_preFilter
Enable ICSERRORLOG /usr/lpp/internet/bin/Jav_dll.so:Javelin_errorLog
<-- Change the following 6 lines. Disable CAServlet and
Servlet Express. This function has moved to WebSphere
Application Server.
# Service /*.jhtml
..cont. /usr/lpp/WebSphere/AppServer/lib/libadpter.so:AdapterService
# Service /*.shtml
..cont. /usr/lpp/WebSphere/AppServer/lib/libadpter.so:AdapterService
# Service /servlet/*
Basic IBM HTTP Server installation
39
..cont. /usr/lpp/WebSphere/AppServer/lib/libadpter.so:AdapterService
# Pass /CAServlet/*
..cont. /usr/lpp/internet/server_root/CAServlet/C/*
# Pass /ServletExpress/resources/*
..cont. /usr/lpp/internet/server_root/CAServlet/C/*
# Pass /ServletExpress/*
..cont. /usr/lpp/WebSphere/AppServer/web/*
....
Exec /Docs/admin-bin/* /usr/lpp/internet/server_root/admin-bin/*
Exec /my-cgi-bin/* /web/apple/ocgi/*
<-add
for your own CGIs
# Pass /reports/javelin/*
...
/usr/lpp/internet/server_root/pub/reports/javelin/* <-changed
Pass /reports/java/* /usr/lpp/internet/server_root/pub/reports/java/*
# Pass /reports/* /usr/lpp/internet/server_root/pub/reports/* <-default
Pass /reports/* web/server1/reports/*
<-changed
# *** ADD NEW PASS RULES HERE ***
# Pass /* /usr/lpp/internet/server_root/pub/*
<-default
Pass /Server/* /usr/lpp/internet/server_root/pub/* <-add
Pass /*
/web/server1/pub/*
<-add
CacheLocalFile /usr/lpp/internet/server_root/Admin/lgsplash.gif
CacheLocalFile /web/apple/pub/index.html
<-add
------------------------- httpd.conf --------------------------------Figure 6. httpd.conf preparation
Notes to Figure 6:
• The default setup and mapping rules define
/usr/lpp/internet/server_root/pub/Frntpage.html to be the primary
homepage.
• The changed setup and mapping rules define /web/server1/pub/index.html
to be the primary homepage.
• Frntpage.html (and with it the Remote Server Configuration Dialog) still
can be reached using URL:
http://servername/Server
• If you decide not to use the Remote Server Configuration Dialog, you may
comment out most of the mapping statements.
• You may keep the “original” Frntpage.html, but you should certainly cache
your homepage including all the images.
• Also consider caching other frequently accessed static pages and
consider using the FRCA cache.
40
Domino for S/390 and Web Server Integration
The next file to customize is httpd.envvars which is the Web server’s global
variable file. The httpd.envvars example shown in Figure 7 enables a
standard Web server.
PATH=/usr/lpp/internet/bin:/usr/lpp/internet/sbin:
-- cont --> /bin:.:/usr/sbin:/usr/lpp/ldap/bin
SHELL=/bin/sh
TZ=EST5EDT
LANG=C
LC_ALL=en_US.IBM-1047
NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lpp/internet/%L/%N:
-- cont --> /usr/lpp/ldap/lib/nls/msg/%L/%N
LIBPATH=/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/lpp/ldap/lib
STEPLIB=CURRENT
Figure 7. httpd.envvars preparation
4.4 Defining the security environment
IBM HTTP Server requires some setup regarding security (RACF). To enable
your standard Web server, the following steps are necessary:
• Create the Web server Administration ID (WEBADM) and its RACF Group.
• Create the Web server’s own user ID (WEBSRV).
• Permit WEBSRV to BPX.DAEMON and BPX.SERVER RACF FACILITY
classes (and make sure they are activated).
• Create the anonymous access user ID (PUBLIC) and its RACF group.
• Turn on program control.
Program control is not needed to prevent access to programs (in the
classical RACF sense) but it is used to indicate that these libraries are
authorized libraries.
Security experts may suggest using user IDs and groups other than the
published ones to make it more difficult for hackers. We suggest that you stay
with these names if this is your first installation. Switch them later when you
have gained a more complete understanding of all the dependent security
mechanisms (like PROTECT statements in httpd.conf, etc.).
Basic IBM HTTP Server installation
41
Figure 8 shows the RACF commands required for a particular Web server
called CANDY.
ADDGROUP IMWEB OMVS(GID(205))
ADDGROUP EXTERNAL OMVS(GID(999))
ADDUSER WEBADM DFLTGRP(IMWEB) OMVS(UID(206) HOME('/usr/lpp/internet')
...
PROGRAM('/bin/sh'))
ADDUSER WEBSRV DFLTGRP(IMWEB) OMVS(UID(0) HOME('/usr/lpp/internet')
...
PROGRAM('/bin/sh'))
ADDUSER PUBLIC DFLTGRP(EXTERNAL) OMVS(UID(998) HOME('/')
...
PROGRAM('/bin/sh'))
RDEFINE SURROGAT BPX.SERVER.WEBADM UACC(NONE)
RDEFINE SURROGAT BPX.SERVER.PUBLIB UACC(NONE)
PERMIT BPX.DAEMON CLASS(FACILITY) ID(WEBSRV) ACCESS(READ)
PERMIT BPX.SERVER CLASS(FACILITY) ID(WEBSRV) ACCESS(UPDATE)
PERMIT BPX.SRV.WEBADM CLASS(SURROGAT) ID(WEBSRV) ACCESS(READ)
PERMIT BPX.SRV.PUBLIC CLASS(SURROGAT) ID(WEBSRV) ACCESS(READ)
RALTER PROGRAM * ADDMEM('SYS1.SCEERUN'/'volser'/NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM('CBC.SCLBDLL'/'volser'/NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM('SYS1.LINKLIB'/'volser'/NOPADCHK) UACC(READ)
SETR RACLIST(FACILITY) REFRESH
SETR WHEN(PROGRAM) REFRESH
SETR CLASSACT(SURROGAT) if not already done
Figure 8. Web server security setup
42
Domino for S/390 and Web Server Integration
4.5 Defining the started procedure
The started procedure for the Web server needs to be set up. This is shown
in Figure 9.
//WEBCANDY PROC P1='-B',
// P2='-r /web/candy/httpd.conf',
// P3='-p 8100 -vv',
// LEPARM='ENVAR("_CEE_ENVFILE=/web/candy/httpd.envvars")'
//*-------------------------------------------------------//* -vv # VERY VERBOSE trace to stderr
//* -p nnnn # Port nnn (default 80)
//* -r /etc/httpd.imwebbox.icssec # RuleFile path/name
//*-------------------------------------------------------//WEBSRV EXEC PGM=IMWHTTPD,REGION=0K,TIME=NOLIMIT,
// PARM=('&LEPARM/&P1 &P2 &P3')
//SYSIN DD DUMMY
//OUTDSC DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSERR DD SYSOUT=*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
Figure 9. Web server started procedure setup
Note
Remember that the PARM field in JCL can be just 100 characters even if
the parameter input to the Web server is larger. See OS/390 e-business
Infrastructure: IBM HTTP Server 5.1 for OS/390 - Customization and
Usage, SG24-5603, for details on how to overcome this limitation.
Basic IBM HTTP Server installation
43
4.6 Authorizing the started procedure to RACF
Having defined the Started Procedure, you need to authorize it to RACF and
refresh the STARTED class. This shown in Figure 10.
RDEFINE STARTED WEBCANDY.** STDATA(USER(WEBSRV))
SETR RACLIST(STARTED) REFRESH
We called our Started Procedure WEBCANDY for the C(andy) Web server.
It's up to you to choose a suitable name.
Figure 10. Authorizing the Started Procedure
4.7 Creating a homepage
To begin with, create a small homepage in your directory for Web content
/web/server1/pub and call it index.html. Figure 11 shows a simple homepage
to get you started.
<html><head>
<title>HTTP 5.1 Project - The Candy Web Server on Port 8120</title>
<head><body bgcolor="FFFFFF">
<h1>Welcome to the CANDY Web server on port 8120</h1>
<p>
This is IBM HTTP Web Server V5.1.
<hr>
Follow this link to access the
<a href="/Server/">Remote Server Administration</a>.
</html>
Figure 11. A simple homepage
4.8 Starting the Web server
The Web server is now ready to start.
Starting, stopping and monitoring are described in Chapter 5, “Operating the
Domino for IBM HTTP Server” on page 45.
To use the Web server with the Domino for IBM HTTP Server connector, you
need to do some additional configuration steps as described in Chapter 2,
“Configuring the Domino for IBM HTTP Server” on page 5.
44
Domino for S/390 and Web Server Integration
Chapter 5. Operating the Domino for IBM HTTP Server
This chapter introduces you to the operation of the of Lotus Domino for IBM
HTTP Server, also known as the Web connector, which involves the operation
of both IBM HTTP and Domino/390 servers. The actual Domino for IBM HTTP
Server runs within the IBM HTTP Server process as a GWAPI plug-in. In
order to function properly, the corresponding Domino/390 server must be
started prior to bringing up the Domino for HTTP Server. Due to the way the
two servers interact, their startup and shutdown must be coordinated in the
proper sequence.
The following sections describe various methods for:
• Starting/stopping the servers
• Different ways to operate the servers
• Monitoring the status of the servers
• Coordinating the server start/stop sequence for the Web connector
• Dealing with abnormal terminations
We hope that the information in the following sections will provide you with
the basic understanding of how to operate the servers. Gaining day-to-day
experience with the servers will allow you to hone your operational skills, and
craft operational procedures appropriate for your shop.
Detailed information can be found in the Lotus publication Administering the
Domino System, Volumes 1 and 2, and in the redbook Lotus Domino for
OS/390 Release 5: Installation, Customization and Administration,
SG24-2083.
5.1 Starting Domino for OS/390
There are several ways to start the Domino/390 server:
• By using a dedicated telnet session
• By using DOMCON (Domino Console Interface package)
• By using notes.rc (a script which executes Domino in the background)
This section discusses the two most common ways to start the Domino
server: telnet session and DOMCON. Starting the server from a telnet
session is useful for post-installation testing and debugging. DOMCON can
be easily integrated with OS/390 system operations, and is recommended for
running in production mode.
© Copyright IBM Corp. 2000
45
The third method, notes.rc, is a UNIX script which starts Domino as a
background process. You then communicate with Domino using the UNIX
comcon command. A UNIX systems programmer could configure notes.rc to
control multiple servers, but this would take considerable effort, and would be
hard to troubleshoot. Therefore we limit our discussion to the first two
methods.
5.1.1
User ID considerations for starting the Domino server
The server should be started with the OS/390 user ID which was associated
with the server during the server setup process. The Domino server
processes run in a set of OS/390 address spaces. These address spaces are
named with the server user ID plus a number (for example, for a server with a
user ID of DOMINO, address spaces are named DOMINO1, DOMINO2...
DOMINOn).
Whichever method is used to start the server, that server user ID must be
assigned a UNIX UID which has read/write access to the objects in the
server's notesdata directory. This user ID must also have write authority to
the /tmp directory.
The user ID associated with each server owns the /notesdata directory and
files, shared memory segments, message queues, and semaphores. For
these reasons, different Domino servers should be run under unique user
IDs. This allows you to identify which address spaces belong to which server.
It also allows each server to access and clean up its own resources at
termination.
Also important to note is that you cannot start two instances of the same
Domino server.
Warning
Never start a Domino server under an ID with superuser authority(uid=0).
Stopping a server whose UID=0 can be disastrous to your system, as it will
bring down kernel processes!
If a server ends abnormally, it may fail to clean up its interprocess
communication shared resources. Therefore you cannot restart a server until
you have checked for and cleaned up hung processes and stranded IPC
resources. The use of DOMCON prevents this situation from happening,
46
Domino for S/390 and Web Server Integration
because it enforces termination cleanup and startup verification that there are
no server-owned shared resources in existence.
In some circumstances, it will be of value to remove the layer added by
DOMCON and start a server from telnet to help debug a problem situation.
For this to be of value, it is important that the UNIX environment for the server
under telnet and under DOMCON are identical. Special care must be taken to
keep the server's .profile and the DOMCON domino_global_env
synchronized.
5.1.2 Starting the server with Telnet
To start the server:
1. Rlogin or telnet into OS/390 UNIX with the user ID that owns the server.
Note that operating the Domino server from the OMVS shell is not
supported.
Caution
Make sure that this user ID is not UID 0!
2. Change to the proper notesdata directory:
cd /notesdata1
(server’s notesdata)
3. To issue the server startup command, type:
/usr/lpp/lotus/bin/server
The terminal will then become a dedicated server console. Details of the
startup process will be logged to it. In general, the server is considered to
have started when the Database Server Started message appears on the
console, at which point clients should be able to connect to the server.
As soon as the server start command is issued from one of these sessions
and the server begins execution, the session becomes part of the server's
console, and can be used to monitor the server, issue server commands, and
eventually shut down the server. If the telnet session is lost or closed, the
Domino server continues to run. You cannot reconnect the server console
directly, but you can operate the server and browse its log even when the
telnet console has been lost by using the following:
• The console utility (available with Domino R5 for UNIX platforms)
• The comcon command
Operating the Domino for IBM HTTP Server
47
Even with these options, in our opinion, running a Domino server from a
telnet or rlogin session should be limited to test or debugging. We suggest the
use of DOMCON as more appropriate for a typical OS/390 operating
environment.
5.1.3 DOMCON
In the OS/390 environment, the system tasks are operated from the OS/390
system console, and that is precisely what the DOMCON 3.1 package allows
you to do with Domino. DOMCON monitors the Domino server. It intercepts
Domino console output, reroutes it, and displays it on the OS/390 system
console. DOMCON also provides the ability to start, stop and send
commands to Domino from the OS/390 console. The use of the OS/390
console has the advantage of built-in console recovery support, automatically
switching to alternate consoles in the event a console becomes
disconnected. Typically, OS/390 consoles are secured from unauthorized
access. In addition, OS/390 functions such as SDSF and TSO console facility
make the OS/390 console access available from any authorized terminal/user
ID.
The current level of the package, DOMCON 3.1, is available for download
from an IBM Web site at URL:
http://www.s390.ibm.com/products/domino/domcon/dmcnmain.html
The DOMCON package comes as part of a Notes discussion database that
can be accessed on the Web from your browser. You may view and post
questions to this database from your browser. You can also access this
database by using the URL:
http://www.support.lotus.com/domcon.nsf
Note:
We successfully tested the DOMCON V3 package during our residency
project and found that a customer should strongly consider using it for their
Domino operations, although it was not officially supported at that time.
IBM intends to provide this support in a future release of Domino on S/390.
5.1.3.1 DOMCON procedures
DOMCON provides three system procedures (started tasks):
• DOMINS - Starts the Domino server
• DOMINC - Issues commands to Domino server
• DOMINK - Shuts down the Domino server
48
Domino for S/390 and Web Server Integration
Note: This is only a partial list of functions provided by DOMCON Version 3.1.
For detailed, version-dependent information, refer to documentation at the
DOMCOM Web site:
http://www.s390.ibm.com/products/domino/domcon/dmcnmain.html
Through the use of these procedures, Domcon provides:
• An automated and synchronized way to start the Domino for OS/390
server with other resources at system IPL time.
• Management of all Domino partitioned servers on the OS/390 image from
the same console.
• Remote access with SDSF/console functions with appropriate controls.
• The ability for operations to send server commands to the Domino for
OS/390 server from the console.
• Operations with the capability of performing an orderly shutdown of the
Domino for OS/390 server during OS/390 shutdown.
• An interface to automation systems that can start, stop, or send
commands to the server in response to error situations.
• Synchronized OS/390 resource utilization. Signals the Domino for OS/390
server to start replications at the completion of the batch processing (may
be variable on end-of-month/week).
• Verifies that DOMINO has been assigned the required address space size
(AS) of 2 GB and unlimited CPU time.
• A RACF-protected data set to store Domino passwords (server.id) and the
ability to automatically feed them into the server's input stream at startup.
• The ability to set unique environment variables on a server-by-server
basis.
• Automated startups with secure server.id files.
• An interface from UNIX System Services which allows selected users to
send commands to selected Domino servers and see the responses.
RACF Surrogate authority is used to control which users can access which
servers.
• Ability to establish filters that limit which messages are routed from the
Domino servers to the OS/390 operator console.
• The Domino USS address spaces created by DOMCON will not inherit the
parent limits (AS size, time, and others), but instead will be stamped with
the values corresponding to the system’s BPXPRMxx settings.
Operating the Domino for IBM HTTP Server
49
• Optionally synchronizes the starting and stopping of a companion IBM
HTTP Server for a Web connector configuration.
5.1.3.2 Starting the Domino server with DOMCON
With DOMCON, the Domino for OS/390 server is started by submitting the
DOMINS proc with the following OS/390 console command:
S DOMINS,SRVID='DOMINO1',BYPASS='N',TYPE='N'
The options may be entered in any order and, depending on the effect
desired, some of the options can be allowed to default. Defaults are set in the
domino_global_env file. If you are only running one server, you can set it up
as the default in domino_global_env2 and then simply start DOMINS:
S DOMINS
The following commands will start the Domino for OS/390 server associated
with the SAF (RACF) user ID DOMINO2 and bypass the IPCS semaphore
checking. This can be used to start Domino after an abend.
S DOMINS,SRVID='DOMINO2',BYPASS='y'
S DOMINS,BYPASS='y',SRVID='DOMINO2'
Here is a description of DOMCON startup parameters:
SRVID:
The value assigned to this keyword determines which partitioned
Domino server to start. The server name specified must match the
SAF (RACF) user ID corresponding to the server to be started,
with a relationship to its notesdata defined in the DOMCON
domino_global_env file. (The domino_global_environment file
contains configuration values for DOMCON.)
If SRVID is omitted, DOMCON uses the default server specified in
domino_global_env. This value is case-sensitive and must be
entered in uppercase.
BYPASS: The value assigned to this keyword indicates if DOMCON should
ignore the error condition of IPCS semaphore resources still
associated with the Domino for OS/390 SAF user ID. The start
option validates that no process, IPCS memory, or IPCS
semaphore exist. If they do, this is an indication that the Domino
for OS/390 server may still be running. It is possible that the kill
process will not be able to remove some remaining IPCS
semaphores. By specifying y on BYPASS, you can tell DOMCON
to start the Domino for OS/390 server even if IPCS semaphore
resources are still present. By default, or by using n, the normal
verification process will take place.
50
Domino for S/390 and Web Server Integration
TYPE:
This option tells DOMCON how to invoke the startup process. The
possible values are N/S/R.
N
This is the default and indicates a normal start. It causes
DOMCON to start the Domino server and then start the monitor
processes. This functions just like the 2.2 release and previous
release did.
S
This causes the monitor process to only stay active until the
Domino sever has started. Once the server is started, the monitor
session will self-terminate and no more messages will be routed to
the console. The server started status is detected by scanning for
a particular string all the messages routed to the console. The
domcon_srv_startup environment variable in domino_global_env
determines what string to search for and XXXXXX_start_srv_sleep
indicates how long before a time-out condition is detected. If the
search string has not been found before the time out, DOMCON
issues an error to the console and then terminates the monitor.
If this condition occurs, the operator should be responsible for
validating the health of the server, which should be in question since
the expected started-status string was never received from the
server.
R
This indicates that this invocation should only restart the monitor
process and not the actual server.
When DOMINS is started it performs the following functions:
1. Validates and sets the debug level to be used
2. Parses and validates options passed
3. Sets up the global environment
4. Determines which Domino partition to start based upon the RACF user ID
5. Changes the address space name to match any alias
6. Switches to the correct user ID for address space
7. Reset the address space settings to match your BPXPRMxx
8. Validates if resources exist for the RACF user ID
9. Defines/renames Domino for OS/390 stdin and stdout files
10.Starts the Domino for OS/390 server in the background
11.Starts the monitor process in the background
12.Optionally starts the companion IBM HTTP Server
Operating the Domino for IBM HTTP Server
51
13.Terminates
Earlier, we mentioned that using DOMCON is the best way to integrate the
operation of the Domino server with the general OS/390 system production
operation. It is suggested that DOMCON not be used until it has been proven
that the server works without problems from a telnet session; otherwise it can
be hard to determine whether a failure is due to Domino itself or to the
DOMCON setup.
5.2 Stopping Domino for OS/390
Once the server is up and running, the options to stop the server depend on
the way it was started. We will cover only stopping the server from the telnet
session and with DOMCON. To learn more about the other options, refer to
Lotus Domino for OS/390 Release 5: Installation, Customization and
Administration, SG24-2083.
5.2.1 Stopping Domino from the telnet or rlogin session
When the server has been started from a telnet or rlogin session, this session
becomes the Domino server console. To stop the server from the server
console, enter either exit, quit, or simply q. Any of these commands will
initiate an orderly server shutdown process.
5.2.2 Stopping Domino with DOMCON
To terminate a Domino for OS/390 server, use the DOMINK procedure. It can
be issued with the following options:
S DOMINK,SRVID=’DOMINO1’,FORCE=’N’,TYPE=’N’
To shut down the default server, as defined by the settings in the
domino_global_env, you can simply enter:
S DOMINK
Even if Domino was started via telnet, it is useful to be able to stop it with
DOMCON. It can be used to shut down Domino if the telnet session were to
be lost. During our testing, we successfully used the DOMINK proc for the
shutdown and cleanup of a hung server by using the following commands:
S DOMINK,SRVID='DOMINO1',FORCE='Y',TYPE='Q'
Here is a list of the DOMINK options which can be entered in any order:
SRVID:
52
This parameter value tells DOMCON which partitioned Domino for
OS/390 server to shut down. The server name specified must
Domino for S/390 and Web Server Integration
match the SAF(RACF) user ID used to start the server. If no
SRVID is specified, DOMCON uses the default server specified in
domino_global_env. This value is case-sensitive and must be
entered in uppercase.
FORCE:
This parameter tells DOMCON to bring the server down and purge
all resources while ignoring errors. It is possible an error condition
(input log destroyed/damaged) could be detected by DOMCON.
Under normal execution, DOMCON will terminate the shutdown
processes. By specifying y on the FORCE option, DOMCON will
continue the shutdown process and purge resources (sigterm,
sigkill, ipcs remove) even if errors are detected.
TYPE:
This parameter tells DOMCON how the shutdown request is to be
processed.
N
This is a normal shutdown, the default. It causes the quit
command to be sent to the Domino server and then waits for the
server to shut down (or time out), at which point any leftover
resources are cleaned up.
M
This is to shut down the monitor processes only. The Domino
server is left running.
Q
This is used for a quick shutdown. This allows you to have
DOMCON go immediately to the clean-up section of the shutdown
process. For example, you have 5 minutes (300 seconds) defined
as the wait time before a shutdown times out and one of your
servers has failed. If you do not specify TYPE=’Q’, then the
DOMINK request will wait for 5 minutes before cleaning up the
address spaces and IPCS resources. By specifying TYPE=’Q’, the
5-minute interval is skipped.
When DOMINK is started, it performs the following functions:
1. Optionally issues a stop command for the companion IBM HTTP Server
2. Validates and sets the debug level to be used
3. Parses and validates the options that are passed
4. Sets up the global environment
5. Determines which Domino partition to start based upon the RACF user ID
6. Switches to the correct user ID for address space
7. Validates the environment to be used during shutdown
8. Issues commands to the Domino for OS/390 server to have it terminate
9. Waits for Domino for OS/390 to terminate
Operating the Domino for IBM HTTP Server
53
10.Finds any processes still associated with the Domino for OS/390 RACF
user ID and issues a SIGTERM to them
11. Waits for SIGTERM to process
12. Finds any IPCS memory resources and releases them
13. Finds any IPCS semaphore resources and releases them
14. Terminates
When the Server shutdown complete message appears on the OS/390
operator’s console, your Domino server has been terminated.
5.3 Operating the Domino server
The Domino server on OS/390 can be operated from a number of different
user interfaces, including:
• rlogin or telnet
• Domino Administration Client
• Domino Web Administrator Client
• OS/390 console using DOMCON
• comcon interface
• cconsole interface
In general, these options provide somewhat different functionality. For
example, a telnet session can start the Domino server and, once started, it
can become the server console, from which you can issue server commands
and eventually shut it down. Another option, the administration client, is a
powerful interface which, as part of the functionality, includes a remote server
console from which you can operate the server.
In our project, while testing the 5.01 Domino code, we used the Domino
administration client, telnet and DOMCON. These three options are
discussed in this chapter. Refer to Lotus Domino for OS/390 Release 5:
Installation, Customization and Administration, SG24-2083, for an in-depth
look at the possible ways to operate the Domino server. For Domino server
commands, you can also refer to the Domino Administration Guide at URL:
http:/notes/net/notesua.nsf
54
Domino for S/390 and Web Server Integration
5.3.1 Operating the server from Telnet
As described in 5.1.2, “Starting the server with Telnet” on page 47, you can
start the server from a workstation telnet or rlogin session to the OS/390
UNIX host. As soon as the server start command is issued, and the server
begins execution, the session becomes the server's console, and can be
used to issue server commands and monitor the server, as well as shut it
down.
5.3.2 Domino administration client
Lotus Domino Release 5 provides a specific administration client called the
Domino Administrator. The administration client can be selected during setup
of your Notes client, or can be installed separately.
To be able to use the administrator functions, ensure you are using an ID
which has administrator rights to the server. For example, we used the
administrator ID created at first server install time. If needed, you could also
authorize other IDs to operate and administer the Domino server.
This application is the main interface for any Domino-related administration
task. The Administrator allows you to perform Domino server commands and
monitor the server from your workstation. You can initiate server shutdown,
but obviously, you cannot start a server because the client cannot interact
with OS/390 to request server startup.
In addition, since the server console log is written to the log.nsf database on
the server, a Notes Client with the proper access can read and analyze it.
5.3.3 Web administrator client
Since Domino R4.6, there is a Web administrator client interface that allows a
user with the proper access authority to perform server administration
functions. Domino R5 has enriched the options available through this
interface.
To find more information about the Domino administration client and Web
administrator client, as well as Domino server commands, refer to
Administering the Domino System, Volumes 1 and 2 and Lotus Domino for
OS/390 Release 5: Installation, Customization and Administration,
SG24-2083.
5.3.4 Operating the server with DOMCON
As detailed in 5.1.3.2, “Starting the Domino server with DOMCON” on page
50, you can start the server from the OS/390 console with proc DOMINS.
Operating the Domino for IBM HTTP Server
55
5.2.2, “Stopping Domino with DOMCON” on page 52 describes how you can
stop the server from OS/390 console with proc DOMINK. An additional proc,
DOMINC, allows you to issue commands to the servers. These procedures
can be integrated with system automation.
5.3.5 Recommendations for Domino operation
Based on the previously discussed options we recommend the following:
• For post-installation verification, such as newly installed server startup,
use rlogin or telnet.
• For a production environment, start the server with DOMCON from the
OS/390 operator console. Once started, the server can be administered
from the Notes administration client or Web administrator client.
• When you run into problems, or for testing, start Domino from a telnet or
rlogin session for problem determination. As in indicated in 5.1.1, “User ID
considerations for starting the Domino server” on page 46, it is important
that the server environment under telnet and under DOMCON is identical.
• Use DOMCON DOMINK proc to force shutdown/cleanup after abend.
• The Domino administrator should become proficient in using the remote
console of the Domino administration client to monitor and operate the
server.
5.4 Monitoring the status of the Domino server
The most straightforward way to determine the status of a server is to issue
the appropriate server console commands. It is not the objective of this
section to teach server operation, but only to give some tips that may be
helpful. Again, the options will depend on how the server was started.
5.4.1 Issuing server commands from a telnet/rlogin session
In this case, just issue the desired command in response to the console
prompt(>); for example, to display server status:
sh server
5.4.2 Issuing server commands with DOMCON
For this you can use the DOMINC procedure, which has a very similar format
to the previously discussed DOMCON procedures. For example, to issue the
show server command to the DOMINO2 server, type:
S DOMINC,SRVID=DOMINO2,CMD="sh server"
56
Domino for S/390 and Web Server Integration
5.4.3 Valuable OS/390 console commands
A skilled console operator can help you to display information related to the
server that will be of value to you. In case you are unfamiliar with the
necessary commands, we list several of them here.
The MVS command D A,L shows all of the active address spaces. The
address spaces of the Domino server are prefixed with the user ID which
started the Notes server.
To display the UNIX processes related to a specific UNIX ID (for example the
ones related to the server started under DOMINO1), you can issue the
following command:
D OMVS,U=DOMINO1
To display all existing UNIX processes, you would issue:
OMVS,A=ALL
5.4.4 UNIX System Services environment
UNIX is known for its rich command set, but it is virtually impossible to cover
it all here. Instead, we will describe a few of these commands.
To display information about UNIX processes, issue:
ps -ef
You can also check if the Domino tasks are listening on their individual
TCP/IP ports by using the onetstat command. If you have multiple stacks
running you can specify a stack with the -p option.
The standard output of the onetstat command shows the status of all TCP/IP
socket connections. To see if the Domino server actually communicates over
the TCP/IP stack, use the -b options, which show the number of bytes
transferred through the socket connections:
onetstat -p TCPIPOE
onetstat -b -p tcpipoe
5.5 Coordinating server start/stop sequence for the Web connector
The proper sequence for operating the Domino for HTTP Server is as follows:
Startup:
1. Start the Domino server.
Operating the Domino for IBM HTTP Server
57
2. Start the associated IBM HTTP server.
You should now be able to access Domino databases from a Web
browser.
Shutdown:
1. Stop the IBM HTTP server.
2. Stop the Domino server.
Warning
If Domino abends, you must bring down the associated IBM HTTP
Server prior to restarting Domino.
Restart:
1. Use the MVS D A,L command and the UNIX ipcs -bo command to
confirm that all Domino and HTTP processes/shared resources are
gone for that Domino server.
2. If there are leftover processes, use cleanup procedures as detailed in
5.6, “Dealing with abnormal terminations” on page 58
3. Start the Domino server.
4. Start the IBM HTTP Server.
5.5.1 Coordinating a start/stop sequence with DOMCON
DOMCON Version 3.1 provides the option to synchronize the start/stop
sequence of both servers, Domino and IBM HTTP server. This is controlled
by variable DOMINO_390WAS in the domino_global_environment.
By specifying this option, DOMCON will issue a Start (S) on the operator’s
console 30 seconds after the Domino Server is started. Also, DOMCON will
issue a Pause (P) at server shutdown. The environment variable should be
set to the procname of the Web Server that has the Web Connector enabled
on it.
5.6 Dealing with abnormal terminations
If the Domino server crashes or for whatever reason hangs during shutdown,
you may encounter problems in subsequent attempts to re-start the same
server. Most likely, this will be due to existing interprocess communication
resources, such as shared memory and semaphores, that had been allocated
by the previous server instance but never released due to the abnormal
58
Domino for S/390 and Web Server Integration
termination. It is important to understand that the shared memory is retained
even if you cancel the Domino server address spaces.
Therefore it is a requirement to have a procedure in place to clean up leftover
resources before a new server instance can be started. DOMINS has a
startup validation that checks for existing resources. Note that these
resources could very well be tied to a healthy active server, and not the result
of a failed one. In that case, it would be incorrect to start a duplicate instance
of the same server.
If you find a situation where you need to clean up after an abnormal server
termination, the following sections list some options.
5.6.1 Attempt to force a shut down of the server
If at all possible, try to issue a termination command:
• For telnet-started servers, if the console service is still operational, you
can type:
exit or quit and press ENTER
If not, if the telnet session seems to be healthy, you can proceed with the
clean up. Otherwise, the telnet session itself will have to be subject to the
clean up.
• For DOMCON-started servers, from the system console you should issue
a DOMINK command for the server. It will attempt an orderly shutdown
and then clean up.
S DOMINK,SRVID=’DOMINO2’
5.6.2 Forced cleanup with DOMINK
No matter how the server was started, you can always issue a DOMINK
command for the server. If you know the server is dead or unresponsive, you
can bypass the wait and have it go into forced cleanup:
S DOMINK,SRVID=’DOMINO2’,FORCE=’Y’,TYPE=Q
5.6.3 Forced cleanup with nsd.sh
You can use nsd.sh to clean up leftover processes and resources related with
a server. You must do so from a UNIX System Services session, normally
telnet. You have two options:
• From a telnet session with login under the server ID, you can issue the
following command:
cd /notesdata1
(server’s notesdata)
Operating the Domino for IBM HTTP Server
59
/usr/lpp/lotus/bin/tools/diag/nsd.sh -kill
• From a telnet session with login under an ID that has superuser authority,
you can issue the following command:
cd /notesdata1
(server’s notesdata)
/usr/lpp/lotus/bin/tools/diag/nsd.sh -kill -user domino_userid
Beware that if you issue this command as superuser (UID=0) with no
options appended, the effects can be disastrous, since it will attempt to
clean up all resources and processes associated with UID=0.
Warning
Be sure that you use the -user operand with the ID corresponding to
the server to clean up. Otherwise, the power of the superuser
authority can cause havoc by destroying resources and processes.
5.6.4 Explicit kill of Domino processes
If needed, you can explicitly kill the processes associated with a server:
• First you need to determine which processes are active.
• From SDSF or the MVS system console, you can use any of the
following commands to find the processes:
D A,L
D OMVS,A=ALL
D OMVS,U=DOMINO1
(or your server’s user ID)
• From the shell, under the server ID or superuser:
ps -ef
| grep ‘DOMINO1’
(or your server’s user ID)
• If any server processes are listed, you can proceed to kill the processes
explicitly from the system console by one of the following means:
• Determine the parent process ID (PPID) of the lowest numbered server
process (for example, DOMINO11 of all DOMINO1n processes). Then
issue, on the system console:
F BPXOINIT,FORCE=PID#
where PID# is the parent number for Domino processes.
• From the UNIX shell you can issue:
kill -s SIGKILL pid
(same as kill -9 pid)
where pid is the process ID number.
60
Domino for S/390 and Web Server Integration
• Issue plain cancel commands from the console for each of the Domino
processes:
C DOMINO11
C DOMINO12
C DOMINO1n
You will have to provide the ASID value if there are duplicate names:
C DOMINO13,A=00nn
C DOMINO13
(nn is the hex ASID number)
• As a last resort, you can force the address spaces to remove them:
FORCE DOMINO1,A=00nn,ARM
(nn is the hex ASID number)
5.6.5 Explicit release of Domino resources
If needed, it is possible to explicitly release any interprocess communication
resources associated with the failed Domino server. To do so, you have to be
able to list the resources first. From the shell, under the server ID, issue an
ipcs -a command as shown in Figure 12.
> ipcs -a
Message Queues:
T
q
q
q
ID
KEY
MODE
OWNER
10 0x01016417 ----------- IBMUSER
131087 0x01016d52 ----------- IBMUSER
16 0x01016d94 ----------- IBMUSER
GROUP
IMWEB
IMWEB
LOTUSGRP
CREATOR
IBMUSER
IBMUSER
IBMUSER
CGROUP
CB
IMWEB
0
IMWEB
0
LOTUSGRP 0
Shared Memory:
T
ID
KEY
MODE
m
433221 0xf8138802 --rw-rw---m
1023050 0xf80ba002 --rw-rw---m
1023051 0xf80ba001 --rw-rw----
OWNER
DOMINO1
DOMINI2
DOMINI2
GROUP
LOTUSGRP
LOTUSGRP
LOTUSGRP
CREATOR
DOMINO1
DOMINI2
DOMINI2
CGROUP
NATTCH
LOTUSGRP
LOTUSGRP
LOTUSGRP
Semaphores:
T
ID
s
1723948
s
1461805
s
609840
s
609841
s
740914
OWNER
DOMINI1
DOMINI1
DOMINO2
DOMINO2
DOMINI2
GROUP
LOTUSGRP
LOTUSGRP
LOTUSGRP
LOTUSGRP
LOTUSGRP
CREATOR
DOMINI2
DOMINI2
DOMINO2
DOMINO2
IBMUSER
CGROUP NATTCH
LOTUSGRP 16
LOTUSGRP 16
LOTUSGRP 16
LOTUSGRP 16
LOTUSGRP 16
KEY
0xf80ba003
0xf80ba004
0xf8138a70
0xf8138807
0xf80ba270
MODE
--ra-ra-----ra-ra-----ra-ra-----ra-ra-----ra-ra----
Figure 12. Listing interprocess communication resources
Use the ipcs -a shell command to verify that all interprocess communication
(IPC) resources are removed. IPC resources are not automatically released
when a process terminates.
Operating the Domino for IBM HTTP Server
61
The output shown in Figure 12 is from the ipcs -a shell command after a failed
attempted to start a Domino server. The left-most column indicates resource
type:
q = message queue
m = shared memory segment
s = semaphore
The next two columns are the ID and key. You can remove resources based
on either the ID or key number.
Notice that in the display above, there are mixed resources owned by two
different Domino server user IDs: DOMINO1 and DOMINO2. To display only
those resources of a certain type, and display the owner’s process ID, you
can use:
ipcs -pm
ipcs -pq
ipcs -ps
(show shared memory)
(show queues)
(show semaphores)
This is the output from the ipcs -pm command:
> ipcs -pm
Shared Memory:
T
ID
KEY
m
433221 0xf8138802
m
1088585 0xf80ba000
m
1023050 0xf80ba002
m
1023051 0xf80ba001
m
1547340 0xf8138800
m
367698 0xf8138801
MODE
--rw-rw-----rw-rw-----rw-rw-----rw-rw-----rw-rw-----rw-rw----
OWNER
DOMINO1
DOMINO2
DOMINO2
DOMINO2
DOMINO1
DOMINO1
GROUP
LOTUSGRP
LOTUSGRP
LOTUSGRP
LOTUSGRP
LOTUSGRP
LOTUSGRP
CPID
352321566
117440536
117440536
117440536
1845493809
1845493809
LPID
704643129
1224736819
1224736819
1224736819
704643129
704643129
In the display above, the CPID column shows the owning process ID number.
The commands to remove IPC resources are:
ipcrm -m SharedMemoryID
ipcrm -q QueueID
ipcrm -s SemaphoreID
ipcrm -M SharedMemoryKey
ipcrm -Q QueueKey
ipcrm -S SemaphoreKey
Once you have removed the resources you can verify that they were all
released by again using the ipcs -a command.
62
Domino for S/390 and Web Server Integration
5.7 Starting the IBM HTTP Server
The most common way to run your server is to define a procedure in your
system PROCLIB data set and start it from the operator console, as shown in
Figure 13.
S WEBBEAN
$HASP100 WEBBEAN ON STCINRDR
IEF695I START WEBBEAN WITH JOBNAME WEBBEAN IS ASSIGNED TO USER
WEBSRV , GROUP IMWEB
$HASP373 WEBBEAN STARTED
IMW3534I PID: 637534259 SERVER STARTING
IMW3536I SA 637534259 0.0.0.0:8110 * * READY
Figure 13. Starting the IBM HTTP Server from the OS/390 console
Notice that message IMW3536I identifies the server as a standalone server
(SA). The fields with asterisks in the message are used to display
WLM-related information.
A sample procedure called IMWEBSRV is shipped with the IBM HTTP Server
in SYS1.SAMPLIB. The procedure needs to run under the authority of the
RACF user ID that you have defined to run the Web server.
5.7.1 Stopping the IBM HTTP Server
Use the OS/390 STOP command to bring down your server instead of
cancelling the address space with the OS/390 CANCEL command.
Cancelling a standalone server might cause you to lose valuable trace and
logging data since this data is buffered before being written by a logging
thread. Figure 14 shows a normal stop of the IBM HTTP Server, which
causes a SIGTERM signal to be sent to the server.
P WEBBEAN
IMW3540I SA 654311475 0.0.0.0:8110 * * STOPPING WORK
IMW3541I SA 654311475 0.0.0.0:8110 * * TERMINATING NOW
$HASP395 WEBBEAN ENDED
Figure 14. Stopping the IBM HTTP Server from the OS/390 console
Note: If your server is busy, and depending on what work needs to be
stopped, in some cases it might take up to several minutes before you see
the message:
IMW3541I SA 654311475 0.0.0.0:8110 * * TERMINATING NOW
Operating the Domino for IBM HTTP Server
63
You may see this if you are using persistent connections. The PersistTimeout
parameter specifies the length of time to wait before closing a TCP/IP
connection. The IBM HTTP Server does not shut down until this period has
expired.
5.7.2 Controlling the IBM HTTP Server
The IBM HTTP Server accepts a set of OS/390 MODIFY commands that
allow you to make changes while the server is running. For example, you can
use this facility to display statistics about your server, control the level of
tracing, turn SMF recording on and off, turn debugging on and off for specific
IBM HTTP Server modules, and restart your server. Figure 15 on page 64
shows the use of the MODIFY command to display configuration information,
display server statistics, and turn very verbose tracing on.
F WEBBEAN,APPL=-D CONFIG -D STATS -VV
IMW3518I More trace enabled. (Very Verbose)
IMW3501I Config: Hostname: wtsc59oe.itso.ibm.com, Port: 8110, SSL 702
Port: 443, Server root: /usr/lpp/internet/web/bean.
Tracing: workthread, threadpool, dirbrw, http, html, format, bag,
hash, groups, ruledb, log, error, request, timers, rules, status,
pics, dns, proxy, proxycache, gc, time, lex, workqueue, tcp, ftp,
javelinbase, javelincfg, javelinpics, nls, mempool, proxylock, icapi,
cgi, ssi, connections, wbi, if, stringlib, selftest, gopher, fastcgi,
resphdrs, mpool, frca, proxygroup, javelin.
SMF recording is currently disabled.
IMW3502I Stats: Threads running: 40, Threads idle: 40, Requests: 11,
703
Bytes rcvd: 3965, Bytes sent: 22243, Actv In Conns: 0, Actv Out
Conns: 0.
Figure 15. Use of the OS/390 MODIFY command to display server information
Figure 16 shows the use of the MODIFY command to restart the server. A
SIGHUP signal is sent to the running server which causes the server process
to reload its configuration file. All client requests are disrupted until the restart
process completes.
F WEBBEAN,APPL=-RESTART
IMW3537I SA 637534259 0.0.0.0:8110 * * RESTARTING
IMW3538I SA 637534259 0.0.0.0:8110 * * RESTART SUCCESSFUL
Figure 16. Use of the OS/390 MODIFY command to restart the IBM HTTP Server
64
Domino for S/390 and Web Server Integration
For detailed information on the MODIFY command options available for
controlling the IBM HTTP Server, refer to the chapter “Managing your Web
server” in IBM HTTP Server for OS/390 Release 7, Planning, Installing, and
Using, Version 5.1, SC31-8690.
Other MODIFY commands are described in Table 7 on page 76.
Note: Equivalent functions to those provided by the MODIFY command can
also be invoked from your browser by using the Web Server Administration
interface. Refer to 5.7.3, “Monitoring the IBM HTTP Server” on page 65 for a
description of this interface.
5.7.3 Monitoring the IBM HTTP Server
The Web server accepts line mode commands to display statistic and
monitoring information as described in 5.7.2, “Controlling the IBM HTTP
Server” on page 64. The IBM HTTP Server also provides a Web-based
interface for administering the Web server, and also for consulting help files
and product information. This interface employs frames for easier navigation,
HTML forms for conveniently and accurately updating configuration
information, and Java applets.
5.7.4 Accessing IBM HTTP Server administration
IBM HTTP Server administration is accessed via a link on the default Front
Page shipped with the Web server (see Figure 19 on page 69). You would
probably not include this link on any publicly accessible page served by your
server. Your security requirements determine how and to whom you make this
facility available (or indeed, whether you make it available at all), as we
discuss in 5.7.8, “Administration security considerations” on page 76. By
default, HTTP Basic Authentication (user ID: webadm) is used to control
access to Web Server Administration interface.
There are some specific browser requirements for using this facility, including
support for HTML forms and for the Java Development Kit (JDK) 1.1.4. In
practice, this means either Netscape Navigator V4.04 supplemented by the
JDK 1.1.4 SmartUpdate available from the Netscape download site, or
Microsoft Internet Explorer V4.0. At the time of writing, the latest version of
Netscape Communicator is 4.7 with integrated JDK 1.1.5.
If using Netscape, you can check your installed JDK level by starting the Java
Console and reading the startup messages:
Netscape Communications Corporation -- Java 1.1.5
Type '?' for options.
Symantec Java! ByteCode Compiler Version 210.065
Operating the Domino for IBM HTTP Server
65
Copyright (C) 1996-97 Symantec Corporation
You need to enable both Java and JavaScript in your browser and to specify
that the cached document always be compared to the network document. The
latter requirement is to ensure that the user receives accurate feedback when
submitting forms. In Netscape Navigator V4 these options are set by
selecting Edit/Preferences as illustrated in Figure 17.
Figure 17. Enabling Java options in Netscape Navigator
In Microsoft Internet Explorer (MSIE), these options are set by selecting
View/Internet Options as illustrated in Figure 5.7.5 on page 67. For MSIE
version 5, select Tools/Internet Options. Then, click the Settings button
inside the Temporary Internet Files box (this is the same for both versions of
MSIE).
66
Domino for S/390 and Web Server Integration
Figure 18. Enabling Java options in Microsoft Internet Explorer
5.7.5 Functions of the configuration and administration forms
Web server Administration provides you with a graphical user interface (GUI)
for managing your Web server. It allows you to:
1. View and update the server configuration.
The use of HTML forms provides a potentially more readable display of
configuration data and a more accurate way of updating it than is possible
by directly editing the httpd.conf configuration file. One limitation,
however, is that it is not possible using Web Server Administration
interface to enter comments into your configuration file to describe and
time stamp your changes.
2. Restart the server.
This is a convenient way of testing changes to your server configuration
that take effect on restart. Not all changes are in that category. Refer to
Appendix C in IBM HTTP Server for OS/390 Release 7, Planning,
Installing, and Using, Version 5.1, SC31-8690 for a list of configuration
changes that require the server to be stopped and then started again. For
Operating the Domino for IBM HTTP Server
67
such changes (which are grouped under a single Basic form in Web
Server Administration), you need to use either the console or UNIX
System Services to stop and start the IBM HTTP Server, but you do not
need to restart your browser or re authenticate.
3. Display statistics and usage reports.
Web Server Administration provides a more comprehensive and readable
display of server statistics than is provided by the MODIFY command. It
also gives you some very useful reports on the usage of your server,
including details of entry and exit links, most popular links, and users from
whom requests have originated.
4. Access online copies of documentation and help information.
You can access the IBM HTTP Server publications via your browser, and
also a range of help information, including help on specific forms and more
general help on various aspects of administering the IBM HTTP Server.
One obvious requirement for using the Web Server Administration interface is
that the Web server must be running. If you wish to make configuration
changes when the server is not running, then of course you have to directly
edit the httpd.conf file.
In 5.7.7, “Mapping Web Server Administration functions” on page 75 we
summarize the configuration changes and reporting options available with
Web Server Administration.
5.7.6 Using the Web Server Administration interface
The following sections give you an idea of the content and flow of the Web
server administration facility. Of course, only by using it yourself can you
develop a close familiarity with its functions and interface, and decide
whether it is the right administration tool for your organization.
5.7.6.1 Front page and authentication
Figure 19 on page 69 shows the default IBM HTTP Server Front Page,
with the authentication window that is presented when you click
CONFIGURATION AND ADMINISTRATION FORMS. You are also
presented with this authentication prompt if you click HOW DO I GET
STARTED? on the same Front Page. Regardless of the path you take, you
are only prompted once for your user ID and password, provided your
browser continues running.
68
Domino for S/390 and Web Server Integration
Figure 19. IBM HTTP Server configuration and administration authentication
5.7.6.2 IBM HTTP Server introduction page
Figure 20 on page 70 shows the introduction page following successful user
authentication. Note some of the key navigation aspects of Web server
administration that are visible on this page.
Operating the Domino for IBM HTTP Server
69
Figure 20. IBM HTTP Server introduction page
On the left is a frame that displays a menu of administration forms, or
expandable headings for such forms. The selected form or text is displayed to
the right of the frame. At the top of the window is a title bar for the current
form. Apart from the title, two small buttons are always displayed on this bar,
at the right-hand end: an exclamation mark for restarting the server, and a
question mark for accessing help. Clicking the Restart button is a convenient
way of testing or implementing configuration changes that do not require the
server to be stopped and then started again in order to take effect. Clicking
the help button displays, in turn, a small menu of three levels of help, which
are depicted in subsequent figures.
Just below the title bar you see a status indicator, initially set to Ready.
During and following execution of an action such as submitting a form,
requesting information, or restarting the server, this indicator displays the
current status of that action.
70
Domino for S/390 and Web Server Integration
The use of frames means that the current forms or topics are always visible
and selectable on the left side of the screen. Help panels are always
launched in a new window. These features of Web Server Administration
make for easier navigation, and in particular reduce the need to use the Back
button on your browser.
You are initially presented with the menus for the IBM HTTP Server, but you
can select the menus for the proxy server by clicking IBM Web Traffic
Express, which is initially at the bottom of the left frame, and then switch
between the two sets of forms.
5.7.6.3 Web Server administration form
Figure 21 shows a typical page corresponding to the selection of a particular
form in the forms menu (the Fast Response Cache Accelerator form, in this
case).
.
Figure 21. Sample IBM HTTP Server administration form
Operating the Domino for IBM HTTP Server
71
This example gives you an idea of how the forms interface works. Apart from
fields for entering new information, the form also presents you with existing
values of related fields that you can choose to keep or to override.
5.7.6.4 Form help page
Figure 22 shows the Help page for the FRCA form. We obtained this page by
clicking the Help icon while the corresponding form was displayed and then
selecting Field help (which is always context-sensitive). This information is
displayed in a new window, enabling us to easily switch between a given form
and its help information.
Figure 22. Sample IBM HTTP Server administration form help
5.7.6.5 HTTP server help contents pages
Figure 23 shows the Contents tab of the main help page. You can arrive at
this page by several routes, for example by clicking the Help button and then
selecting How do I?, or by clicking HOW DO I GET STARTED? from the
Front Page.
72
Domino for S/390 and Web Server Integration
Figure 23. IBM HTTP Server help contents
The items in the Contents menu provide information on forms and on specific
actions, as well as general information on various topics. The example in
Figure 23 shows information resulting from the selection of the Security topic
from the menu.
5.7.6.6 HTTP server help index pages
Figure 24 shows the Index tab of the main help page. You can arrive at this
page by several routes, for example by clicking the Help button and then
selecting Index, or simply by clicking the Index tab when you have the
Contents page already displayed.
Operating the Domino for IBM HTTP Server
73
.
Figure 24. IBM HTTP Server help index
Menu links relating to the Web server itself are of the form
/admin-bin/helpout/hlpxxxxx, where xxxxx identifies the particular help topic.
The Index menu also includes help items for FRCA. The example in Figure 24
shows information regarding the page (form) for enabling and tuning FRCA.
5.7.6.7 Navigation summary
Figure 25 on page 75 illustrates the high-level flow of the Web Server
Administration panels. The main features to observe in this diagram are the
authentication process, the implementation of Web Server Administration as
a Java applet, and the interaction between the execution environment (when
submitting a form) and the help environment (for obtaining information about
a form or some other aspect of the administration of the IBM HTTP Server).
74
Domino for S/390 and Web Server Integration
Figure 25. Web Server administration flow
5.7.7 Mapping Web Server Administration functions
The Web Server Administration GUI is intended to make the configuration
process simpler, more intelligible, and more accurate. For this reason, Web
Server Administration does not generally expose directive names to the user,
but instead uses functional language to describe the purpose and contents of
its configuration forms. In this way, you can (in theory) administer your Web
server without ever directly seeing your httpd.conf file. In practice, however,
you need to edit the configuration file if you want to add comments to it or if
you want to make configuration changes when the server is not actually
running.
An example of a common administration function is to add mapping directives
( Map, Pass, Fail, Exec, Redirect) to map URLs to specific files. The form for
this particular kind of configuration change is called Request Routing in the
forms menu. If you did not know that, you could click the entry for the Pass
mapping rule in the Help Index, where you are referred to the Request
Routing form (as well as given comprehensive tutorial information on how
these directives work).
Operating the Domino for IBM HTTP Server
75
Some of the IBM HTTP Server functions that are provided with the OS/390
MODIFY command can be invoked from Web Server Administration. Table 7
provides a correlation of those functions with specific administration forms.
Table 7. MODIFY command options using Web server administration forms
Function
MODIFY command option
Web Server Administration
form
Display basic
configuration
information
-d config
Basic
Display server
statistics
-d stats
Server Activity Monitor:
Activity Statistics
Control SMF
reporting
-smf [perf|config]
-nosmf [perf|config]
Logging and Reporting:
Global Logging File
Configuration Settings
Restart server
-restart
Click on Restart button
Display version
-version
Introduction
5.7.8 Administration security considerations
For some organizations, Web Server Administration is a convenient and
easy-to-use facility for administering your Web server. However, you should
evaluate the use of the Web interface against your security requirements. To
the extent that your Web server is a critical resource, you need to restrict
access to its operator facilities as you would to the operator facilities of any of
your critical subsystems and applications. However, some new
considerations arise if you are thinking of accessing Web Server
Administration over the Internet. Again, these considerations are not unique
to the Web interface, but would also apply if you were thinking of providing
operator access via the Internet to any of your internal systems.
5.7.8.1 Authentication and confidentiality
By default, the IBM HTTP Server provides an administrative user ID
(WEBADM) and a Protection directive called IMW_Admin, which uses HTTP
Basic Authentication (non-encrypted user ID and password) to protect access
to Web Server Administration. This does not provide adequate security for
such a critical application in an Internet environment. Not only is the
authentication weak, but your administration traffic is visible to an
eavesdropper, revealing potentially sensitive information about your Web
server.
Therefore, some stronger form of authentication is warranted, for example:
76
Domino for S/390 and Web Server Integration
1. Use SSL with server authentication to provide encryption of the Web
server administration session, and in particular of the user ID and
password, provided you are able to restrict all traffic to the SSL port (443,
by default).
2. Use SSL with server and client authentication, providing strong
authentication of the client, as well as encryption of the session.
Of these options, the second is obviously the more secure and flexible.
5.7.8.2 Administration access control
To the extent that use of a workstation cannot be reliably equated with a
particular user, you need to exercise care in the use of Web Server
Administration, even when the workstation is attached to your intranet.
If you are using Basic Authentication, your user ID and password are cached
in browser memory after you respond to the authentication prompt, and are
automatically transmitted with each subsequent request to access a
protected page. This authentication information is retained in memory as long
as your browser remains active, even if you close your Web Server
Administration window. You should keep this in mind if there is a possibility of
your browser being shared with or accessed by other users.
Another consideration is that the IBM HTTP Server allows multiple
administrators to be concurrently signed on with the same Web Server
Administration user ID. This could result in operational problems if those
administrators attempted to perform conflicting actions. Again, this is
something that could be avoided with a combination of strong controls on the
administration user ID and password and stronger client authentication. For
example, imposing a requirement for a client certificate would solve this
problem, as well as the other problems previously identified.
If you do not pursue the certificate option, we recommend that you not use
the supplied WEBADM ID for managing your Web server. Rather, you should
remove that ID from the mask parameter of the IMW_Admin protection directive,
and include the RACF TSO user ID of a trusted administrator (unless you
have assigned the WEBADM ID to your trusted administrator).
Your ultimate recourse, if you are concerned with the security of the Web
Server Administration interface, is to disable the facility by setting appropriate
directives in the configuration file, for example:
• Change the Pass directive for /admin-bin/webexec/* to a Fail directive.
• Comment out the Exec directive for URLs of the form /admin-bin/*.
Operating the Domino for IBM HTTP Server
77
78
Domino for S/390 and Web Server Integration
Chapter 6. OS/390 authentication support for Domino
The Domino for IBM HTTP Server brings together two products that by
themselves have especially rich security features. The Domino server and the
IBM HTTP Server are systems with tight authentication and sophisticated
resource protection schemes. When both are joined by the Domino for IBM
HTTP Server, and the IBM HTTP Server becomes the HTTP gateway for
Domino, it is obvious that there are new possibilities for the handling of
security, in particular for authentication purposes.
It may not make much sense to re-map the database protection characteristic
of Domino into RACF profile protections, but the use of RACF for
authentication appears as an immediate option. The design of the Domino for
IBM HTTP Server makes an effort to retain both authentication systems,
RACF and Domino, as options to choose from, depending on specific
application requirements. As a result, the Domino for IBM HTTP Server
connector fully supports the same authentication process as the Domino
built-in HTTP task when authenticating Web user access to protected
databases.
In addition, the connector provides optional OS/390 authentication support,
extending the authentication process to allow OS/390 user ID and
passwords, or electronic certificates managed by RACF, to be used to verify a
Web user’s identity.
6.1 Web access authentication overview
When a client issues a Web access request to a server, the server may need
to determine the identity of the Web user making the request. The process of
determining and verifying a user’s identity is called authentication.
There are two authentication methods commonly used by today’s web to
convey the Web users identity: HTTP Basic authentication and SSL client
certificate authentication. We discuss these methods in detail in the following
sections.
6.1.1 HTTP basic authentication
HTTP basic authentication is sometimes referred to as username and
password authentication. In this method, when a Web user attempts access
to a protected resource, the Web server challenges the user’s browser to
supply a username and password with the request in order to authenticate
the user. If this is the first such request for this Web server (and
© Copyright IBM Corp. 2000
79
authentication “realm”), the browser will prompt the user to enter a username
and password, and then it will re-issue the request including this information
as the user authentication credentials. The username is used to identify the
user and the password to verify that identity. HTTP basic authentication can
be used on normal (http:) and secure/SSL (https:) connections.
6.1.2 SSL client certificate authentication
SSL client certificate authentication uses X.509 certificates in conjunction
with secure/SSL (https:) connections. X.509 certificates are also sometimes
referred to as electronic certificates. In this method, the browser is configured
to hold an electronic certificate (and corresponding private key) that uniquely
identifies the Web user.
When the user establishes an SSL connection with a Web server, the Web
server asks the user’s browser to supply the user’s electronic certificate.
Using public-key cryptographic techniques, the Web server verifies that the
certificate belongs to the user that supplied it, and verifies that the certificate
is trustworthy by checking that it has been issued by a trusted issuer or
certificate authority. The certificate is used to identify the user.
6.1.3 Domino session authentication option
In addition, outside of the authentication mechanisms defined by the
protocols, there can be an application layer authentication where the
challenge and clearance is handled by the application, possibly using cookies
to perpetuate session term user identification. The built-in Domino HTTP task
provides the application developer with a Domino Session Authentication
option based on this type of application layer process.
6.1.4 Authentication summary
At this point it should be clear that HTTP basic authentication can be used
both on normal and secure (SSL) connections and that secure (SSL)
connections allow the use of both basic and certificate authentication.
Obviously, both types of connections, secure (SSL, https:) or not (http:), can
be used in an unauthenticated mode. It is no secret that today, most Web
traffic is unauthenticated over non-secure channel (http:). Only a small
fraction of the traffic runs in secure mode (SSL, https:) and in turn, most of it
is unauthenticated (for example a merchant only cares about your credit card
number). The rest, a very tiny fraction of all traffic, is SSL with X.509
certificates.
80
Domino for S/390 and Web Server Integration
6.2 Overview of authentication with the Domino for IBM HTTP Server
When a Web user accesses a database through the IBM HTTP Server
running the Domino for IBM HTTP connector (or through Domino’s built-in
HTTP task), Domino performs access control list checking to verify that the
user is authorized to access the database and perform the action being
requested. As part of this access control list checking, Domino may need to
determine the identity of the Web user making the request, that is, to
authenticate the user.
Domino supports Basic Authentication and SSL client certificate
authentication. In addition, Domino also provides a third authentication
method, specific to Domino, called session authentication.
Session authentication is a username and password authentication method
like HTTP basic authentication. However, unlike HTTP basic authentication,
the username and password challenge and response is accomplished
through Domino-generated HTML forms and session cookies rather than
through mechanisms defined by the HTTP protocol.
The Domino for IBM HTTP Server connector supports all three methods of
Web user authentication, but as explained before, the connector adds the
choice of selecting the Domino or OS/390 authentication process. The HTTP
basic authentication and SSL client certificate authentication methods can be
used in conjunction with the two authentication processes and associated
repositories: the standard Domino Web authentication process, and the
optional OS/390 authentication process (RACF). Domino for IBM HTTP
Server supports Domino Session Authentication only in conjunction with the
standard Domino Web authentication process and not with OS/390
authentication.
6.2.1 Using Domino authentication
The standard Domino Web authentication process involves verifying user
identities using user information in the Domino directory. By default, the Web
connector employs the standard Domino authentication model only. In this
configuration, the connector treats all authentication credentials received
from Web users (that is, usernames and passwords or electronic certificates)
as being Domino usernames and passwords or Domino-managed
certificates.
The Web connector passes all requests to Domino as not-yet-verified
requests, passing along the original username and password and/or
electronic certificate received with the request. These credentials are used by
OS/390 authentication support for Domino
81
Domino in performing its standard Web authentication process using user
information (names, passwords, certificates) stored in the Domino directory.
• In the case of username and password authentication, Domino uses the
username to locate a Person document in the Domino directory, and then
verifies that the password supplied by the Web user matches the Internet
password in that Person document; see Figure 26.
• In the case of certificate authentication, Domino uses information in the
certificate to locate the user Person document. This Domino Web
authentication processing is the same as that done for Web requests
made through Domino’s built-in HTTP task.
Figure 26. Person document
6.2.2 Using OS/390 authentication
The Web connector’s OS/390 authentication support extends the Web
authentication process to allow Web users to authenticate for Domino
82
Domino for S/390 and Web Server Integration
requests using either OS/390 authentication credentials managed by RACF,
or Domino authentication credentials managed by Domino. When this support
is enabled and set up for a Web user, the user can supply either their OS/390
user ID and its password, or their Domino username and its Internet
password when challenged to provide a username and password as part of
HTTP basic authentication. Similarly, when authenticating by certificates, the
user can provide an SSL electronic certificate that has been registered in
RACF or in the Domino directory.
The connector’s OS/390 authentication support works in conjunction with the
application identity mapping support provided by RACF. This RACF support
allows a Domino identity, in the form of a Domino shortname, to be
associated with a user’s profile in RACF. The Web connector’s authentication
process occurs in two steps.
First, the Web connector treats the authentication credentials provided by the
Web user as being OS/390 credentials, and uses them to authenticate the
Web user as an OS/390 user ID using RACF. If the first step is successful, the
connector then uses the RACF application identity mapping service to map
the OS/390 user ID to its corresponding Domino identity (shortname). If
successful, the Web connector passes the request to Domino as a
pre-authenticated request, specifying the Domino shortname as the user’s
Domino identity.
If the connector is unable to authenticate the Web user as an OS/390 user ID
(for example, if the first step fails), the Web connector passes the request to
Domino as not-yet-verified, supplying the original username and password
and/or the electronic certificate received with the request. This allows Domino
to perform its standard authentication processing for the request. If the Web
connector is able to authenticate the Web user as an OS/390 user ID (for
example, if the first step succeeds), but there is no Domino shortname
associated with the user’s RACF profile, the Web connector passes the
request to Domino as an anonymous request, that is, without any username
and password or electronic certificate.
OS/390 authentication support for Domino
83
6.3 Authentication processing details
This section provides a detailed description of the authentication processing
done by Domino for IBM HTTP Server in both supported flavors, using
Standard Domino authentication and using OS/390 authentication.
It is important to note that the result of either authentication system is to
assign the Notes user ID under which the Web browser request is being
made. This ID will correspond to a Person entry in the Domino directory or to
the generic Anonymous if the authentication process is unsuccessful. This
Notes ID will then be used in the Access Control List (ACL) process
associated with all database operations performed during the term of the
HTTP transaction. Since unauthenticated Web users are mapped to
Anonymous, it is important to add in database ACLs an entry for Anonymous
with the desired access level. Otherwise, anonymous users will be given
-Default- access.
6.3.1 Standard Domino authentication
In its default configuration, the Web connector treats all security credentials it
receives from Web users as being Domino (rather than OS/390) credentials.
In this default setup, the OS/390 authentication is disabled. The connector
passes all requests to Domino as not-yet-verified requests, passing along the
original username and password and/or electronic certificate received with
the request. These credentials are used by Domino in performing its standard
certificate or basic authentication processing as required by the ACLs on the
databases being accessed.
84
Domino for S/390 and Web Server Integration
6.3.1.1 Anonymous requests with Domino authentication
If the Web user makes a request anonymously, that is without supplying
either a username and password or electronic certificate, Domino processes
the request as the Anonymous user. The actual access level to a given
database will depend on the database security setup (such as ACL and
Internet access).
Figure 27. Anonymous request with Domino standard authentication
If a Web user’s request is for a database or action that is protected and the
credentials (or lack of them) do not grant access and the Domino server has
been configured to allow name and password authentication, Domino will
generate a basic-authentication challenge back to the Web user to supply a
username and password for the request.
OS/390 authentication support for Domino
85
6.3.1.2 Basic authentication requests with Domino authentication
Web clients usually send a Basic authentication request in one of two
situations; see Figure 28:
• As a result of a challenge from Domino to a previous anonymous request.
The Web client, upon receiving the rejection and challenge from the
server, prompts the user for user ID and password and reissues the
request with the credentials attached.
• In subsequent requests to the server after an authenticated transaction. In
general, due to built-in logic, once the Web client has gone through a
challenge and authentication cycle, it will include the credentials on all
requests to the same server. Without this logic, most likely every request
would be challenged and would have to be re-issued.
Figure 28. Basic authentication request with Domino standard authentication
86
Domino for S/390 and Web Server Integration
6.3.1.3 X.509 authentication requests with Domino authentication
In the case of SSL requests that include electronic certificates, the IBM HTTP
Server plays a role in the authentication process, assuming the proper setup
is in place. When the user connects to the IBM HTTP Server using an SSL
(https:) connection, and if the URL request is for a Domino database and is
thus handled by the Domino for IBM HTTP Server connector (and the OS/390
authentication option is not enabled), the process is illustrated in Figure 29:
Figure 29. Client certificates with Domino standard authentication
The IBM HTTP Server will request a client certificate from the browser and
verify that the certificate provided by the browser is signed by a certificate
authority that is marked as trusted in the IBM HTTP Server’s key database.
• If the certificate is not signed by a trusted signer, the IBM HTTP Server
does not accept the certificate from the browser, and the request
processing continues as if no certificate were supplied.
• If it is trusted, the connector will obtain the certificate from the IBM HTTP
Server and pass it to Domino as part of the request.
OS/390 authentication support for Domino
87
Domino will use the certificate in a similar way as it would for client
certificates arriving with requests through the built-in HTTP task. The
certificate will be used in a Domino directory lookup to find the Person
document corresponding to the user. The resulting Domino user name will
be used to perform ACL checking for protected databases.
6.3.2 OS/390 authentication
This section describes the authentication process outside Domino.
6.3.2.1 Anonymous requests with OS/390 authentication
If a Web user makes a request anonymously, that is without supplying any
username and password nor an electronic certificate, the Web connector
passes the request to Domino without any security credentials. Domino
processes the request as the Anonymous user.
Figure 30. Basic authentication request with OS/390-based authentication
If the Web users request is for a database or action that is protected and the
Domino server has been configured to allow name and password
authentication for Web users, Domino will generate a challenge back to the
Web user to supply a username and password for the request.
88
Domino for S/390 and Web Server Integration
6.3.2.2 Basic authentication requests with OS/390 authentication
If a Web user makes a request including a basic authentication username and
password, the connector first uses the username and password to attempt to
authenticate the user as a OS/390 user ID using RACF. If successful, it then
maps that OS/390 user ID to a Domino identity (shortname) using the RACF
application identity mapping service. If this process is successful, the Web
connector passes the request to Domino as a pre-authenticated request,
specifying the mapped-to Domino shortname as the user’s security
credentials. If this process is not successful, the connector either passes the
original username and password to Domino (used by the Domino standard
basic authentication process), or passes the request to Domino as an
anonymous request. The complete process is illustrated in Figure 31:
Figure 31. Basic OS/390 authentication request using RACF
• First, the connector considers the username and password supplied with
the request as being an OS/390 user ID and password and attempts to
verify the user ID and password using RACF.
OS/390 authentication support for Domino
89
- If RACF verification fails, the OS/390 authentication process ends and
the connector passes the request to Domino as a not-yet-authenticated
request, passing the username and password as the user’s security
credentials along with the request. The username and password are
used by Domino as part of its normal basic authentication process as
described in previous sections of this chapter.
• If the credentials identify a valid OS/390 user, the Web connector uses the
RACF application identity mapping service to determine the Lotus
Notes/Domino shortname associated with the user’s RACF USER profile.
This shortname is recorded in the LNOTES segment of the RACF USER
profile.
- If there is no value in the LNOTES segment, the process ends and the
connector passes the request to Domino without any security
credentials, that is, as an anonymous request.
• If the USER profile has a Lotus Notes/Domino shortname associated with
it, the connector turns to the Domino side to verify this as a shortname
against the Domino Directory:
- If it cannot relate the shortname value to a Domino directory person
entry, the connector passes the request to Domino without any security
credentials, that is, as an anonymous request. The original username
and password provided with the request are not passed to Domino.
• If the connector can successfully identify a Notes user by the shortname
value, it passes the request to Domino as a pre-authenticated request,
giving the Domino shortname as the user’s security credentials.
90
Domino for S/390 and Web Server Integration
6.3.2.3 X.509 authentication requests with OS/390 authentication
If a Web user makes a request using an SSL connection and provides an
electronic certificate signed by a trusted signer, the Web connector first uses
that certificate to attempt to authenticate the user as OS/390 user ID using
RACF digital certificate support and, if successful, then maps that OS/390
user ID to a Domino identity (shortname) using the RACF application identity
mapping service. If this process is successful, the connector passes the
request to Domino as a pre-authenticated request, specifying the mapped-to
Domino shortname as the user’s security credentials. If this process is not
successful, the connector either passes the original certificate to Domino
(used by the Domino standard certificate authentication process), or passes
the request to Domino as an anonymous request. The complete process is
illustrated in Figure 32:
Figure 32. Client certificates with OS/390-based authentication
OS/390 authentication support for Domino
91
• As part of establishing the SSL connection with the Web browser, the IBM
HTTP Server obtains the electronic certificate from the browser and
verifies if the certificate is signed by the certificate authority (CA) that is
marked as trusted in the IBM HTTP Server’s key database.
- If the certificate is not signed by a trusted signer, it is not accepted by
the IBM HTTP Server and never reaches the connector. The resulting
effect is the request is processed as if it arrived without any security
credentials, that is, as an anonymous request.
• If the certificate can be trusted, it is given to the Web connector that will
attempt to map the certificate to an OS/390 user ID using RACF digital
certificate support.
- If the check against the RACF database fails, the authentication on the
OS/390 side ends and the connector passes the request to Domino as
a not-yet-authenticated request. The certificate reaches Domino as the
user’s security credentials along with the request and is used by
Domino as part of its normal certificate authentication process.
• If the certificate is successfully mapped to an OS/390 user ID, the Web
connector uses the RACF application identity mapping service to
determine the Lotus Notes/Domino shortname associated with the user’s
RACF USER profile. This shortname is recorded in the LNOTES segment
of the USER profile.
- If there is no value in the segment, the OS/390 authentication process
ends and the connector passes the request to Domino without any
security credentials, that is, as an anonymous request.
• If the USER profile has a Lotus Notes/Domino shortname associated with
it, the Web connector turns to the Domino side to verify this as a valid
shortname against the Domino directory:
- If this verification fails, the connector passes the request to Domino
without any security credentials, that is, as an anonymous request. The
original certificate provided with the request is not passed to Domino.
• If this verification succeeds, the connector passes the request to Domino
as a pre-authenticated request, specifying the Domino shortname as the
user’s security credentials.
92
Domino for S/390 and Web Server Integration
6.3.2.4 X.509 and basic authentication with OS/390 authentication
It is possible for an SSL request to carry both an electronic certificate and
basic authentication username and password credentials. If such a request
with a trusted certificate reaches the Web connector, it first uses the
certificate to attempt to authenticate the user as OS/390 user ID using RACF.
If that fails, the Web connector then tries to use the basic authentication
username and password as an OS/390 user ID and password and verify them
using RACF. If either of these authentication methods succeeds, the
connector maps that OS/390 user ID to a Domino identity (shortname) using
the RACF application identity mapping service. If this process is successful,
the connector passes the request to Domino as a pre-authenticated request,
specifying the mapped-to Domino shortname as the user’s identification. If
this process is not successful, the Web connector either passes the original
username and password and certificate to Domino (used by the Domino
standard certificate and basic authentication processes) or passes the
request to Domino as an Anonymous request. The complete process is
illustrated in Figure 33:
Figure 33. X.509 and basic authentication with OS/390 authentication
OS/390 authentication support for Domino
93
• As part of establishing the SSL connection with the Web browser, the IBM
HTTP Server obtains the electronic certificate from the browser and
verifies that the certificate is signed by a certificate authority that is
marked as trusted in the IBM HTTP Server’s key database.
- If the certificate is not signed by a trusted signer, it is not accepted by
the IBM HTTP Server. Processing continues as if only username and
password were provided, as described before for requests with basic
authentication credentials. The Web connector will either identify a
valid OS/390 user or give a chance to Domino authentication.
• If trusted, the certificate is given to the Web connector to attempt to map
the certificate into an OS/390 user ID by using RACF digital certificate
support.
- If mapping fails, the Web connector attempts to authenticate username
and password as an OS/390 user ID and password against RACF.
• If both the certificate and the username/password authentication fail
to validate an OS/390 user, the OS/390 authentication ends and the
connector passes the request to Domino as a not-yet-authenticated
request. Both the certificate and the username/password are given
to Domino as the user’s security credentials along with the request.
The certificate and username/password are used by Domino as part
of its normal certificate and basic authentication process.
• If either the certificate or username/password successfully authenticate
the user as an OS/390 user ID, the Web connector uses the RACF
application identity mapping service to determine the Lotus Notes/Domino
shortname associated with the user’s RACF USER profile. This shortname
is recorded in an LNOTES segment of the USER profile.
- If there is no value in the segment, the OS/390 authentication process
ends and the connector passes the request to Domino without any
security credentials, that is, as an anonymous request.
• If the USER profile has a Lotus Notes/Domino shortname associated with
it, the connector verifies this shortname with Domino to ensure that it is a
valid shortname registered in the Domino directory.
- If this verification fails, the connector passes the request to Domino
without any security credentials (that is, as an anonymous request).
Neither the original certificate nor the username/password provided
with the request are passed to Domino.
• If this verification succeeds, the connector passes the request to Domino
as a pre-authenticated request, specifying the Domino shortname as the
user’s identification.
94
Domino for S/390 and Web Server Integration
6.4 Enabling OS/390 RACF-based authentication
The standard setup procedure configures the Domino for IBM HTTP Server
so that the authentications are performed by Domino. If the decision is made
to enable OS/390 authentication, this can be achieved by the following steps:
1. Update the IBM HTTP Server’s permissions.
Update the RACF permissions for the IBM HTTP Server user ID
(WEBSRV by default) so that it has the authority to invoke the RACF
application mapping service to retrieve the LNOTES segment for later
matchup with the shortname in Person documents. From a user ID with
RACF SPECIAL authority, issue the following commands:
rdefine facility irr.rusermap uacc(none)
permit irr.rusermap class(facility) id(WEBSRV) acc(read)
setropts raclist(facility) refresh
2. Activate the connector’s OS/390 authentication processing.
The connector can be instructed to use OS/390 authentication by altering
the ServerInit statement in the server’s httpd.conf file by appending the
terms -platcreds allow. This will enable the use of OS/390 platform
credentials.
ServerInit PATHNAME/domihttp:ServerInit "sslport SSL_PORT -platcreds allow"
For this change to take effect, the server will have to be restarted. Obviously,
for it to make a difference, users have to be properly defined in RACF.
6.5 Practical considerations
As explained in previous sections, Domino for IBM HTTP Server (the Web
connector) brings OS/390 authentication into the picture, but the Domino
database access control scheme remains in place. Once a Web user is
authenticated, his ability to deal with a database is set in the database’s ACL.
On the other hand, the combined authentication process causes either
selection to be not as absolute as one might think. Here are points worth
considering:
• OS/390 authentication is just an option, and it is disabled in the default
configuration, leaving the authentication in the hands of Domino.
• Enabling OS/390 authentication is easy as described in 6.4, “Enabling
OS/390 RACF-based authentication” on page 95. But doing so without
loading user definitions in the RACF database makes little sense. On the
other hand, existing RACF user definitions are of no value without
corresponding entries in the Domino directory. This is because after the
OS/390 authentication support for Domino
95
user ID is RACF authenticated, it must be mapped to a Notes user by an
LNOTES match to shortname. User RACF profiles with invalid LNOTES
segments will result in anonymous requests.
• Enabling OS/390 does not disable Domino/390 authentication. If the user
ID password fails the RACF check, it is percolated to the standard Domino
authentication where it will have a second chance. This has some
implications:
- It is feasible to have a hybrid setup where only a fraction of the users
access the server using RACF credentials, while the rest use the
Domino user and Internet password.
- All non-RACF users will incur an OS/390 authentication failure before
reaching the Domino process. However small, the resources involved
in the failed check could be considered a waste. If this became an
issue, users could be placed in different servers.
• Use of standard Domino authentication in a Domino for IBM HTTP Server
environment applies only to database objects, because only nsf-type
URLs are passed to the connector. Requests for other objects like HTML
pages and Java servlets are served by the HTTP side without the
knowledge of Domino. In this sense, the use of RACF authentication can
help to extend the scope of protection.
96
Domino for S/390 and Web Server Integration
Chapter 7. Setting up a secure Web server
This chapter helps you to set up the IBM HTTP Server in a way so that it can
be used as a secure server in conjunction with the Domino for IBM HTTP
Server. Since the server will be part of a Domino environment and may be
pre-existent, the chapter covers some alternative options, in particular in the
choice of an internal certificate authority.
As described in Chapter 4, “Basic IBM HTTP Server installation” on page 35,
we intend to provide you with a “quick and proper” customization which
enables you to get a fast start. Security in the Web server is an extensive
topic and is described in detail in OS/390 e-business Infrastructure: IBM
HTTP Server 5.1 for OS/390 - Customization and Usage, SG24-5603.
The steps for setting up a secure Web server are:
1. Decide on the source of the server certificate you will use.
2. Set the key ring with the server certificate.
3. Make configuration changes to establish SSL.
In addition, if you are interested in setting the server to accept electronic
certificates, refer to Chapter 8, “Setting up client certificates” on page 111
where the topic is covered with enough detail to get you started in that area.
7.1 Decision on server certificates
You must decide what source of certificates will be used to authenticate your
server. A certificate must be created by a certification authority (CA), and you
can choose to use one of following authorities.
• External (commercial) CA organizations
• Self-certified CA
To get started with SSL, you will probably want to do some testing within your
organization, and for this purpose self-certification will probably be sufficient.
In a pure IBM HTTP environment the preferred way is to use IKEYMAN to
create a self-signed certificate authority. However, since the server will be
part of a Domino environment, it may be an advantage to use the internal
Domino Certificate Authority to sign the server certificate. This CA is also a
self-signed authority, but it may be a better option, especially if X.509 client
certificates come into consideration, in which case it really simplifies the
insertion of the certificate into the Domino directory.
© Copyright IBM Corp. 2000
97
If you deploy applications on the Internet, you will need a certificate from a
widely recognized CA in the geographic region you expect your clients to
connect from. The wider the geographic area you expect to reach out to, the
more careful you will have to be about selecting a widely recognized CA.
For the purpose of this chapter we will provide basic guidance to get started
with either of these options, IKEYMAN and the Domino Certificate Authority.
7.2 Creating a server certificate using IKEYMAN
This section describes how to generate server certificates using the IBM
HTTP Server’s IKEYMAN utility.
7.2.1 Accessing the IKEYMAN utility
The following gives you access to the IKEYMAN utility:
• It is located in /usr/lpp/internet/bin.
• It has default permission bits 751; Owner WEBADM; Group IMWEB.
• Prepare the environment by setting up PATH, LIBPATH and NLSPATH
environment variables. If you plan to use IKEYMAN frequently, modify
your user profile to enable it there. To do so add the following definitions to
your .profile data set .profile:
• export PATH=$PATH:/usr/lpp/internet/bin
• export LIBPATH=$LIBPATH:/usr/lpp/internet/bin:.:
• export NLSPATH=$NLSPATH:/usr/lpp/internet/%L/%N
7.2.2 Generating and installing a self-signed certificate
IKEYMAN provides a simple way to create a self-signed certificate. This
certificate, which is in fact a CA (or root) certificate, can be used as an
operational server certificate.
1. In the USS shell, change to the destined directory and execute IKEYMAN:
cd /web/candy/sec
ikeyman
(see our proposed directory structure)
Note
As you will see later, the key database and the stash file (a separate file
containing the encrypted database password) need to be in the same
directory. Therefore, make sure that you change to the directory where you
want to store the key database before performing the next steps.
2. Use the IKEYMAN entry panel as shown in Figure 34:
98
Domino for S/390 and Web Server Integration
Option 1
Create a new key database.
Name
Use a name to identify this file as the server key
database.
Password
Select a password.
Expire
No.
Next selection Select option 5 in the Key database menu as indicated in
Figure 35 on page 100 to create a self-signed certificate.
IBM Key Management Utility
Choose one of the following options to proceed.
1 - Create new key database
2 - Open key database
3 - Change database password
0 - Exit program
Enter your option number: 1
Enter key database name or press ENTER for "key.kdb": candy1.kdb
Enter password for the key database.......> secret
Enter password again for verification.....> secret
Should the password expire? (1 = yes, 0 = no) [1]: 0
The database has been successfully created, do you want to continue to work with
the database now? (1 = yes, 0 = no) [1]:
===> 1
Figure 34. IKEYMAN entry panel
Setting up a secure Web server
99
Key database menu
Current key database is /web/candy/sec/candy1.kdb
1
2
3
4
5
6
7
8
9
10
11
-
List/Manage keys and certificates
List/Manage request keys
Create new key pair and certificate request
Receive a certificate issued for your request
Create a self-signed certificate
Store a CA certificate
Show the default key
Import keys
Export keys
List all trusted CAs
Store encrypted database password
0 - Exit program
Enter option number (or press ENTER to return to the parent menu):
===> 5
Figure 35. IKEYMAN: Key database menu
3. Define certificate content:
• Version number determines the level of the certificate. We suggest you
use 3 (which is the newest and latest version).
• Enter a label for the key. Select a name that will associate the
certificate being created to being the server certificate.
• Select the desired keysize.
• 512 bit is less secure but faster than 1024 bit.
• 1024 bit is more secure but requires more cryptographic resources.
• Define the certificate fields to define the Distinguished Name (DN).
• Common Name
The Common Name usually is the server’s Domain Name. This field
will be checked against the actual URL and a warning will be issued
if they don't match.
•
•
•
•
•
Organization
Organization Unit
City/Locality
State/Province
Country
• Define when the certificate will expire.
• Select that this key will become the default key in your key database.
100
Domino for S/390 and Web Server Integration
• Store the certificate in a file.
• Choose a format. It does not matter which format you choose (we used
ASCII).
• Give the file used to store the certificate a name (cert.arm).
• Select 0 to proceed.
Enter version number of the certificate to be created (1, 2, or 3) [3]: 3
Enter a label for this key................> IBM ITSO POK The Candy Server 1
Select desired key size from the following options (512):
1:
512
2:
1024
Enter the number corresponding to the key size you want: 1
Enter certificate subject name fields in the following.
Common Name (required)................> wtsc59oe.itso.ibm.com
Organization (required)...............> IBM
Organization Unit (optional)..........> ITSO Poughkeepsie
City/Locality (optional)..............> Poughkeepsie
State/Province (optional).............> New York
Country Name (required 2 characters)..> US
Enter number of valid days for the certificate [365]: 1500
Doyouwanttosetthekeyasthedefaultinyourkeydatabase?(1=yes,0=no)[1]:1
Do you want to save the certificate to a file? (1 = yes, 0 = no) [1]: 1
Should the certificate binary data or Base64 encoded ASCII data be saved? (1 = ASCII,
2 = binary) [1]: 1
Enter certificate file name or press ENTER for "cert.arm": candy1.arm
Please wait while self-signed certificate is created...
Your request has completed successfully, exit ikeyman? (1 = yes, 0 = no) [0]:
===> 0
Figure 36. IKEYMAN: Create a self-signed certificate
4. Store the encrypted database password as indicated in Figure 37 on page
102.
For certain functions it is required to have the encrypted database
password in a separate file, so create a so-called “stash file”. This file
must be in the same directory as the key database itself. The name needs
to be associated with the key database and is predefined by IKEYMAN
based on the name of your key database.
Setting up a secure Web server
101
Key database menu
Current key database is /web/candy/sec/candy1.kdb
1
2
3
4
5
6
7
8
9
10
11
-
List/Manage keys and certificates
List/Manage request keys
Create new key pair and certificate request
Receive a certificate issued for your request
Create a self-signed certificate
Store a CA certificate
Show the default key
Import keys
Export keys
List all trusted CAs
Store encrypted database password
0 - Exit program
Enter option number (or press ENTER to return to the parent menu): 11
The encrypted password has been stored in file /web/candy/sec/candy1.sth
Your request has completed successfully, exit ikeyman? (1 = yes, 0 = no) [0]:
===> 1
Figure 37. IKEYMAN: Key database menu - option 11
Having completed the preceding steps, the following files will have been
created in your directory (/web/candy/sec in our case):
• candy1.arm
• candy1.kdb
• candy1.sth
Note
Should an error occur during this IKEYMAN process, you can just delete all
files starting with the name of your key database in your directory for the
security setup (for example, /web/server1/sec, if you followed our proposed
directory structure) and start again.
7.3 Creating the server certificate using the Domino CA
If you have plans to use the internal Domino Certificate Authority to issue
client certificates to work with the server, it makes sense to use the same CA
to sign the server certificate. 8.1, “Setting up the Domino Certificate
Authority” on page 111 describes how to set up the Domino Certificate
Authority (CA). In this section we go through the steps of creating the IBM
HTTP Server operational certificate.
102
Domino for S/390 and Web Server Integration
7.3.1 Creating and submitting the server certificate request
Start by invoking IKEYMAN. For information on the use of this utility refer to
7.2.1, “Accessing the IKEYMAN utility” on page 98.
• Select option 1 to create the Web server key database.
• Choose appropriate values for database file name, password, and
expiration period.
IBM Key Management Utility
Choose one of the following options to proceed.
1 - Create new key database
2 - Open key database
3 - Change database password
0 - Exit program
Enter your option number: 1
Enter key database name or press ENTER for "key.kdb": candy1_key.kdb
Enter password for the key database.......> secret
Enter password again for verification.....> secret
Should the password expire? (1 = yes, 0 = no) [1]: 0
The database has been successfully created, do you want to continue to work with
the database now? (1 = yes, 0 = no) [1]:
===> 1
Next, still in IKEYMAN, select option 3 to create a new key pair and certificate
request.
• Keep the default for the request file and assign a descriptive label to
identify the certificate.
• Chose a key size according to your needs.
• Fill in the distinguished name certificate information (Common name,
organization, etc.). Be sure to provide the fully qualified server’s TCP/IP
domain name (domweb1.itso.ibm.com, in our case).
Setting up a secure Web server
103
.
Enter option number (or press ENTER to return to the parent menu): 3
Enter certificate request file name or press ENTER for "certreq.arm":
Enter a label for this key................> candy1 server key
Select desired key size from the following options (512):
1:
512
2:
1024
Enter the number corresponding to the key size you want: 2
Enter certificate subject name fields in the following.
Common Name (required)................> domweb1.itso.ibm.com
Organization (required)...............> ITSO Domino for IBM HTTP Server
Organization Unit (optional)..........> ITSO Red Books
City/Locality (optional)..............> Poughkeepsie
State/Province (optional).............> New York
Country Name (required 2 characters)..> US
Please wait while key pair is created...
Your request has completed successfully, exit ikeyman? (1 = yes, 0 = no) [0]:
• Return to the main menu. Select option 11 to create the stash file and
save the password in encrypted mode. Then use option 0 to exit .
Now that the certificate request has been created, you need to pass it to the
Domino CA. Since this has to be done using copy and paste to put the
request text in the CA Web page, you need to prepare for it by copying the
request to the Windows clipboard.
• Still in the USS shell, use OEDIT to open certreq.arm, the certificate
request file.
• Select the whole text of the certificate and copy it to the clipboard. The
operation must include the Begin Certificate and End Certificate lines.
At this point you are ready to start the browser to access the Domino
Certificate Authority.
• Point the browser to the URL for the server and database corresponding
to the CA application. In our case we used:
https://domweb1:8261/ca/itso_ca.nsf
The SSL port in Domweb1/itsoweb is set to 8261.
• On the left panel, select Request Server Certificate. See Figure 38 on
page 105.
104
Domino for S/390 and Web Server Integration
Figure 38. Requesting a server certificate
• In the certificate input area, paste the certificate text previously saved in
the clipboard. Do not be overly concerned with the contact information,
since you will use Pickup ID to retrieve the signed certificate.
• Click Submit.
7.3.2 Signing the certificate with the Domino CA
At this point you turn to the Domino Certificate Authority to approve the
certificate request.
• Working from the Domino administrator, open the Domino Certificate
Authority application database.
• Click Server Certificate Requests in the left panel.
• Open the desired request by double-clicking on it.
Setting up a secure Web server
105
• Review the Server Certificate Request Approval form to be sure that the
submitted information complies with the organization’s certification policy.
See Figure 39.
Figure 39. Domino certificate processing
• Deselect the checkbox to send e-mail notification to the requestor.
• Fill in the validity period.
• Write down the Pickup ID for later use and then select Approve.
7.3.3 Retrieving and receiving the signed certificate
To complete the process, we will have to use the browser to retrieve the
signed certificate from the Domino CA and then process it with IKEYMAN to
receive it into the Server key database. First assign the trusted root of the
Domino CA; otherwise it will not trust the signer and will refuse to receive the
106
Domino for S/390 and Web Server Integration
signed certificate. If you have not done so, proceed to 8.3, “Adding the
Domino CA trusted root to the HTTP Server” on page 123.
1. Obtain the signed certificate and save it temporarily in the clipboard:
• Point the browser to the proper URL to access the Domino CA.
• On the left panel, click Pick Up Server Certificate.
• Enter the Pickup ID from the previous section and click Pick Up
Signed Certificate.
• The browser will display the signed certificate information. Select the
whole certificate text, including Begin Certificate and End Certificate.
Copy it to the clipboard.
2. Create a text file in the OS/390 UNIX HFS and paste the certificate from
the clipboard.
• Switch to the OMVS shell terminal session and start OEDIT with a
non-existent file. The file name is not significant. (From the command
line, we issued oedit signed.cert.)
• Paste the content of the clipboard into the OEDIT screen. Be sure that
the whole certificate is pasted properly, including the delimiter lines.
Save the signed.cert file and exit.
3. Receive the certificate in the Server key database (key ring).
• Start IKEYMAN and select option 2 to open the server’s key database.
Setting up a secure Web server
107
IBM Key Management Utility
Current key database is /web/candy/sec/candy1_key.kdb
1
2
3
4
5
6
7
8
9
10
11
-
List/Manage keys and certificates
List/Manage request keys
Create new key pair and certificate request
Receive a certificate issued for your request
Create a self-signed certificate
Store a CA certificate
Show the default key
Import keys
Export keys
List all trusted CAs
Store encrypted database password
0 - Exit program
Enter option number (or press ENTER to return to the parent menu): 4
Enter certificate file name or press ENTER for "cert.arm": signed.cert
Do you want to set the key as the default in your key database? (1 = yes, 0 = no
) [1]:
Please wait while certificate is received......
Your request has completed successfully, exit ikeyman? (1 = yes, 0 = no) [0]:
===>
• Select option 4, Receive a certificate issued for your request and
when prompted enter the name of the signed certificate file created
with OEDIT.
• Accept the certificate as the default key.
7.4 Configuring the Web server for SSL
To finalize your “quick and proper” setup of a secure Web server, some
changes have to be made to the configuration file httpd.conf. These changes
relate to the parameters:
KeyFile
SSLMode
SSLPort
Normalmode
108
Define name and place of the key database
Turn SSL on or off [on]
Define the SSL port number [443]
Define if normal mode still allowed [on]
Domino for S/390 and Web Server Integration
See Figure 40 for the required settings.
# keyfile key.kdb
keyfile /web/candy/sec/candy1.kdb
<-default
<-changed
<-default
sslmode on
443
<-default
normalmode on
<-default
sslport
Figure 40. httpd.conf setting for SSL mode
The Web server needs to be restarted in order to pick up the changes.
Now you can test the secure Web sever from your browser:
https://<your-server-name> if you used the default SSL port 443, or
https://<your-server-name>:<SSL port number> if you are using a port
number other than the default.
7.4.1 SSL troubleshooting
If everything is OK, the vv trace log should display the messages shown in
Figure 41 on page 109:
Loaded security US
SSL security is "on"
sslport........ 8221
normalmode is "on"
keyfile........ /web/candy/sec/candy1.kdb
secinit.c: Setting up security, state=0
secinit.c: retcode from skit_initialize=0
secinit.c: calling webdb_recoverstash
Daemon...... Parsed SSL as port 8121, inet 0.0.0.0
IP.......... Opened socket number 10
Daemon...... Master socket(), bind() and listen() all OK
Daemon...... SSL socket(), bind() and listen() all OK
Figure 41. VV trace for correct SSL setup
Setting up a secure Web server
109
If something went wrong you will get messages in your vv trace log similar to
the following:
ErrorLog.... 09/Jun/1999:10:31:07 +5000 SSL support initialization
failed, server will run only in non-secure mode without listening on ssl
port
IP.......... sslmode = off;SSL Port not opened
Should this be the case, the following might give an indication of the error.
•
•
•
•
110
Key database not at expected place.
Stash file not in the same directory as key database.
Stash file not the same name as key database.
Database password expired.
Domino for S/390 and Web Server Integration
Chapter 8. Setting up client certificates
This chapter helps you to set up the IBM HTTP Server to support the use of
X.509 electronic client certificates through SSL. It covers using the Domino
Certificate Authority as a tool to create client as well as server certificates for
your test environment. At some point, your organization will have to decide on
(or has already decided) the source of certificates for production use, either
internal or external.
The certificates topic in Domino is relatively complex because of the
variations introduced by the use of Notes and/or Internet clients, the use of
certificates with protocols other than https, cross-certification issues, etc. The
intent of this chapter is to provide the minimum level of security needed to set
up electronic client certificates to be used for test with the connector.
For a more in-depth perspective of the topic, refer to the following
publications:
•
•
•
•
Administering the Domino System R5 Volume 1, CT6T7NA
Administering the Domino System R5 Volume 2, CT6T8NA
Lotus Notes and Domino R5 Security Infrastructure Revealed, SG24-5341
OS/390 e-business Infrastructure: IBM HTTP Server 5.1 for OS/390 Customization and Usage, SG24-5603
8.1 Setting up the Domino Certificate Authority
The process of creating a Domino Certificate Authority in the Domino/390
environment is very similar to that used on other Domino platforms, with just
some small differences caused by fact that the Notes client is running
somewhere else and not within the OS/390 system.
In this section we describe how to set up the Domino Certificate Authority
application in the Domino/390 Server Domweb1/itsoweb. Since the CA
application is a Web application, we have two choices for the access path:
the Domino built-in http task, or using the IBM HTTP Server when in a
Domino for IBM HTTP Server configuration. In either case, access will
normally take place under SSL protection.
The following process assumes that neither the IBM HTTP Server nor the
Domino HTTP task are set up for SSL.
© Copyright IBM Corp. 2000
111
8.1.1 Creating the Domino Certificate Authority application
From the Domino Designer client, click File->Database->New to create the
Domino Certificate Authority database. Be sure to select the server (in our
case Domweb1/Itsoweb) and the Domino R5 Certificate Authority
(CCA50.NTF) from the template list after setting the Show Advanced
Templates checkbox as displayed in Figure 42.
Figure 42. Create Domino database authority
Exit the database immediately, once it opens, and proceed to edit the
database Access Control List:
• Include the names of the administrators who will be involved in the
process of managing electronic certificates. Assign the Editor attribute to
each of them and allow Delete access and the [CAPrivledge] role.
• Set the -Default- to Author with Create access.
8.1.2 Creating the Certificate Authority key ring and certificate
In this step we will actually create the self-signed certificate to be used as
the internal Certificate Authority (CA). It will be stored in a
password-protected binary format key ring. If the Domino Certificate
Authority being created is to be used for other than test purposes, it is
obvious that proper steps should be taken to provide physical security for
the objects. The following steps will create the database (key ring):
• Working from the Domino Administrator client, open the Domino
Certificate Authority application database; see Figure 43 on page 113.
112
Domino for S/390 and Web Server Integration
• Select Create Certificate Authority Key Ring & Certificate.
Figure 43. Create Certificate Authority key ring
• Fill in the values in the form as shown in Figure 43. There are three
values that deserve some explanation here.
• Key ring file name: This file will be created in the disk of the client
machine where the Domino Administrator is running. You must
specify the fully qualified path and file name; .kyr is the suggested
extension.
• Key size: This value defines the length of each of the keys in the
key pair to be generated.
• Common Name: This identifies, in a descriptive way, the CA entity.
• Click Create Certificate Authority Key Ring.
• Verify the information about the file and CA name and click OK.
Setting up client certificates
113
If this was done for a production environment, this would be the point to
make backups of the key ring file and store them in a secure location.
8.1.3 Configuring the Domino Certificate Authority profile
Once the Certificate Authority key ring and certificate have been created,
you can proceed to configure the Certificate Authority application by
following these steps:
• Working from the Domino Administrator, open the Domino Certificate
Authority application (if not already open).
• Select Configure Certificate Authority Profile.
• Fill in the values in the form. Since you may not want to make use of
Certificate Authority-generated e-mail notifications with embedded URL
for the requestors to pick up the signed certificates, you may choose to
leave blank most of the fields.
• Click Save & Close.
At this point, the Domino Certificate Authority is fully configured and ready
to be used.
8.1.4 Setting up SSL on the Domino CA server
Once the Domino CA is in operation, users will use a browser to access the
CA to request or pick up certificates. Because of this, it is common practice to
use SSL to protect the CA, although this is not mandatory in a test
environment.
In theory, if the intent is to set up the Domino for IBM HTTP Server, you would
not need to set up the http task of the Domino server where the Certificate
Authority resides, much less to secure it with SSL. You could access the CA
through the Web connector even if the IBM HTTP Server is not secure. In
fact, you could access the CA, process a server certificate request for the
IBM HTTP Server, and then re-start the IBM HTTP Server in secure mode
with the newly signed certificate.
In practice, however, you may want to set up the Domino HTTP task with
SSL, because at times it may be of value to be able to compare Web pages
served through both paths, the IBM HTTP Server and Domino built-in http
task. You can set up SSL as follows:
• Working from the Domino Administrator client, open the Domino
Certificate Authority application (if not already open).
• Select Create Server Key Ring & Certificate.
114
Domino for S/390 and Web Server Integration
Figure 44. Creating CA server key ring
Setting up client certificates
115
• As shown in Figure 44 on page 115 (where we have included the fully
scroll panel by combining two picture), fill in the values in the form as
appropriate. Select key size and assign a label for identification of the
CA certificate in the key ring. For the Common Name, be sure to
provide the fully qualified server’s TCP/IP domain name
(domweb1.itso.ibm.com in our case).
• Click Create Sever Key Ring. You will be prompted for the CA
password.
• Now that the key ring has been created in the disk drive of the
workstation, you need to transfer it to the notesdata directory of the
Domino/390 server. On a Command Prompt window, switch to the
directory where the files were created and start an FTP session in
binary mode. We used the server ID for this operation; see Figure 45.
D:\Notes\Data\ca>ftp domweb1
Connected to domweb1.
220-FTPD1 IBM FTP CS V2R7 at wtsc59oe.itso.ibm.com, 16:00:40 on 1999-09220 Connection will close if idle for more than 30 minutes.
User (domweb1:(none)): domino
331 Send password please.
Password:
230 DOMINO is logged on. Working directory is "/u/domino".
ftp> cd /notesdata1/sec
250 HFS directory /notesdata1/sec is the current working directory
ftp> bin
200 Representation type is Image
ftp> put domweb1_cakey.kyr
200 Port request OK.
125 Storing data set /notesdata1/sec/domweb1_keyfile.kyr
250 Transfer completed successfully.
8715 bytes sent in 3.25 seconds (2.69 Kbytes/sec)
ftp> put domweb1_cakey.sth
200 Port request OK.
125 Storing data set /notesdata1/sec/domweb1_keyfile.sth
250 Transfer completed successfully.
129 bytes sent in 0.00 seconds (129000.00 Kbytes/sec)
ftp> bye
221 Quit command received. Goodbye.
Figure 45. Transferring the key ring using FTP
You can now set up the CA server to allow SSL connections. Go to the server
document Ports - Internet Ports - Web. Provide the SSL key file name and
other pertinent options. For more information, consult Administering the
Domino System R5.
Once this is done, you can recycle the Domino server and load the HTTP task
to make the certificate application available to browsers.
116
Domino for S/390 and Web Server Integration
Note that with this setup, Domweb1/Itsoweb will be running SSL with the
identity of the Domino Certificate Authority. If you want to hide that identity,
you can create a new server key ring by using the Server Certification
Administration application (CERTSRV.NSF) in a very similar way. If you need
to do so, refer to Administering the Domino System R5.
8.2 Creating client certificates
In this section we cover how to issue X.509 client certificates to users in the
Domino directory. For simplicity, these users will be defined in the directory as
person entries, and not actual Notes registered users.
8.2.1 Creating a Person entry in Domino directory
From the Domino Administrator, select File->Open Server and choose the
proper server to administer the Domino Directory (in our case
Domweb1/Itsoweb). Then to create a new Person entry, select People &
Groups, People, Add Person and proceed to fill in the fields.
Setting up client certificates
117
Figure 46. Creating a new Person entry
If you intend to allow this person to use Internet mail, you will need to fill in
the mail section and create the mail database with the proper template. Once
you have provided all the information required, click Save & Close.
This process can be repeated for as many test users as required.
8.2.2 Requesting the client certificate
Now it is time to request a client certficate for the new person. We used
Netscape Communicator.
In general, this request should be run from the workstation where the user
would be using it. In our case, because it was done for testing purposes, the
request was made from the same workstation that we used for the entire
project.
118
Domino for S/390 and Web Server Integration
You might also find yourself having to make a certificate request from your
own workstation, and you want to keep your personal Netscape environment
separated from the test users you may be setting up. For this reason, we start
with a tip on how to set up multiple Communicator profiles.
8.2.2.1 Setting up multiple Communcator profiles
• From the bottom left corner of the Windows desktop, navigate through
Start->Programs->Netscape Communicator->Utilities->User Profile
Manager.
• Then select New and fill in the user name and later on change the default
profile name to the same user name (in our case we used Carl Jensen for
both of them). Disregard any input fields you are not concerned with (mail,
news...). This will set up a new user environment. Close the Navigator
window, once complete.
• In the Windows desktop, create an additional instance or copy of the
Netscape shortcut. Right-click in this shortcut and open its properties
window. You can customize the shortcut to evoke a specific profile by
appending -P"profile name" (in our case -P"Carl Jensen") to the program
target value.
You can create as many profiles and shortcuts as needed to directly invoke a
user’s browser session.
Now, after starting the browser (for Carl Jensen, in our case) from the
desktop shortcut , proceed to request the certificate:
• Type the proper URL to access the Domino CA. In our case, this was:
https://domweb1:8261/ca/itso_ca.nsf
The SSL port in Domweb1/itsoweb is set to 8261.
• Since the CA is not known to the browser, it is normal to receive the New
Site Certificate warning. Follow the browser instruction to accept the
certificate.
• Once in the Domino Certificate Authority Web page, click Request Client
Certificate in the left pane.
• Type the user’s information, as appropriate.
Setting up client certificates
119
Figure 47. Request a client certificate
• Click Submit Certificate Request to pass the request to the Domino CA.
• Assign a password to protect the client certificate in the browser.
Netscape will prompt the user for the password when needed.
• A page will display the information submitted with the certificate request.
At this point, the request has been submitted and is pending approval by the
CA, which is the next piece of action that must take place.
8.2.3 Signing the certificate and adding it to the Domino directory
Now it is time to process the client certificate request and either approve or
reject it. At the same time that it is approved, the certificate can be added to
the Domino directory. In this way, whenever the certificate is presented in a
120
Domino for S/390 and Web Server Integration
Web client request to the Domino server, the user can be authenticated and
mapped to a user in the Domino directory.
• Working from the Domino Administrator client, open the Domino
Certificate Authority application database.
• Click Client Certificate Requests in the left panel.
• Open the request to be handled by double-clicking it.
• Once in the Client Certificate Request Approval form, review the
submitted information to be sure that it complies with the organization’s
certification policy.
• Keep the checkbox selected to Register Certificate in the Public
Address Book, and make sure that the selected address book entry is
the proper one.
• If the request is to be denied, click Deny after providing a reason in the
comment field.
• To approve the request, fill in the Validity Period and write down the
Pickup ID before selecting Approve.
8.2.4 Merging the signed client certificate
In other circumstances, the client would use the e-mail notification to retrieve
the signed certificate; but in our case, we used the Pickup ID obtained in the
previous section.
• Once again, type the proper URL to access the Domino CA; we used:
https://domweb1:8261/ca/itso_ca.nsf
• Click Pick Up Client Certificate.
• Enter the Pickup ID from the previous section and click Pick Up Signed
Certificate.
• The browser will display the signed certificate information. If appropriate,
click Accept Certificate. You will have to provide the certificate password
that was assigned in an earlier section.
Setting up client certificates
121
Figure 48. Pick up signed client certificate
At this point the certificate request process for the Internet client is complete.
Using Communicator, you can view it by selecting
Communicator->Tools->Security Info, and then Yours, View.
8.2.5 Accepting the Domino CA in the client’s browser
While you are accessing the Domino Certificate Authority from the browser,
as in 8.2.2, “Requesting the client certificate” on page 118, you may want to
accept the the Domino CA as a trusted root. Earlier on, when you accessed
the Domino CA for the first time, you were presented with a new site warning
and given the option to accept it. Accepting it, however, even forever, does
not set that site as trusted root CA; it just sets it as a trusted site.
Here we can accept the trusted root certificate of the Domino CA by clicking
Accept This Authority In Your browser on the left panel of the Domino
122
Domino for S/390 and Web Server Integration
Certificate Authority Web page. This presents a new page with information
about the authority and the option to accept it. Once this is done, the
certificate entry will appear in the list of certificate signers of the
Communicator Security Info.
8.3 Adding the Domino CA trusted root to the HTTP Server
If you are using the Domino Certificate Authority to issue certificates to
Internet clients and you are going to accept these certificates through the IBM
HTTP Server, you need to add the Domino CA certificate as trusted root to
this server’s key ring.
1. First you need to obtain the Domino CA certificate, saving it in the
windows clipboard:
• Using the browser, type the proper URL to access the Domino CA; we
used:
https://domweb1:8261/ca/itso_ca.nsf
• On the left panel, click Accept This Authority In Your Server. This will
display a page with the trusted root certificate.
• Select the certificate text by sweeping it with the mouse, and copy it to the
clipboard. This operation must include both the Begin Certificate and End
Certificate lines.
Setting up client certificates
123
Figure 49. Certificate pickup
2. Create a OS/390 UNIX System Services HFS file and paste the certificate
from the clipboard.
• Switch to the USS shell terminal session and start OEDIT with a
non-existent file. The file name is not significant. (From the command
line, we issued oedit trusted.root).
• Paste the content of the clipboard into the OEDIT screen. Be sure that
the whole certificate is pasted properly, including the delimiter lines.
Save the trusted.root file and exit.
3. Store the CA trusted certificate in the HTTP Server ring.
• Start IKEYMAN and select option 2 to open the server’s key ring
database.
• Choose option 6 to store the CA certificate.
124
Domino for S/390 and Web Server Integration
Current key database is /web/webdom1/sec/webdom1_httpkey.kdb
1
2
3
4
5
6
7
8
9
10
11
-
List/Manage keys and certificates
List/Manage request keys
Create new key pair and certificate request
Receive a certificate issued for your request
Create a self-signed certificate
Store a CA certificate
Show the default key
Import keys
Export keys
List all trusted CAs
Store encrypted database password
0 - Exit program
Enter option number (or press ENTER to return to the parent menu): 6
Enter certificate file name or press ENTER for "cert.arm": itso_domca_root.txt
Enter a label for this key................> Domino CA
Please wait while certificate is stored...
Your request has completed successfully, exit ikeyman? (1 = yes, 0 = no) [0]:
At this point the CA certificate has been stored. It can be verified by selecting
option 10 to List all trusted CAs.
8.4 Setting up the Domino Server to accept electronic certificates
By default, the Domino server setup of the built-in http task does not accept
electronic certificates in the SSL port. To enable it to do so, do the following:
• From the Domino Administrator, select the directory in the appropriate
Domino server and click the Configuration tab.
• In the All Servers Documents view, open for edit the appropriate server
document.
• Select Ports, Internet Ports, Web and scroll to the bottom, to the Web
(HTTP/HTTPS) section.
• Set Client Certificate to YES in the Authentication Options of SSL Port.
• Save and close.
When this is done, shut down and restart the Domino server to pick up the
new setup. The next time a Web client presents a certificate, Domino will
perform the standard client certificate processing. This processing involves
Setting up client certificates
125
determining if the user is trusted and authenticating the user by mapping the
certificate through the Domino directory.
8.5 Setting up the IBM HTTP Server to accept electronic certificates
By default, the IBM HTTP Server is not enabled to accept client certificates
through the secure SSL port. Assuming that the HTTP server has been
properly set up for use of SSL as described in Chapter 7, “Setting up a secure
Web server” on page 97, the use of client certificates can be enabled by
editing the server’s configuration file, httpd.conf, and setting the
SSLClientAuth directive local:
SSLClientAuth local
The default for this directive is off. Setting this value to local instructs the
IBM HTTP Server to request client certificates from browsers when they
establish an SSL connection with the server. With this setting, the IBM HTTP
Server validates the certificates provided by the clients by checking that the
certificates are signed by a trusted CA.
Note
Do not set the SSLClientAuth directive to passthru. This setting is intended
for GWAPI or CGI applications that perform their own certificate
processing. That is not the case for the Domino for IBM HTTP Server,
which relies on the IBM HTTP Server to handle the trustworthiness of the
certificate.
126
Domino for S/390 and Web Server Integration
Chapter 9. Configuration scenarios
As soon as we have the ability to run a Domino for IBM HTTP Server, we are
confronted with a number of questions related to possible configurations.
• Is it possible to run two or more of them in an OS/390 image? If so, what
would be the reason for doing so?
• Is it possible to connect more than one IBM HTTP Server to a Domino
server? If so, would there be an advantage in doing it?
Although the scope of the project did not allow for in-depth research to
answer these questions, we were able to implement some basic
configurations and explore some of the reasons why a specific configuration
might be implemented.
This chapter describes the scenarios that we implemented and their
configuration information, along with considerations of why you could benefit
from the scenario. Also included are sample configuration members.
We tested the following configurations:
1. A minimum configuration where an IBM HTTP Server with the Web
connector provides client connectivity to a Domino Server. It is discussed
in 9.2, “Basic Domino for IBM HTTP Server configuration” on page 131.
2. Two or more separate sets of IBM HTTP and Domino servers with the
corresponding connectors is described in 9.3, “Multiple instances of the
Domino for IBM HTTP Server” on page 134.
3. Two or more IBM HTTP Servers to one Domino Server is discussed in 9.4,
“Two or more IBM HTTP Servers connected to one Domino server” on
page 139.
9.1 Configuration considerations
Before getting into specific configurations, there are a number of
considerations you should be aware of, as follows.
9.1.1 TCP/IP addresses/ports when running multiple servers
In general, on a given TCP/IP stack, only one application can listen on a
particular TCP/IP address and port combination. Attempts by other
applications to listen on the same address/port combination will fail. The
same applies to the OS/390 TCP/IP stack; although it is true that there is a
© Copyright IBM Corp. 2000
127
Port Sharing configuration option, its use is limited to very specific
circumstances and will not be considered here.
On the other hand, there are a number of ways to configure the OS/390
TCP/IP stack in such a way that it supports two or more TCP/IP addresses,
which is sometimes referred to as a multi-homed host.
When a server, which is just a TCP/IP application, opens a socket to listen on
a port, it can do so by using generic or specific bind. Using specific bind, the
server identifies the address:port combination to be used, leaving the same
port available on any additional stack addresses. Using generic bind, the
server just identifies the port on which to listen but not the address, resulting
in binding to that port on all available IP addresses in the stack, thus
preventing other servers from using the same port on any of the addresses.
Practically speaking, there are two common approaches to running multiple
servers on the same stack:
• Assign each server a different IP address. This allows all servers to listen
on the standard port, like port 80 for HTTP protocol.
• Share an IP address either with specific bind or not, but assign to each
server a different port to listen on. This saves IP addresses but, other than
for test purposes or very specific situations, it is not a workable production
solution because application clients normally talk to servers using the
protocol standard port, like port 80 for HTTP.
In our residency, because we shared the environment with other on-going
projects, we normally assigned a different port to each server with no specific
bind. Specific bind with different IP addresses was only used when needed.
9.1.2 Same IP address on both servers
It should be no problem to use the same IP address for both the IBM HTTP
server and the Domino server, provided they do not use the same ports. Most
commonly, this will be the case, with one listening on port 80 for HTTP and
the other on port 1352 for NRPC protocol.
9.1.3 Supporting HTTP on both servers
The Domino for IBM HTTP Server configuration provides an alternate HTTP
path for Domino, but it does not prevent you from running the Domino built-in
HTTP task. If you wish to run both applications simultaneously, you must
configure them to use different IP address:port combinations since, as
explained before, only one application can listen on a given combination at a
time.
128
Domino for S/390 and Web Server Integration
9.1.4 Domain name server support
Although it is possible to access the servers by using their numeric IP
addresses, in practice each address should be mapped into a DNS entry.
9.1.5 Client authentication options
The Domino for IBM HTTP Server connector fully supports the same Web
user authentication process as does Domino’s built-in HTTP task for
authenticating Web users access to protected databases. In addition, the
Web connector provides optional OS/390 authentication support, extending
the Web user authentication process to allow OS/390 user IDs and
passwords, and/or electronic certificates managed by RACF, to be used to
verify a user’s identity. For a detailed description of the authentication
process refer to Chapter 6, “OS/390 authentication support for Domino” on
page 79.
9.1.6 Server start/stop
Due to the way that Domino and the Domino for IBM HTTP Server connector
share data, it is necessary to stop (and then later restart) the IBM HTTP
Server instance that is running the Web connector any time the Domino
Server is being stopped, or terminates abnormally.
This requirement may impact the availability of other applications being
hosted by the same instance of the IBM HTTP Server as the one in which the
connector is running. This must be taken into consideration to determine if it
is operationally acceptable to host other than the Domino application(s) from
the IBM HTTP configured with Domino.
We recommend that you do not run the Web connector in the same IBM
HTTP Server instance as other applications with critical availability
requirements. Instead, you should set up a separate IBM HTTP Server
instance for hosting Web access for Domino databases via the Web
connector.
9.1.7 Scalable Web server considerations
There are special considerations in the case of an IBM HTTP Server running
as a scalable Web server. If the related Domino server is to be stopped, it is
also necessary to stop the WLM Application Environments (APPLENVs)
being used to process Web connector requests. Stopping the IBM HTTP
Server instance is required in order to terminate the Web connector so that
the IPC resources used to share data between the Domino server and the
connector can be properly cleaned up. This IPC cleanup is required before
Configuration scenarios
129
the Domino server and the Domino for IBM HTTP Server connector can be
successfully restarted.
This requirement may impact the availability of other applications being
hosted by the same instance of the IBM HTTP Server as the one in which the
connector is running. With the scalable configuration the scope of effect is
expanded. As stated earlier, we recommend that you do not run the
connector in the same IBM HTTP Server instance as other applications with
critical availability requirements. In addition, if you are running the IBM HTTP
Server as a scalable server, you should set up a separate WLM Application
Environment (APPLENV) and corresponding IBM HTTP Server queue server
processes for processing the Web connector workload.
See IBM HTTP Server: Planning Installing and Using, SC31-8690 and
OS/390 e-business Infrastructure: IBM HTTP Server 5.1 - Customization and
Usage, SG24-5603 for information on setting IBM HTTP Server in scalable
mode.
9.1.8 Internet cluster manager
Since the Domino Internet cluster manager is implemented in the Domino
built-in HTTP task, it is not available when this task is removed from the
requests path in the Domino for IBM HTTP Server configuration.
9.1.9 One connector to one Domino server
While it is possible to configure a Domino for IBM HTTP Server with two or
more IBM HTTP Servers connected to the same Domino server, it is not
possible to configure the Domino for IBM HTTP Server with one HTTP server
connected to two or more Domino servers. From a given IBM HTTP Server,
you can only connect to a Domino server.
At first glance, it might seem that such a configuration would be desirable, for
scalability purposes, in order to spread the workload. However, after looking
into the design of the Web connector, it becomes obvious that this is not so.
The connector moves the actual processing of client requests from the
Domino HTTP task to the IBM HTTP Server address space. (Think of it as
program calls to Domino code under the corresponding client thread.) All the
work is done within the process. Connecting this process to another Domino
server would add workload to the IBM HTTP Server, not spread it, and as
such would provide no relief or scalability advantage.
130
Domino for S/390 and Web Server Integration
9.2 Basic Domino for IBM HTTP Server configuration
This is the simplest configuration in which one IBM HTTP Server is connected
to a Domino server. It is a fully functional solution which may be sufficient for
the practical deployment of an application. It is also the starting point for
installation, configuration, and test of larger configurations. A good practice
when implementing this solution is to consider the installation of the IBM
HTTP and Domino servers as separate entities. Test them as such and then
implement the Web connector, making sure they are all working together.
Figure 50. Basic Domino for IBM HTTP Server
As depicted in Figure 50, which illustrates this basic configuration, we have
chosen to use RACF authentication, but it could as well been left to Domino.
In 9.3, “Multiple instances of the Domino for IBM HTTP Server” on page 134,
we show how to configure the Web connector for basic Domino
authentication.
Configuration scenarios
131
9.2.1 Sample configuration: Basic Domino for IBM HTTP Server
This section includes the highlights of the sample configuration. To better
focus on the connector definition, we show only the sections of definitions
that are relevant. Table 8 contains the most significant configuration
parameters, like user IDs, server and host names and file directories used in
the configuration. Although in our tests we used non-standard ports, here, to
avoid any confusion, we decided to list in the table the standard port values.
Table 8. Basic Domino for IBM HTTP Server sample configuration parameters
Parameter
Configuration Values
Domino data directory
/notesdata1
Domino product installation directory
/usr/lpp/lotus
Domino Server user ID (RACF)
DOMINO1
Domino UNIX group
NOTESGRP
Domino Server name
domweb1/ITSOweb
Domino Server TCP host name
domweb1.itso.ibm.com
Domino Server port (http)
8080 (Debug only purposes)
Domino Server SSL port (https)
8443 (Debug only purposes)
IBM HTTP Server user ID
WEBSRV
IBM HTTP Server UNIX group
IMWEB
IBM HTTP TCP host name
domweb1.itso.ibm.com
IBM HTTP Server port (http)
80
IBM HTTP Server SSL port (https)
443
Connector authentication
RACF
You will notice that the list contains ports for the Domino built-in HTTP task.
In our tests we found that, for debugging purposes, it was helpful to start the
Domino internal HTTP task simultaneously with the IBM HTTP Server. To do
so we assigned a pair of non-standard ports, which allowed us to point the
browser to either HTTP server. The need for this should be obvious since
only one server can listen on a particular address and port combination at any
given time.
As an alternative, we could have assigned different TCP/IP stack addresses
and host domain names to each of the servers, setting the ports to the
standard values. Chapter 10, “Migrating to the Domino for IBM HTTP Server”
132
Domino for S/390 and Web Server Integration
on page 143 includes details about how to use both HTTP paths to migrate
applications.
The relevant segments of httpd.conf and httpd.envvars for the IBM HTTP
Server 1 connector are documented in Figures 51 and 52. The parameter
values from Table 8 on page 132 have been integrated into the segments of
httpd.conf and httpd.envvars files, with some significant values shown in bold.
PATH=/bin:.:/usr/sbin:/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/
lpp/ldap/bin:/usr/lpp/java/J1.1.6/J1.1/bin:/notesdata1:
/usr/lpp/lotus/notes/latest/os390:/usr/lpp/lotus/notes/latest/os390/res/C:
LIBPATH=/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/lpp/ldap/lib:
/usr/lpp/java/J1.1.6/J1.1/lib/mvs/native_threads:
/usr/lpp/lotus/notes/latest/os390
Figure 51. Section of httpd.envvars for IBM HTTP sample 1
To help understand the difference in implementing each type of
authentication, note that only the ServerInit statement is affected, with the
-platcreds allow keywords enabling the RACF option. For more details about
the authentication options refer to Chapter 6, “OS/390 authentication support
for Domino” on page 79.
Port 8230
ServerInit /usr/lpp/lotus/notes/latest/os390/domihttp:ServerInit "-sslport 443 -platcreds allow"
Protection DOMINO-CONNECTOR-SETUP {
Mask
Anybody
UserID
DOMINO1
}
NameTrans /icons/*
NameTrans /
/usr/lpp/lotus/notes/latest/os390/domihttp:DomIcons
/usr/lpp/lotus/notes/latest/os390/domihttp:DomRootCmds
Protect
Protect
Protect
Protect
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
*.nsf
*.nsf/*
/domicons/*
/domjava/*
Service
*.nsf
Service
*.nsf/*
ServerTerm
/usr/lpp/lotus/notes/latest/os390/domihttp:Service
/usr/lpp/lotus/notes/latest/os390/domihttp:Service
/usr/lpp/lotus/notes/latest/os390/domihttp:ServerTerm
Pass
Pass
/notesdata1/domino/icons/*
/notesdata1/domino/java/*
/domicons/*
/domjava/*
Figure 52. httpd.conf for IBM HTTP sample 1 with standard Domino authentication
Configuration scenarios
133
9.3 Multiple instances of the Domino for IBM HTTP Server
Multiple instances of the Domino for IBM HTTP Server can be installed in a
given LPAR or in different LPARs, provided enough resources are available.
As is illustrated in Figure 53, this entails isolated sets, each with an IBM
HTTP Server connected to a Domino server in a Domino for IBM HTTP
Server configuration. In such environment, the Domino servers may or may
not be part of the same Notes domain.
Figure 53. Two separate instances of the Domino for IBM HTTP Server
During the residency we discussed why multiple instances would be of value.
There are a number of arguments that can make a case for this scenario and
whatever they are, they will make the assumption that the client requests can
be routed to the proper target instance by whichever means, the simplest
being the use of different URLs. Although we classified the reasons into three
categories, normally, in a practical situation, a combination of them is what
leads to two or more instances.
134
Domino for S/390 and Web Server Integration
Some reasons for using multiple instances of the Domino for IBM HTTP
Server are:
1. Application separation
• It might simply be desirable to separate two applications (for example,
the human resource applications from HTTP mail serving).
• Intranet vs. internet: There is no need to host internal applications for
Internet access. Why not place them in separate servers?
• Easy of maintenance: Keeping applications in separate servers can
simplify maintenance by allowing each organization to manage its own
applications. Also, the effect of service outages, planned or not, can be
isolated to specific application areas.
• Critical applications vs. non-critical: Keeping critical applications in
their own environments can lead to their stability. Scheduling of
changes to less critical applications in other environments becomes
less of an issue.
2. Security considerations
• Intranet vs. internet: There is no need to expose internal applications to
accessibility from the Internet.
• Different authentication mechanisms: These may be desirable for
different user populations, or the security clearance levels of two
applications may simply require it. For example, one Domino for IBM
HTTP Server could provide OS/390 authentication support, checking
the Web user credentials against OS/390 user IDs and passwords,
while the other Domino for IBM HTTP Server would check the
credentials against the Domino directory. One server could use RACF
for employees, the other server could use Domino authentication for
customers. Or you could use RACF for intranet purposes and
Domino-managed X.509 client certificates for Internet access.
3. Performance and tuning
• Workload isolation: Separating different types of workloads makes the
environment more manageable. By segregating light transactions from
heavy long-running ones, tuning can be done and resources can be
directed to provide adequate service levels.
• Scalability: When design allows, an application workload can be spread
across two or more instances. This is the only way to provide scalability
where transaction volume and characteristics result in exhaustion of
interprocess communication shared memory resources.
Configuration scenarios
135
• Different authentication for different users: If two user populations with
different authentication types (RACF and Domino) are supported under
the same Domino for IBM HTTP Server, unnecessary cycles will be
used in to the attempt to authenticate the non-RACF users against
RACF before they are authenticated against the Domino directory. This
overhead has not been quantified and is probably rather small, but
nonetheless it could be avoided by separating the users into two
different servers, each with the proper authentication type.
As a final comment to the previous arguments, it is important to remember
that if the same database application is hosted through two separate servers,
care must be taken to ensure that the nature and dynamics of the data allow
for this configuration. For example, an online customer registration
application could be acceptable, but warehouse inventory would not be.
9.3.1 Sample configuration: Second Domino for IBM HTTP Server
In our test environment we had two Domino for IBM HTTP Server instances
as shown in Figure 53 on page 134, with the parameter values depicted in
Table 9. We have already covered the configuration of Server #1 in 9.2.1,
“Sample configuration: Basic Domino for IBM HTTP Server” on page 132. In
this section, we cover the Domino for IBM HTTP Server #2, which will use
basic Domino authentication.
Table 9. Second Domino for IBM HTTP Server sample configuration parameters
Parameter
Server #1
Domino binaries directory
/usr/lpp/lotus
Domino data directory
/notesdata1
/notesdata2
Domino Server user ID (RACF)
DOMINO1
DOMINO2
Domino UNIX group
NOTESGRP
Domino Server name
domweb1/ITSOweb
domweb2/ITSOweb
Domino Server TCP host name
domweb1.itso.ibm.com
domweb2.itso.ibm.com
Domino Server port (http)
8080 (for debug only)
not used
Domino Server SSL port(https)
8443 (for debug only)
not used
IBM HTTP Server user ID (RACF)
IBM HTTP Server UNIX group
IBM HTTP TCP host name
136
Server #2
Domino for S/390 and Web Server Integration
WEBSRV
IMWEB
domweb1.itso.ibm.com
domweb2.itso.ibm.com
Parameter
Server #1
Server #2
IBM HTTP Server port (http)
80
80
IBM HTTP Server SSL port(https)
443
443
Connector authentication
RACF
Domino
Note that, for clarity, Table 9 shows each of the Domino for IBM HTTP Servers
with a different host name and implied address and making use of standard
ports. In addition, each pair of servers, Domino and IBM HTTP, can use the
same host name and implied IP address. This is not mandatory but is
probably a good practice to follow whenever possible.
The differences or changes to httpd.envvars and httpd.conf needed to
customize the second server are minimal, affecting only the values of
notesdata path, Domino user ID, and hostname. Figures 54 and 55 on page
138 present abstracts of these two files with /notesdata2, DOMINO2, and
domweb2 properly substituted.
PATH=/bin:.:/usr/sbin:/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/
lpp/ldap/bin:/usr/lpp/java/J1.1.6/J1.1/bin:/notesdata2:
/usr/lpp/lotus/notes/latest/os390:/usr/lpp/lotus/notes/latest/os390/res/C:
LIBPATH=/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/lpp/ldap/lib:
/usr/lpp/java/J1.1.6/J1.1/lib/mvs/native_threads:
/usr/lpp/lotus/notes/latest/os390
Figure 54. Section of httpd.envvars for IBM HTTP sample 2
Configuration scenarios
137
Hostname domweb2.itso.ibm.com
BindSpecific on
Port 80
ServerInit /usr/lpp/lotus/notes/latest/os390/domihttp:ServerInit "-sslport 443"
Protection DOMINO-CONNECTOR-SETUP {
Mask
Anybody
UserID
DOMINO2
}
NameTrans /icons/*
NameTrans /
/usr/lpp/lotus/notes/latest/os390/domihttp:DomIcons
/usr/lpp/lotus/notes/latest/os390/domihttp:DomRootCmds
Protect
Protect
Protect
Protect
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
*.nsf
*.nsf/*
/domicons/*
/domjava/*
Service
/*.nsf
Service
/*.nsf/*
ServerTerm
/usr/lpp/lotus/notes/latest/os390/domihttp:Service
/usr/lpp/lotus/notes/latest/os390/domihttp:Service
/usr/lpp/lotus/notes/latest/os390/domihttp:ServerTerm
Pass
Pass
/notesdata2/domino/icons/*
/notesdata2/domino/java/*
/domicons/*
/domjava/*
Figure 55. Section of httpd.conf for IBM HTTP sample 2
The basic Domino authentication is set by default. Just omitting the words
-platcreds allow from the tail end of the ServerInit statement disables RACF
authentication, allowing it default to Domino.
138
Domino for S/390 and Web Server Integration
9.4 Two or more IBM HTTP Servers connected to one Domino server
As shown in Figures 56 and Figure 57 on page 140, it is possible to configure
more than one IBM HTTP Server connected to the same Domino server,
creating what could appear to be a multi-headed Domino for IBM HTTP
Server. But since the *.nsf HTTP client requests for a Domino for IBM HTTP
Server are executed within the Web connector, in a IBM HTTP Server
process it would be more appropriate to depict it as a number of Domino for
IBM HTTP Servers which are standing on a common pair of feet, the Domino
server.
Figure 56. Two IBM HTTP Servers to one Domino server
9.4.1 Configuration Considerations
Whichever way you choose to depict this complex installation, it is worth
clarifying some details:
• All “heads”, or IBM HTTP Servers, see the same set of data, as opposed
to possible database replicas if full separate instances were implemented.
Configuration scenarios
139
• Each IBM HTTP Server has the ability to fully execute the client requests
because the client threads actually run in the IBM HTTP Server address
space.
However, it is not clear to us that this is a scalability advantage because
the process by definition is multi-threaded. Another “head” would add
more threads, but a similar effect could be attained by doubling the
threads in the first head. In our opinion only the exhaustion of a resource
within the first server would make spawning a new head advantageous.
• The weak link is in the sharing of resources though the common Domino
server, in particular, locks and shared memory. Using locks affects overall
performance (CPU and response time), and using shared memory results
in a possible saturation of shared storage used for session control blocks.
• Each IBM HTTP Server can implement different security schemes: RACF
or Domino authentication.
• From an operational perspective, both server members, the IBM HTTP
Server and Domino, must start and stop in a coordinated way. This can be
a critical operational requirement.
Figure 57. Multiple IBM HTTP Servers to one Domino server
140
Domino for S/390 and Web Server Integration
Using these considerations as a filter, you can refer to 9.3, “Multiple instances
of the Domino for IBM HTTP Server” on page 134 and revisit the different
reasons that could be an incentive to implement the configuration considered
here. In general, some of the reasons for application separation or security
will stand, while scalability probably will not.
9.4.2 Sample configuration: Additional IBM HTTP Server
During our tests we implemented this configuration, just to the point where we
were able to determine that it was feasible without running into significant
problems. Table 10 lists the values used. This was one of the very few
instances where we really used specific bind, although on non-standard
ports. Once again, for clarity, the list includes standard port values.
Table 10. Additional IBM HTTP Server sample configuration parameters
Parameter
HTTP #1
HTTP #2
Domino Data directory
/notesdata1
Domino binaries directory
/usr/lpp/lotus
Domino Server user ID (RACF)
DOMINO1
Domino UNIX group
NOTESGRP
Domino Server name
domweb1/ITSOweb
Domino Server TCP host name
domweb1.itso.ibm.com
Domino Server port (http)
8080 (for debug only)
Domino Server SSL port(https)
8443 (for debug only)
IBM HTTP Server user ID (RACF)
WEBSRV
WEBSRV
IBM HTTP Server UNIX group
IMWEB
IMWEB
IBM HTTP TCP host name
domweb1.itso.ibm.com
domweb2.itso.ibm.com
IBM HTTP Server port (http)
80
80
IBM HTTP Server SSL port(https)
443
443
Connector authentication
RACF
Domino
In 9.2.1, “Sample configuration: Basic Domino for IBM HTTP Server” on page
132, we describe the configuration for server #1. We also looked at the IBM
HTTP Server #2, but that was for a different scenario. Although the changes
for this scenario are minimal, we have included, in Figures 58 and Figure 59
on page 142, sections of the configuration files for a second HTTP Server
associated with the same Domino server. If additional servers were planned,
Configuration scenarios
141
the only consideration would be the need for different host names
corresponding to a different IP address, assuming standard ports are being
used. Note that due to the limited scope of our project, we did not test with
more than two servers.
PATH=/bin:.:/usr/sbin:/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/
lpp/ldap/bin:/usr/lpp/java/J1.1.6/J1.1/bin:/notesdata1:/usr/lpp/lotus/notes/latest/
os390:/usr/lpp/lotus/notes/latest/os390/res/C:
LIBPATH=/usr/lpp/internet/bin:/usr/lpp/internet/sbin:/usr/lpp/ldap/lib:
/usr/lpp/java/J1.1.6/J1.1/lib/mvs/native_threads:
/usr/lpp/lotus/notes/latest/os390
Figure 58. Section of httpd.envvars for second (additional) HTTP server
Note that the user ID stays at Domino1 because both connectors are
accessing the same Domino1 server. The same applies to /notesdata1, the
notes data directory.
Hostname domweb2.itso.ibm.com
<= Different IP Address
BindSpecific on
<= For binding to the Hostname
Port 80
<= Only the same as other web servers
when you are using different IP address
ServerInit /usr/lpp/lotus/notes/latest/os390/domihttp:ServerInit "-sslport 443" no ssl port
Protection DOMINO-CONNECTOR-SETUP {
Mask
Anybody
UserID
DOMINO1
}
NameTrans /icons/*
NameTrans /
/usr/lpp/lotus/notes/latest/os390/domihttp:DomIcons
/usr/lpp/lotus/notes/latest/os390/domihttp:DomRootCmds
Protect
Protect
Protect
Protect
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
*.nsf
*.nsf/*
/domicons/*
/domjava/*
Service
/*.nsf
Service
/*.nsf/*
ServerTerm
/usr/lpp/lotus/notes/latest/os390/domihttp:Service
/usr/lpp/lotus/notes/latest/os390/domihttp:Service
/usr/lpp/lotus/notes/latest/os390/domihttp:ServerTerm
Pass
Pass
/notesdata1/domino/icons/*
/notesdata1/domino/java/*
/domicons/*
/domjava/*
Figure 59. Section of httpd.conf for second (additional) IBM HTTP Server
142
Domino for S/390 and Web Server Integration
Chapter 10. Migrating to the Domino for IBM HTTP Server
This chapter covers some considerations related to migrating from native
Domino-based Web serving to using a Domino for IBM HTTP Server
configuration. In real life such a migration could also involve a platform
change, for example from NT to OS/390. However, the scope of the chapter
will be limited to issues related to moving the support for HTTP serving from
Domino to the IBM HTTP Server with the Web connector.
When Domino for IBM HTTP Server comes into the picture, replacing an
existing Domino Web server, there are changes such as these:
• As some pieces of the action move from the Domino side to the IBM HTTP
server side, the related definitions must move also.
• As new functionality comes into perspective, new choices appear with
their corresponding definition requirements.
• With the move, some options may be left behind, or need some
re-engineering to maintain equivalent results.
The following sections will explore some of these areas.
10.1 Security considerations
As explained in depth in Chapter 6, “OS/390 authentication support for
Domino” on page 79, the Domino for IBM HTTP Server brings OS/390
authentication into the picture, but the Domino database access control
scheme remains in place. If authentication is left to Standard Domino,
meaning the OS/390 authentication is not enabled, the process should be
very much the same for it with respect to database access.
If the existing Domino server makes use of Web Configuration documents
defined in the Domino Directory, the entities or functionality defined by them
is not mapped over nor available when the connector is in place. This affects
virtual servers, URL mappings and redirections, realms, and file protection.
With the Web connector, you can protect system files using OS/390 UNIX file
permissions.
© Copyright IBM Corp. 2000
143
10.2 Migrating the configuration
If you have set up Domino using its built-in HTTP server and customized its
HTTP-related settings in the Domino directory, you could use the
configuration merge utility provided with the Domino for IBM HTTP Server
support as an aid in setting up the IBM HTTP Server instance that will run the
Domino for IBM HTTP Server connector. This utility picks up selected
HTTP-related fields from a specified server document in the Domino
directory, and merges these settings into an IBM HTTP Server configuration
file which you can then use as the basis for your continued setup work. This
utility does not attempt a full-scale migration of a Domino Web environment,
but may be useful as a first step in such a migration.
On the other hand, with some experience in the IBM HTTP Server, it should
not be an issue to map the existing Domino definitions into the httpd.conf file.
In our project we performed all configuration by manual editing and did not
use the configuration merge utility.
When the configuration merge utility is used, it is started from a UNIX shell
session and has access, either through defaults or explicit parms, to the
Domino directory, Domino server name, existing HTTP server configuration
file name, and output file name.
A number of fields from the Domino server document will be migrated by the
utility and merged with the provided configuration file. The fields migrated
relate to the areas of TCP/IP ports, client authentication, host name and bind,
active threads, log settings and time-outs.
For detailed information on the use of the configuration merge utility, refer to
the description included in the Domino IBM HTTP Server Guide.
10.3 Features not supported by the Web connector
As described, the Domino for IBM HTTP Server design prevents the use of
some features that would otherwise be available. This may result from
technical incompatibility, or be caused by separation of the HTTP process out
of Domino.
Some of the features not available are:
• Connection request logging on the Domino side.
• Web server API filters.
• Domino Web server API (DSAPI) filters are not supported.
144
Domino for S/390 and Web Server Integration
• Domino Internet Cluster Manager (ICM) is not supported.
• Web configuration documents defined in the Domino directory, that is,
virtual servers, URL mappings and redirections, realms, and file
protection, are not supported. You now can protect system files using
OS/390 UNIX file permissions.
• The Domino Servlet Manager is not supported. However, you can use the
servlet manager provided with the IBM WebSphere Application Server.
• Some options in the Domino server document lose their significance and
setting makes no difference. Others are still used.
We suggest that you check the Domino IBM HTTP Server Guide for a
detailed list of supported features and the current status of the unsupported
features.
10.4 Testing a migrated application
Once the Domino for IBM HTTP Server has been set up and made
operational by migrating a Domino server with an existing Web application, it
is time to test the application and verify that all of its pieces work properly.
Such a test normally involves browsing through the application and checking
different aspects such as page rendering, link integrity, etc.
During our project, we did not have the time to dissect the migration of an
application, but to a point, we had a need to go through similar steps when
testing the connector. Often, we found ourselves having a Domino server with
both the built-in HTTP task and the Web connector started. With the browser,
we would compare access to server databases through both HTTP paths. To
help us with the process, we devised a simple pair of HTML pages that
allowed us to choose the access path and even render both the same pages
simultaneously in parallel frames of the navigator window. Figure 60, “Using
both Domino for IBM HTTP connector & Domino HTTP task” on page 146
illustrates the environment.
Migrating to the Domino for IBM HTTP Server
145
Figure 60. Using both Domino for IBM HTTP connector & Domino HTTP task
A simple initial HTML page that included three links was first established.
One link was used to put requests through the Domino HTTP task, another
link was used to request the Domino for IBM HTTP Server connector, and the
third was used to show two frames, so we could compare the rendering by
the Domino HTTP task with the Domino for IBM HTTP Server connector. The
HTML code is represented in Figure 61 on page 147 and the HTML page is
represented in Figure 62 on page 147.
146
Domino for S/390 and Web Server Integration
<title>Domino for IBM HTTP Server Connector</title>
</head>
<body>
<center><b><u><font size=+3>Domino for IBM HTTP Server Connector</font></u></b>
<hr WIDTH="100%"></center>
<ul><li>
<font size=+2><a href="http://domweb1:8260/?openserver">Access through
the Domino HTTP Task</a></font></li>
</ul>
<hr WIDTH="100%">
<ul><li>
<font size=+2><a href="/?openserver">Access through
the Domino for IBM HTTP Server Connector</a></font></li>
</ul>
<hr WIDTH="100%">
<ul><li>
<font size=+2><a href="/compare/cindex.html">Compare
the Domino HTTP Task to the Domino for IBM HTTP Server Connector</a></font></li>
</ul>
</body>
</html>
Figure 61. HTML code for a Web page with different links
As shown in Figure 61, the Domino HTTP task is accessed within the HTML
code by specifying its port ( http://domweb1:8260/?openserver). However, you
do not need to specify the Domino for IBM HTTP Server connector port
( /?openserver) since you are already using the IBM HTTP Server port when
you are requesting this page (in our case, http://domweb1:8230).
Figure 62. HTML page with links to different servers and comparison
Migrating to the Domino for IBM HTTP Server
147
Finally, another directory called compare was created which was used to hold
the cindex.html page that is described in Figure 63.
You may find it useful to use the comparison HTML code to display the
Domino HTTP task and the Web connector in parallel frames. Figure 63
shows the HTML code that will allow you to display the frames.
<HTML>
<FRAMESET COLS="500,*">
<FRAME MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=AUTO
SRC="http://domweb1:8260/?openserver">
<FRAME SRC="http://domweb1:8230/?openserver" NAME="main">
</FRAMESET>
</HTML>
Figure 63. HTML code to display the comparison in frames
The left frame is filled with HTML from port 8260 (which is the Domino HTTP
task) while the right frame is filled with HTML from port 8230 (which is the
port for the Domino for Web connector). Figure 64 on page 149 displays the
HTML page as a result of the comparison code.
148
Domino for S/390 and Web Server Integration
Figure 64. HTML output to the frames comparison
Migrating to the Domino for IBM HTTP Server
149
150
Domino for S/390 and Web Server Integration
Chapter 11. Troubleshooting
This section contains basic troubleshooting guidelines for the Web connector.
It does not cover problem determination for either Lotus Domino for S/390
Server or IBM HTTP Server. For further information on those topics, refer to
the following redbooks:
• OS/390 e-business Infrastructure: IBM HTTP Server 5.1 Customization
and Usage, SG24-5603
• Lotus Domino for S/390 Release 5: Installation, Customization, and
Administration, SG24-2083
• Lotus Domino for S/390 Release 5: Problem Determination Guide,
SG24-5599
• Debugging UNIX System Services, Lotus Domino, Novell Network
Services, and other Applications on OS/390, SG24-5613
11.1 Domino for IBM HTTP Server dependencies
Domino for IBM HTTP Server is a component of Lotus Domino for OS/390
version 5.0.1. In order to use the Domino for IBM HTTP Server connector
(Web connector), you must have both a Domino for OS/390 Server and an
IBM HTTP Server installed and operating.
11.1.1 Software and required maintenance
The Lotus Domino for OS/390 Server and Web connector requires a minimum
level of OS/390 Version 2 Release 7, and IBM HTTP Server for OS/390
Version 5.1. Proper functioning of the Web connector is dependent upon
correct installation, configuration, and maintenance level of the following:
•
•
•
•
•
•
•
Lotus Domino for OS/390
IBM HTTP Server for 390
Domino for IBM HTTP Server
IBM OS/390 Base
eNetwork Communications Server
OS/390 UNIX System Services
OS/390 Language Environment
The following Web page contains a list of required PTFs for the IBM HTTP
Server:
http://www.ibm.com/software/webservers/httpservers/doc51.html
© Copyright IBM Corp. 2000
151
The following Web page contains a list of required PTFs for the Lotus Domino
for OS/390 Server:
http://www.ibm.com/s390/products/domino/domptf.html
In order to use OS/390 Authentication Services, OS/390 Security Server with
PTFs OW35502 and OW39716, or Solution Developer software with
equivalent capability, is required.
11.1.2 Network
In order for the Domino for IBM HTTP Server connector to access the Domino
server, network connectivity and routing between browser clients and the
Domino for OS/390 host must be established. If the Domino server’s name is
not defined to Domain Name Server, then the Domino server name and IP
address must be added to the S/390 server’s local host file, as well as to the
client workstations’ local hosts files. Note that this may be an unrealistic
approach in a Web client environment.
11.1.3 Security
The Web connector installation documentation contains required resource
definitions. The Web connector requires access to the Domino server’s
/notesdata directory and files. The security definitions allow the Web
connector to behave as a surrogate for the Domino server when it accesses
these files.
The Web connector provides capability to use OS/390 authentication as well
as Domino standard authentication. Whether the user is authenticated with
OS/390 or Domino, once the user’s identity is established, the Notes
database Access Control List (ACL) determines that user’s ability to access
the database.
11.1.4 Availability of system resources
The Domino server for which the Web connector is configured must be active
and responding to requests. In order to assure this, adequate CPU cycles,
memory, and network bandwidth should be provided. The UNIX System
Services parmlib member BPXPRM00 must be properly configured.
Recommendations for the HTTP server can be found in OS/390 e-business
Infrastructure: IBM HTTP Server 5.1 Customization and Usage, SG24-5603.
152
Domino for S/390 and Web Server Integration
11.2 Error categories
During our installation and testing of the Web connector, we encountered four
problem areas:
1. Web connector startup failure
2. Web connector abends
3. Inability to connect to Domino via browser client
4. Ability to connect to Domino, but request for resource fails
11.2.1 Possible causes of Web connector initialization errors
Web connector initialization errors can be caused by improper configuration
of the HTTP configuration directives, or the Web connector GWAPI plug-in
statements.
The Notes server ID file must not use a password. There is no mechanism for
entering this password when the Web connector starts.
11.2.2 Possible causes of abends
Web connector abends can be caused by failure to set the APF authorization
bit on the Domino for OS/390 executables in directory
/usr/lpp/lotus/notes/latest/os390.
Abends can also be caused if the user ID for the Domino server is not set
correctly in the DOMINO-CONNECTOR-SETUP protection directive of the
httpd.conf file. The IBM HTTP Server configured for the Web connector must
be recycled if the Domino server is shut down. Failure to do so may cause the
IBM HTTP Server to abend when a Domino database is requested.
11.2.3 Possible causes of connectivity problems
Web connector connectivity problems errors can have various causes. These
include the following:
1. Domino server is unavailable
2. Network or DNS configuration problems
3. Improper configuration of HTTP server
4. HTTP server busy (no threads available)
5. Improper sequence of server startup
Troubleshooting
153
11.2.4 Failure to access Domino resources
After the Web connector is properly configured and initialized, failure to
access Domino resources can be caused by:
1. Required Web connector security definitions not in place
2. Authentication denied due to invalid RACF credentials (LNOTES segment
incorrectly defined or not uniquely mapping to shortname)
3. Authentication denied by Domino
4. Access by effective Notes user rejected by database ACL
5. Requested database does not exist on the Domino server
6. Domino server not responding
11.3 Tools for problem determination
Tools for troubleshooting include IBM HTTP Server and Web connector
traces and logs, SDSF syslog, SDSF sysout job log, MVS and UNIX System
Services display commands, RACF or other security system display
commands, Domino logs and Domino administration tools. If connectivity
problems are suspected, TCP/IP ping, netstat, and traces can be useful.
11.3.1 Error messages
Web connector initialization error messages and codes are listed in Appendix
A, “Web connector initialization error messages” on page 169.
11.3.2 Installation verification checklist
Assuming that you have a previously working Domino server, the most
frequent cause of errors is improper configuration of the Web connector. We
have included several appendixes to help you configure it. Appendix B,
“Configuration value chart” on page 173 contains a list of configuration values
with spaces for you to write in your specific values. The checklist provided in
Appendix C, “Installation verification checklist” on page 175 and the RACF
security charts in Appendix D, “RACF security charts” on page 177 should be
reviewed before beginning more detailed problem analysis.
11.3.3 RACF security reference materials
Appendix D, “RACF security charts” on page 177 contains three charts:
• IBM HTTP Server
• Domino for IBM HTTP Server connector
154
Domino for S/390 and Web Server Integration
• Domino and DOMCON for OS/390
These charts contain the RACF commands necessary to grant permission to
required resources for the Web connector and Domino. Additional
information can be found in:
• RACF Command Language Reference, SC23-3731
• RACF Messages and Codes, SC23-3730
• Setting Up the Domino for HTTP Connector (shipped with the Lotus
Domino for S/390 R5 server code CD-ROM)
• Lotus Domino for S/390 Release 5: Installation, Customization, and
Administration, SG24-2083
11.3.4 Activating Web connector trace messages
The connector can optionally issue debug/trace messages to the IBM HTTP
Servers trace log. These messages may be helpful in diagnosing problems.
The messages can be found in the Web connector’s JES job log. They are
identified by the DOMIHTTP message ID.
The trace messages are controlled by the _DOMIHTTP_DEBUG environment
variable. Set this variable in the IBM HTTP server’s environment variable file
for your IBM HTTP server instance (/etc/httpd.envvars, by default), or in the
shell environment (/etc/profile or WEBSRVs .profile) if you are running the
IBM HTTP server from the UNIX shell.
Set this variable to an integer value between 1 and 9 to activate messages, or
to a value of 0 to turn them off. A _DOMIHTTP_DEBUG setting of 1 produces
just a couple of messages per request, to confirm the connector's handling of
the request. Larger values produce more messages.
When you activate the Web connector trace, messages appear in the Web
server job log showing that the Web connector GWAPI is initialized.
DOMIHTTP-ServerInit> Initialization started, API version is 1.2.
DOMIHTTP-ParseInitParms> SSL port is 8251.
DOMIHTTP-ParseInitParms> Use of OS/390 creds for Domino requests is
enabled. 2
DOMIHTTP-ServerInit> Initializing interface to Domino.
DOMIHTTP-ServerInit> Interface to Domino successfully initialized.
DOMIHTTP-ServerInit> Initialization completed successfully.
Troubleshooting
155
11.3.5 Activating the HTTP server trace
The HTTP server can optionally issue trace messages showing the flow of
HTTP commands between client and server. These options are controlled by
parameters on the IBM HTTP Server startup procedure JCL EXEC statement.
The trace can be deactivated or modified dynamically while the HTTP server
is running. There are three trace levels available:
v
vv
mtv
Verbose
Very verbose
Much too verbose
The -nodebug parameter deactivates tracing.
The following sample JCL PROC and EXEC statements activate very verbose
tracing:
-------------------------------------------------------//WEBCONN
PROC P1='-B',
// P2='-r /etc//httpd.conf',
// P3='-vv',
// LEPARM='ENVAR("_CEE_ENVFILE=/etc//httpd.envvars")'
//*********************************************************************
//WEBSRV EXEC PGM=IMWHTTPD,REGION=0K,TIME=NOLIMIT,
// PARM=('&LEPARM/&P1 &P2 &P3')
//*PARM=('HEAPP(ON) ALL31(ON) POS(ON) STAC(200K) &LEPARM/&P1 &P2 &P3')
------------------------------------------------------------
The following commands can be used to modify the trace level while the IBM
HTTP Server is running:
F WEBSRV,APPL=-v
F WEBSRV,APPL=-vv
F WEBSRV,APPL=-mtv
F WEBSRV,APPL=-nodebug
11.4 IBM HTTP Server logs
The IBM HTTP Server can be configured to generate several types of log
records. The location and control of the log files can be specified by the
various httpd.conf file log directives.
New log files are created nightly by the server at midnight.
Example: httpd-errors.Aug131999
156
Domino for S/390 and Web Server Integration
Two types of logs are useful for diagnosing Web connector problems. Here
are the default AccessLog and ErrorLog statements which come with the IBM
HTTP Server:
AccessLog
ErrorLog
/usr/lpp/internet/server_root/logs/httpd-logs
/usr/lpp/internet/server_root/logs/httpd-errors
The httpd error logs show errors at Web connector startup or abend. The
httpd access logs show the details of every request made to the Web server.
This includes the requester's origin, the name of the resource being
requested, and HTTP return codes for that request. These codes are as
follows:
1xx
2xx
3xx
4xx
5xx
-
Informational
Success
Redirection
Client Error
Server Error
You can browse these logs using the ISHELL, or use the IBM HTTP Server’s
administration interface if you have Web administrator authority.
For details about configuring and viewing the HTTP Server logs, refer to
OS/390 e-business Infrastructure: IBM HTTP Server 5.1 Customization and
Usage, SG24-5603.
11.4.1 Troubleshooting Web connector startup errors
Most startup errors are caused by errors on httpd.conf directives in the Web
connector IBM HTTP Server configuration file.
11.4.1.1 Symptoms
When the IBM HTTP Server is fully initialized you should see these
messages in the OS/390 syslog:
$HASP373 WEBSRV
STARTED
IMW3534I PID: 721420340 SERVER STARTING
IMW3536I SA 721420340 0.0.0.0:8250 * * READY
If the IBM HTTP server starts and then ends, this can indicate errors in the
configuration file. Possible messages include:
IMW0003E Configuration not loaded
IMW0243E Configuration file /etc/httpd.conf not found or in error.
The server cannot start without a valid configuration file.
IMW0234I Starting.. httpd
............ This is IBM HTTP Server V5R1M0
Troubleshooting
157
............ Built on Mar 23 1999 at 08:32:34.
............ Started at Fri Aug 20 12:09:01 1999
............ Running as "WEBSRV", UID:0, GID:6789.
20/Aug/1999:12:09:01 +0000 : ErrorLog.... 20/Aug/1999:12:09:01 +00
directive is not valid: 9 @(#)53
1.9 src/etc/httpd.conf, web,
web4a1
AA74B80 at 20/Aug/1999:12:09:01 +0000 : ErrorLog....
20/Aug/1999:12:09:01 +00
WEBSRV ended due to errors.
11.4.1.2 Solutions
1. Examine the messages in IBM HTTP Server job log. The configuration
statement which caused the error will be identified by this message:
IMW0243E Configuration file /etc/httpd.conf not found or in error.
Search the Web server job log for these words:
bad configuration directive
The text of the configuration directive which is in error is printed next to the
message, as displayed in the following example:
******************************************************************
ErrorLog.... 20/Aug/1999:13:32:43 +0000 IMW0013E The configuration
.9 src/web/etc/httpd.conf, web, web4a1J 6/21/95 10:19:08
Bad configuration directive: "9 @(#)53
1.9
src/web/etc/httpd.conf,
********************************************************************
2. Fix the configuration statement. Change the Web server started procedure
to activate the -vv trace. Then restart the Web server.
3. During our testing, we found it necessary to place the Web connector
plug-in directives in this order within the httpd.conf file. All of these
statements must be placed before the default Pass directive.
NameTrans
NameTrans
/icons/*
/
DOM_INST_DIR/notes/latest/os390/domihttp:DomIcons
DOM_INST_DIR/notes/latest/os390/domihttp:DomRootCmds
Protection DOMINO-CONNECTOR-SETUP {
Mask
Anybody
UserId
DOM_SERVER_ID
}
Protect
Protect
Protect
Protect
*.nsf
*.nsf/*
/domicons/*
/domjava/*
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
DOMINO-CONNECTOR-SETUP
ServerInit DOM_INST_DIR/notes/latest/os390/domihttp:ServerInit "-sslport SSL_PORT"
Service *.nsf DOM_INST_DIR/notes/latest/os390/domihttp:Service
Service *.nsf/* DOM_INST_DIR/notes/latest/os390/domihttp:Service
158
Domino for S/390 and Web Server Integration
ServerTerm DOM_INST_DIR/notes/latest/os390/domihttp:ServerTerm
Pass
Pass
/domicons/*
/domjava/*
DOM_DATA_DIR/domino/icons/*
DOM_DATA_DIR/domino/java/*
4. Examine MVS syslog and IBM HTTP Server job log for security violation
messages. The IBM HTTP Server must own the files within the
server_root directory. The IBM HTTP Server must have read access to the
BPX.SERVER RACF facility class, and read access to
BPX.SRV.DOM_SERVER_ID plus other IDs for which it will become a
surrogate user.
5. Examine the HTTP Server error log in the server_root log file.
6. Make sure that the Port and SSLPort statements are correct, and that the
ports are not being used by another Web server or TCP/IP application.
7. If the Domino server has been recycled, make certain that the IBM HTTP
Server has also been recycled. The Web connector API uses shared
memory resources, and connects to a specific instance of the Domino
Server. When the Domino server is brought down, it is necessary to bring
down the HTTP Server as well, in order to clean up the shared memory
segments.
We encountered the following problem when we shut down the Domino
server with the HTTP Server running, and tried to restart the Domino:
DOMINO:/notesdata1: >server
CEE3204S The system detected a protection exception.
From entry point OSLockReadSem at compile unit offset
+00000064 at addr
ess 078544DC.
/ospanic.c at entry
The shell command ipcs -a displayed this output:
Shared Memory:
T
m
m
ID
KEY
MODE
171076 0xf8138801 --rw-rw---171078 0xf8138800 --rw-rw----
OWNER
GROUP
CPID
LPID
DOMINO LOTUSGRP 67108895 67108895
DOMINO LOTUSGRP 67108895 419430430
We attempted to restart the Web server prior to cleaning up the Domino
memory and queues. That resulted in these messages:
IMW0234I Starting.. httpd
IMW0235I Server is ready.
Fatal Error signal = 0x0000000b PID/Server-TID/Kernel-TID =
a000026/26010018/0a7
Freezing all server threads ...
............ This is IBM HTTP Server V5R1M0
Troubleshooting
159
To fix this problem, we brought down the Domino server and performed
cleanup as documented in 5.6, “Dealing with abnormal terminations” on
page 58.
11.5 Troubleshooting Web connector GWAPI initialization errors
Errors in the directives for the Web connector may prevent the IBM HTTP
Server from starting.
11.5.1 Symptoms
The Web connector may not initialize when the Web connector statements in
httpd.conf are defined in the wrong order. After the HTTP Server starts, you
should examine the job log for messages. The HTTP Server may start, but
the Web connector service may not initialize correctly, as indicated in the
sample below:
DOMIHTTP-012 Unrecognized -platcreds value: allow
DOMIHTTP-002 DOMIHTTP encountered errors during initialization.
The DOMIHTTP service is not available for use.
When trying to start the HTTP Server configured to connect with one of our
Domino servers, we encountered this error:
$HASP373 WEBSRV STARTED
IMW3534I PID: 268435503 SERVER STARTING
IMW3536I SA 268435503 0.0.0.0:8230 * * READY
ICH408I USER(DOMINIO2) GROUP(LOTUSGRP) NAME(DOMINO USER 2
/notesdata1/gtrhome/
CL(DIRACC ) FID(01D6D7F1C8C6F1000F29000007E00000)
INSUFFICIENT AUTHORITY TO OPENDIR
ACCESS INTENT(R--) ACCESS ALLOWED(GROUP ---)
ICH408I USER(DOMINO2) GROUP(LOTUSGRP) NAME(DOMINO USER 2
/notesdata1/mail/user1.nsf
CL(FSOBJ
) FID(01D6D7F1C8C6E20010320000000A0000)
INSUFFICIENT AUTHORITY TO OPEN
ACCESS INTENT(RW-) ACCESS ALLOWED(GROUP ---)
ICH408I USER(DOMIN02) GROUP(LOTUSGRP) NAME(DOMINO USER 2
/notesdata1/mail/user1.nsf
CL(FSOBJ
) FID(01D6D7F1C8C6E20010320000000A0000)
INSUFFICIENT AUTHORITY TO OPEN
ACCESS INTENT(R--) ACCESS ALLOWED(GROUP ---)
$HASP395 WEBSRV ENDED
This problem was caused by placing the wrong user ID for that Domino server
on the DOMINO-CONNECTOR-SETUP Protection directive. In the example
160
Domino for S/390 and Web Server Integration
above, we were running a Domino server with user ID DOMINO1; however,
we had coded user ID DOMINO2 on the Protection directive.
Improper sequencing of the Domino and IBM HTTP Server startups, or failure
to clean up shared resources, can cause the IBM HTTP Server to abend at
startup. The IBM HTTP Server with the Web connector GWAPI uses message
queues to communicate with Domino. If the IBM HTTP Server abends, it is
necessary for Domino to relinquish these queues before the IBM HTTP
Server is restarted.
You may encounter the IBM HTTP Server abend as described below:
AA74B80 at 26/Aug/1999:14:52:02 +0000 : DOMIHTTP-ServerInit>
Initializing inte...
CEE3250C The system or user abend U 034 R=07110304 was issued.
From compile unit ./ospanic.c at entry point Panic at compile unit
offset ...
CEE3DMP V2 R7.0: Condition processing resulted in the unhandled
condition.
In this case you will need to shut down the Domino server, perform cleanup
procedures, restart the Domino server, then restart the IBM HTTP Server.
11.5.2 Solutions for Web connector GWAPI initialization errors
1. Certain errors are reported in IBM HTTP Server logs:
DOMIHTTP-001: Connector Initialization Errors
ICH408I (Insufficient access authority for BPX.SRV.userid profile)
Other errors are reported to the browser user:
Browser Error 500: IMW0240E Access denied - unauthorized program loaded
Browser Error 500: IMW0241E Access denied - surrogate user setup error
If you receive these errors, refer to the error codes listed in Appendix A, “Web
connector initialization error messages” on page 169, and review required
RACF definitions.
2. Examine the ServerInit and other Web connector statements for syntax
errors. The options which follow the domithhp:ServerInit parameter on the
ServerInit statement must be enclosed by double quotes.
3. Review the installation verification checklist in Appendix B, “Configuration
value chart” on page 173.
4. Examine the HTTP Server JES job log.
5. Examine the OS/390 syslog for security violation messages.
Troubleshooting
161
6. Examine the IBM HTTP Server error logs.
7. Examine the ServerInit statement for the Web connector plug-in service.
Make sure the SSL_Port number is correct, and that the ports do not
conflict with those of another HTTP Server.
8. Activate the Web connector trace facility by adding the
_DOMIHTTP_DEBUG environment variable to the HTTP Server’s
httpd.envvars file. Refer to instructions in 11.3.4, “Activating Web
connector trace messages” on page 155 and to the Domino for HTTP
Server Installation Guide for further information.
11.6 Troubleshooting connectivity problems
Connectivity problems are indicated by the inability to connect to Domino via
a browser client.
11.6.1 Symptoms
When you open a URL, you might receive a message box with the following
text:
There was no response. The server could be down or is not responding. If
you are unable to connect again later, contact the server’s
administrator.
If you access a Domino server for which the Web connector has not been
configured, or use a port for which no HTTP servers are configured, you get a
message like this:
Netscape is unable to locate the server domweb2:8250
When you run multiple HTTP servers, you must use the HTTP server which is
configured with the right /notesdata path for the Domino server you are
attempting to access. You must also use the correct port. In the following
case, we have two HTTP servers named WEBSRV1and WEBSRV2,
connected to corresponding Domino servers named DOMWEB1 and
DOMWEB2. For Notes protocol (NRPC), these servers were using the
following addresses with proper DNS support.
DOMWEB1 IP address=10.10.1.1
DOMWEB2 IP address=10.10.1.2
The server configurations were:
WEBSRV1 listening on port 8230 (non-specific bind), and connected to
Domino server DOMWEB1.
162
Domino for S/390 and Web Server Integration
WEBSRV2 listening on port 8250 (non-specific bind), and connected to
Domino server DOMWEB2.
Note that the HTTP servers were configured as generic listeners
(non-specific bind). This means that a listen request will bind to all
stack-defined addresses. When we tried to access DOMWEB2 using the port
of WEBSRV1, we were connected with DOMWEB1 instead of DOMWEB2.
This is because WEBSRV1 and note WEBSVR2 was listening with
non-specific bind on its assigned port. In fact, with this configuration it does
not matter which of the stack-defined addresses are used. All that matters is
the port being used.
Another conceptual mistake made in this test was that of intuitively
associating each http server with the address being used for NRPC by the
corresponding Domino server. This association does not exist; the addresses
are totally unrelated. In fact, it would be valid to configure the http server
having specific bind to an address different from that of the corresponding
Domino server.
11.6.2 Solutions for connectivity problems
This section provides solutions for connectivity problems.
11.6.2.1 Actions to take from the client workstation:
1. Verify that the URL contains the correct Domino server hostname and
HTTP port.
2. Verify that the Domino server is up.
3. Using the Notes client, verify that the database you are trying to access
exists.
4. Verify that you have a compatible browser. We tested the Netscape
browsers V4.5, 4.6, and 4.7. Some functions did not work correctly on
V4.5.
5. Verify that you can ping the Domino/390 host from the client workstation:
If ping times out, verify that the Domino/390 hostname has been added to
your Domain Name Server or your local hosts file.
6. Determine the client machine IP address by issuing the appropriate
commands. From Windows NT, issue IPCONFIG. From Windows 95/98,
use WINIPCFG.
7. If you can ping the Domino/390 host, ping the client from the S/390 host:
From TSO:
Troubleshooting
163
ping
10.10.1.201
Use oping from shell or telnet sessions.
8. If the Domino/390 hostname is in the DNS or hosts file, but you cannot
ping the 390 host from the client, or you cannot ping the client from the
S/390 host, then investigate routing problems.
One useful command is the tracerte command:
tracerte 10.10.1.201
otracerte 10.10.1.201
(from TSO)
(use otracerte from telnet or OMVS)
From the client, the command is tracerte. Here is output from tracerte
which indicates a routing problem:
tracerte DOMWEB1
1 <10ms
<10ms
2
x
<10ms
x
10.10.1.1
x
Request timed out
11.6.2.2 Actions to take from the S/390 host machine:
1. Verify that TCP/IP is up and working properly.
We received this message when we tried to ping our Domino server and
TCP/IP had been having resolver problems:
EZA0455E BeginTcpIp failed: No TCP/IP service available (8544)
2. If TCP/IP is up, verify that the link device has been started. This TSO
command shows the device status.
netstat dev
onetstat -d
(from OMVS shell or telnet)
The device and link associated with your IP address should have a status
of Ready, as in the display below.
DevName: OSA2220
LnkName: OSAL2220
DevType: LCS
LnkType: TR
DevNum: 2220
Status: Ready
3. Verify that the IBM HTTP Server is up and listening on the correct port.
This TSO command will display the ports and associated processes:
netstat conn
onetstat -p TCPIP
(from OMVS shell or telnet)
The -p parameter specifies the TCP/IP stack proc name. This display
shows that IBM HTTP Server WEBAPPLE is listening on port 8100.
EZZ2587I WEBAPPLE 000C1 0.0.0.0..8100
0.0.0.0..0
Listen
4. Verify that the IBM HTTP Server port is configured correctly in the
httpd.conf file. Use the IBM HTTP Server logs to determine whether the
request was made to the wrong port.
164
Domino for S/390 and Web Server Integration
5. Verify that the Domino server is up and listening on the correct port.
The netstat conn command shows that our Domino server, with a user ID
of DOMINO1, is up and listening generic (on all IP addresses) on port
1352.
EZZ2587I DOMINO1 00579 10.10.1.201..1352
0.0.0.0..0
Listen
6. If Domino is not responding, or is in a CloseWait state, examine the TCPIP
job log and the Domino noteslog files for errors.
This Domino command can be used to display port traffic.
> show port tcpip
The netstat byteinfo command displays the connections, and the number
of bytes that are being transferred.
11.7 Troubleshooting authentication problems
If the user can connect with the Domino server but the attempt to open a
Notes database fails, the cause is probably an authentication problem. First
you need to determine that the actual security scheme in place is the desired
one. By activating the Web connector trace and HTTP trace, you can see
which database was requested, what type of authentication credentials were
presented, and whether access was granted. It is highly recommended that
you review Chapter 6, “OS/390 authentication support for Domino” on page
79 in order to understand the flow of authentication logic.
11.7.1 Symptoms of security-related problems
If you enable OS/390 authentication, and the user has a valid LNOTES
segment in the RACF user ID profile, the Web connector will attempt to map
the LNOTES value into the shortname in the Person documents in the
Domino directory. For this process to be successful, there can be one and
only Person entry satisfying the mapping. You can see the result of the
process in the Web connector trace entries in the job log:
AAE2F20 at 25/Aug/1999:10:43:22 +0000 : DOMIHTTP-OS309toNotesIdMap
Userid (user1) mapped to valid shortname (user1); fullname is CN=Jane
User1/O=Itsoweb. Effective username will be set to user1.
The LNOTES segment value in the RACF user profile is case-sensitive, but
the mapping to shortname process is not. If the mapped shortname is not
unique, or is not found within the Domino directory, the user's identity is
passed to Domino as non-authenticated or anonymous. The trace will show:
AB2AA98 at 25/Aug/1999:10:48:18 +0000 : DOMIHTTP-OS309toNotesIdMap>
Userid (user1) OS/390. Effective username will not be changed.
Troubleshooting
165
At that point, the user could enter a valid Notes name and Notes Web
password. If the name and password are valid, and the ACL of the database
permits access, the request would be granted. If the user does not have a
Notes ID, then the request would be passed as anonymous. If the ACL of the
database does not allow read access to anonymous, your browser will inform
you that authorization failed and prompt for retry.
The Web connector trace shows:
AAE4DF8 at 25/Aug/1999:10:45:40 +0000 : DOMIHTTP-OS309toNotesIdMap>
Userid (l
(sssss). Effective username will be handled as Anonymous.
If the Notes administrator has not enabled HTTP access in the Person
document, authorization fails.
Error 401
You are not authorized to perform this operation
Lotus-Domino Release 5.01a.00
The Netscape browser produces these errors when a user tries to open file
which does not exist:
Error 404
IMW0229E The file was not found, even after searching on any extensions
to the file name. The file does not exist or is read-protected.
11.7.2 Solutions for security problems
1. Activate the Web connector and IBM HTTP Server traces. If an OS/390
authentication scheme is being used, verify that PTFs OW35502 and
OW39716 have been applied. If so, you can proceed to verify that the
OS/390 authentication has been enabled properly. The third line below
indicates that we have enabled OS/390 authentication support.
DOMIHTTP-ServerInit> Initialization started, API version is 1.2.
DOMIHTTP-ParseInitParms> SSL port is 8251.
DOMIHTTP-ParseInitParms> Use of OS/390 creds for Domino requests is
enabled.
DOMIHTTP-ServerInit> Initializing interface to Domino.
DOMIHTTP-ServerInit> Interface to Domino successfully initialized.
DOMIHTTP-ServerInit> Initialization completed succesully.
2. If OS/390 authentication support is enabled, you may have forgotten to set
(or have incorrectly set) the HTTP Server user ID RACF permission to use
the application identity mapping interface. This typically shows in the Web
connector’s trace with the following messages:
DOMIHTTP-Service> ecb.ContentType = <>
166
Domino for S/390 and Web Server Integration
DOMIHTTP-Service> ecb.TotalBytes = 0
DOMIHTTP-ConnReq::extract> Got HTTPS=<OFF>.
DOMIHTTP-ConnReq::extract> Got AUTH_TYPE=<Basic>.
DOMIHTTP-OS390toNotesIdMap> Entered.
DOMIHTTP-ConnReq::extract> Got AUTH_STRING=<bWFnbmV0bzptYWduZXRv>.
DOMIHTTP-GetBasicCreds> Retrieved Basic username=magneto and password of length
DOMIHTTP-OS390toNotesIdMap> RACF_id.length=7, RACF_id.name=MAGNETO.
DOMIHTTP-OS390toNotesIdMap> IRRSIM00 call rc’s: SAF_rc=8, RACF_rc=8, RACF_rs=20.
DOMIHTTP-006 An internal error occurred while processing the request.
Fcn: OS390toNotesIdMap, error code: 292.
Additional symptom information follows in message DOMIHTTP-007.
DOMIHTTP-007 IRRSIM00 call failed: check authority to resource IRR.RUSERMAP.
DOMIHTTP-OS390toNotesIdMap> No mapping has occurred due to a severe internal
DOMIHTTP-OS390toNotesIdMap> Returning with code=0.
DOMIHTTP-Service> Call to OS390toNotesIdMap failed.
If that is the case, refer to 6.4, “Enabling OS/390 RACF-based authentication”
on page 95.
3. Determine which Notes database was requested by examining the Web
server started task job log and Web server logs.
4. If OS/390 authentication support is enabled, does the requesting user
have an LNOTES segment? Use this command to display the LNOTES
segment:
lu userid LNOTES
If the user has an LNOTES segment, check the Person document in the
Domino directory to determine if the shortname matches the RACF
LNOTES user ID (it has to be the one and only shortname match). Then
check the access control list of the requested database. If there is no
match, the request should be processed as Anonymous.
In either case, check the access control list to determine the access level
for the mapped Notes user or Anonymous. If there is no entry for
Anonymous, then the default access would take effect (which may be set
to “none”).
5. If the user enters a Notes user ID and authorization fails, check the
following items:
Does the user have Allow HTTP setting enabled in the Person document
in the Domino directory?
If so, did the user enter the correct Web password?
6. If the user has a valid Notes ID and entered the correct password, check
the Access Control List (ACL) to determine whether access is allowed.
Note that some browsers cache the client’s credentials. If you are doing
testing, and you need to enter a different user ID, it is best to close and
reopen the browser session before changing identities.
Troubleshooting
167
168
Domino for S/390 and Web Server Integration
Appendix A. Web connector initialization error messages
This appendix explains Domino for IBM HTTP Server connector (Web
connector) initialization error messages.
A.1 DOMIHTTP-001
The Domino for IBM HTTP Server connector issues message
DOMIHTTP-001 to the IBM HTTP server’s trace and error log when it
encounters an error in setting up its interface to Domino. The error code
provided in this message is the Domino error code returned by the
initialization call. Most of the errors encountered result from problems in
Domino initialization. The following list summarizes the error codes you are
most likely to encounter and suggestions for resolving the error:
0x0102 (PKG_OS_ERR_PROTECTED) - Cannot write or create file (file
or disk is read-only).
When this occurs during initialization, it is probably because the
HTTP Server user ID/process does not have write access to the
names.nsf database. To resolve this problem, use the chgrp
command (to change the owning group, if necessary) and the
chmod command (to change the permission bits) to give members
of the Domino UNIX group (for example, NOTES) read/write
access to the names.nsf file.
This error can also occur during normal connector processing, in
which case it shows up as an error response to the browser with
the message text given above.
To resolve this problem, use the chgrp command (to change the
owning group, if necessary) and the chmod command (to change
the permission bits) to give members of the Domino UNIX group
(for example, NOTES) read/write access to the file.
0x0107 (PKG_OS_ERR_MEMORY) - Insufficient memory
There is not enough memory available. Increase the region size
for the job or login session running the IBM HTTP Server.
0x1007 Domino initialization can not find the ltscu2e.tlb file.
This is a Domino translation resource file. Domino looks for this
file in the Domino executables directory (which is usually
usr/lpp/lotus/notes/latest/os390).
© Copyright IBM Corp. 2000
169
Domino determines the location of its executable directory by
searching the directories listed in the PATH environment variable
for the Domino executable programs.
To resolve this problem, ensure that the Domino executable
directory (for example, /usr/lpp/lotus/notes/latest/os390) is listed in
the PATH environment variable. Also, ensure that the Domino bin
directory (/usr/lpp/lotus/bin) is not listed in the PATH environment
variable, since its presence in PATH can cause Domino to
incorrectly conclude that it is the Domino executable directory.
0x175b (ERR_BSAFE_WRITE_PROTECTED) - The ID file is write
protected.
This message appears when the HTTP server user ID process
either has no access at all, or read-only access, to the server’s ID
file. The file in question is the one designated by the
ServerKeyfilename variable in notes.ini. Usually this file is
/notesdata/server.id.
To resolve this problem, use the chgrp command (to change the
owning group, if necessary) and chmod command (to change the
permission bits) to give members of the Domino UNIX group (for
example, NOTES) read/write access to the names.nsf file.
0x1902 (PKG_SECURE_ERR_SECURE_NOKEYFILE) - Could not open the
id file.
This is typically the first error you may encounter when trying to
run the Connector from a non-superuser user ID. This error results
from a number of underlying errors. Some of the specific causes
include:
• The notes.ini file could not be found. Domino searched the current
directory and then the directories listed in the PATH environment
variable for this file and could not locate the file. To resolve this
problem, add the Domino data directory to the IBM HTTP servers
PATH environment variable.
• The notes.ini file was found, but the HTTP server user ID process
does not have write access to the file. To resolve this problem,
modify the group and permissions for the file so that the file is
owned by the Domino UNIX group (NOTES) and ensure that group
has read-write access. Ensure that the IBM HTTP Server user ID is
a member of the NOTES group.
170
Domino for S/390 and Web Server Integration
0xff99 The Domino server is not configured to require unambiguous Web user
names using the NoAmbiguousWebNames Domino setting.
To resolve this problem, use the viascii utility to add the following
setting to the notes.ini file for your Domino server:
NoAmbiguousWebNames=1
The Domino for IBM HTTP Server requires this setting in order to
avoid potential security exposures in its translation of OS/390
credentials to Domino credentials
0xff9a Domino initialization could not find the notes.ini file in either
the current directory or in any of the directories named in the
PATH environment variable.
To resolve this problem, add the Domino data directory to the IBM
HTTP Server’s PATH environment variable.
A.2 ICH408I (Insufficient access authority) for BPX.SRV.userid profile
Symptom:
You are receiving message ICH408I on the OS/390 console, or in the
job log for the IBM HTTP Server, for authorization failures related to a
BPX.SRV.userid SURROGAT class profile for the Domino server user
ID.
Cause:
The IBM HTTP Server protection directives in httpd.conf specify that
the Web server should process requests for Domino databases under
the security identity of the Domino server user ID. However, the user ID
running the IBM HTTP Server has not been authorized to act as a
surrogate for the Domino server user ID.
To resolve this problem, use the following TSO command to verify that
the IBM HTTP Server user ID has been given read access to the
SURROGAT class profile for the Domino server user ID. For example,
if the Domino server user ID is SERVER, this profile is called
BPX.SRV.SERVER and it can be listed with the following command:
rlist surrogat bpx.srv.server authuser
If this profile has not been defined, it can be defined with the TSO
RDEFINE command, for example:
rdefine surrogat bpx.srv.server uacc(none)
Web connector initialization error messages
171
If the profile is defined but the IBM HTTP Server user ID is not listed,
use the TSO PERMIT command to grant it read access to this profile.
For example, if the IBM HTTP Server user ID is WEBSRV, access can
be granted with the command:
permit bpx.srv.server class(surrogat) id(websrv) acc(read)
A.3 Browser Error 500: IMW0240E Access denied
Symptom:
The browser receives an Error 500 response, with message IMW0240E
(Access denied - unauthorized program loaded) after a user responds to
a browser username and password challenge for access to some URL.
This error may occur even if the request is for something other than a
Domino database.
Cause:
The system services that the IBM HTTP Server uses to set up security
contexts for processing requests requires that all of the modules
(programs and DLLs) loaded into the IBM HTTP Server address space
come from data sets or HFS files that are marked as
program-controlled. This error message is received when one or more
modules have been loaded from non-program-controlled data sets or
HFS files.
Assuming that the IBM HTTP Server was working correctly before you
activated the Domino for IBM HTTP Connector, the likely cause is that
the Web connector or one of the Domino DLLs is not marked as
program-controlled.
Resolution:
To resolve this problem, use the ls -E UNIX shell command to verify
that the program-controlled external attribute is set for all files in the
/usr/lpp/lotus/latest/os390 directory. If not, use the extattr +p
command to set the program-controlled extended attribute.
You need to have ACCESS(READ) to RACF profile
BPX.FILEATTR.PROGCTL in order to execute the extattr command.
172
Domino for S/390 and Web Server Integration
Appendix B. Configuration value chart
Copy this page and add the configuration values. Use it along with Appendix
C.1, “Checklist” on page 175 when installing your systems.
TCP/IP address of Domino server
HTTP Server PROC name
HTTP Server user ID/group ID
HTTP Server port
HTTP Server SSL port (if using SSL)
HTTP server_root directory
Domino Notes server name
Domino Notes server user ID/group ID
Notesdata directory name
OS/390 authentication enabled? (Y/N)
OS/390 SSL authentication used? (Y/N)
Names of resources for which certificates are
required (https:)
© Copyright IBM Corp. 2000
173
174
Domino for S/390 and Web Server Integration
Appendix C. Installation verification checklist
This appendix contains a checklist that you can use when setting up the Web
connector program. Use it along with Appendix D, “RACF security charts” on
page 177 when installing your systems.
C.1 Checklist
1. Verify that following line been added to notes.ini:
NoAmbiguousWebNames=1
2. Verify that the Notes server ID file does not use a password.
3. If the Domino for HTTP Server user ID is not UID(0), then verify that the
/notesdata directory gives the Domino group read/write/execute
permission. Verify that the server.id, notes.ini, log.nsf and names.nsf files
grant the Notes group read/write permission.
4. Check that the Domino product executables files are program-controlled.
This attribute is required to allow the GWAPI plug-in to change client
thread identity.
cd /usr/lpp/lotus/notes/latest/os390
ls -E
You should see the p and s flags set on all files, similar to the following
example.
-rwxr-xr-x -ps 1 AAAAAA
SYS1
7344664 Jul 29 19:41 ltscu2e.tlb
If the protect bit is not set, logon with a user ID that has read permission to
RACF resource BPX.FILEATTR.PROGCTL.
extattr +p *
5. Check the httpd.envvars file. The PATH statement should include:
/notesdata
(name of your /notesdata directory)
/usr/lpp/lotus/notes/latest/os390
/usr/lpp/lotus/notes/latest/os390/res/C
The LIBPATH statement must include the Domino product executable
directory:
/usr/lpp/lotus/notes/latest/os390
6. The GWAPI connector statements must be in the order specified in
Chapter 2, “Configuring the Domino for IBM HTTP Server” on page 5.
7. The user ID specified in the Protection directive must match the user ID
used by the Domino server.
© Copyright IBM Corp. 2000
175
8. The connector plug-in ServerInit statement must point to the correct
/notesdata directory for the Domino server.
9. The PATH statement in the httpd.envvars file must include the correct
/notesdata directory.
10.Make sure that you have defined the correct port. Make certain that no
other HTTP servers are using that port, and that the SSLPort matches the
-sslport xx portion of the connector plug-in ServerInit statement.
11.Check that the initialization option string on the ServerInit directive
(everything following the domihttp:ServerInit part) is enclosed in double
quotes.
12.Check that the required security definitions for BPX.SERVER,
BPX.SRV.xxxx, and optional LNOTES segments are in place. The Domino
user ID must be connected the the IMWEB (IBM HTTP Server) group, and
the IBM HTTP Server must be connected to the LOTUSGRP RACF
parameters for Domino and DOMCON for OS/390.
176
Domino for S/390 and Web Server Integration
Appendix D. RACF security charts
These charts contain the RACF commands necessary to grant permission to
required resources for the Web connector and Domino.
Resource Profiles
rdefine facility irr.rusermap
uacc(none)
rdefine facility bpx.server
uacc(none)
permit irr.usermap class(facility) permit bpx.server class(facility)
id(W EBSERV) acc(read)
access(read) id(W EBSERV)
rdefine facility bpx.fileattr.progctl rdefine surrogat bpx.srv.domino
uacc(none)
uacc(none)
permit bpx.fileattr.progctl
class(facility) id(sysprog)
access(read)
setropts raclist(facility) refresh
permit bpx.srv.domino class(surrogat)
id(W EBSRV) acc(read)
rlist surrogat bpx.srv.domino authuser
rlist facility bpx.server authuser
Figure 65. RACF parameters for IBM HTTP Server
User Profiles
connect DOMINO group(IMWEB)
connect WEBSRV group(LOTUSGRP)
To define LNOTES segment
adduser newuser lnotes(sname('Domino_shortname') *
listuser mewuser lnotes
*Case-sensitive - must be exact match
To remove LNOTES segment:
altuser newuser lnotes(nosname)
altuser newuser nolnotes
Figure 66. RACF parameters for Domino for IBM HTTP Server connector
© Copyright IBM Corp. 2000
177
LOTUSGRP
ADDGROUP
LOTUSGRP
OMVS(GID(100))
DOMINO*
DOMCON
ADDUSER DOMCON
DFLTGRP(LOTUSGRP)
OMVS(UID(0)
HOME(/'u/domcon')
PROGRAM('bin/sh')
FACILITY Class
PERMIT BPX.DAEMON
CLASS(FACILITY)
ACCESS(READ) ID(DOMCON))
PERMIT BPX.STOR.SWAP
CLASS(FACILITY)
ACCESS(READ) ID(DOMINO))
PERMIT BPX.SMF
CLASS(FACILITY)
ACCESS(READ) ID(DOMINO))
if using domoe:
PERMIT BPX.SRV.*
CLASS(FACILITY)
ACCESS(READ)
ID(DOMINO)
PERMIT BPX.SERVER
CLASS(FACILITY)
ACCESS(UPDATE)
ID(domadmin)
*uid MUST BE NON-ZERO
*For each Domino Server:
ADDUSER DOMINO
DFLTGRP(LOTUSGRP)
OMVS(UID(1001)
HOME('/u/domino')
PROGRAM('bin/sh')
*if TSO, password(xxxx) name('Domino Server') tso()
Program Protection
RALTER PROGRAM *
ADDMEM('DOMINO.LPALIB'
/volume/NOPADCHK)
UACC(READ)
RALTER PROGRAM *
ADDMEM('DOMINO.LPAPDSE'
/volume/NOPADCHK)
UACC(READ)
RALTER PROGRAM *
ADDMEM('DOMCON.LOADLIB)'
/volume/NOPADCHK)
UACC(READ)
SETROPTS
WHEN(PROGRAM)
SETROPTS
RACLIST(FACILITY) REFRESH
STARTED Class
RDEFINE STARTED(DOMIN*.**)
STDATA(USER(DOMCON))
SETROPTS RACLIST(STARTED)
REFRESH
DATASET Rules
*Do for DOMCON + Domino Server ID's
Addsd 'DOMCON.LOADLIB'
UACC(NONE)
PERMIT 'DOMCON.LOADLIB'
ACCESS(EXECUTE)
ID(DOMINO)
Figure 67. RACF parameters for Domino and DOMCON for OS/390
178
Domino for S/390 and Web Server Integration
Appendix E. Special notices
This publication is intended to help Lotus Domino Administrators,
Webmasters and/or systems programmers to install, customize and use the
Lotus Domino for IBM HTTP Server connector. The information in this
publication is not intended as the specification of any programming interfaces
that are provided by Lotus Domino or the IBM HTTP Server. See the
PUBLICATIONS section of the IBM Programming Announcement for Lotus
Domino and IBM HTTP Server for more information about what publications
are considered to be product documentation.
References in this publication to IBM products, programs or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program, or service is not
intended to state or imply that only IBM's product, program, or service may be
used. Any functionally equivalent program that does not infringe any of IBM's
intellectual property rights may be used instead of the IBM product, program
or service.
Information in this book was developed in conjunction with use of the
equipment specified, and is limited in application to those specific hardware
and software products and levels.
IBM may have patents or pending patent applications covering subject matter
in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to the IBM
Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY
10504-1785.
Licensees of this program who wish to have information about it for the
purpose of enabling: (i) the exchange of information between independently
created programs and other programs (including this one) and (ii) the mutual
use of the information which has been exchanged, should contact IBM
Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA.
Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.
The information contained in this document has not been submitted to any
formal IBM test and is distributed AS IS. The information about non-IBM
("vendor") products in this manual has been supplied by the vendor and IBM
assumes no responsibility for its accuracy or completeness. The use of this
information or the implementation of any of these techniques is a customer
responsibility and depends on the customer's ability to evaluate and integrate
© Copyright IBM Corp. 2000
179
them into the customer's operational environment. While each item may have
been reviewed by IBM for accuracy in a specific situation, there is no
guarantee that the same or similar results will be obtained elsewhere.
Customers attempting to adapt these techniques to their own environments
do so at their own risk.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of
these Web sites.
Any performance data contained in this document was determined in a
controlled environment, and therefore, the results that may be obtained in
other operating environments may vary significantly. Users of this document
should verify the applicable data for their specific environment.
Reference to PTF numbers that have not been released through the normal
distribution process does not imply general availability. The purpose of
including these reference numbers is to alert IBM customers to specific
information relative to the implementation of the PTF when it becomes
available to each customer according to the normal IBM PTF distribution
process.
The following terms are trademarks of the International Business Machines
Corporation in the United States and/or other countries:
IBM
OS/390
S/390
WebSphere
Lotus Notes
Notes
Language Environment
RACF
SP
Lotus
Domino
The following terms are trademarks of other companies:
Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything.
Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet
Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli
Systems Inc., an IBM company, in the United States, other countries, or both.
In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli
A/S.
C-bus is a trademark of Corollary, Inc. in the United States and/or other
countries.
180
Domino for S/390 and Web Server Integration
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other
countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.
PC Direct is a trademark of Ziff Communications Company in the United
States and/or other countries and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel
Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries
licensed exclusively through The Open Group.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks
owned by SET Secure Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service
marks of others.
Special notices
181
182
Domino for S/390 and Web Server Integration
Appendix F. Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
F.1 IBM Redbooks
For information on ordering these ITSO publications see “How to Get ITSO
Redbooks” on page 187.
• Lotus Notes and Domino R5 Security Infrastructure Revealed, SG24-5341
• Lotus Domino for S/390 Release 5: Installation, Customization and
Administration, SG24-2083
• OS/390 e-business Infrastructure: IBM HTTP Server 5.1- Customization
and Usage, SG24-5603
• Lotus Domino for S/390 Rlease 5: Problem Determination Guide,
SG24-5599
• Debugging UNIX System Services, Lotus Domino, Novell Network
Services, and Other Applications on OS/390, SG24-5613
F.2 IBM Redbooks collections
Redbooks are also available on the following CD-ROMs. Click the CD-ROMs
button at http://www.redbooks.ibm.com/ for information about all the CD-ROMs
offered, updates and formats.
CD-ROM Title
System/390 Redbooks Collection
Networking and Systems Management Redbooks Collection
Transaction Processing and Data Management Redbooks Collection
Lotus Redbooks Collection
Tivoli Redbooks Collection
AS/400 Redbooks Collection
Netfinity Hardware and Software Redbooks Collection
RS/6000 Redbooks Collection (BkMgr)
RS/6000 Redbooks Collection (PDF Format)
Application Development Redbooks Collection
IBM Enterprise Storage and Systems Management Solutions
© Copyright IBM Corp. 2000
Collection Kit
Number
SK2T-2177
SK2T-6022
SK2T-8038
SK2T-8039
SK2T-8044
SK2T-2849
SK2T-8046
SK2T-8040
SK2T-8043
SK2T-8037
SK3T-3694
183
F.3 Other resources
These publications are also relevant as further information sources:
• OS/390 Planning for Installation, GC28-1726
• OS/390 UNIX System Services Planning, SC28-1890
• IBM HTTP Server for OS/390 Release 7, Planning, Installing, and Using,
Version 5.1, SC31-8690
• Program Directory for OS/390 V2R7.0 , GI10-4001
• RACF Command Language Reference, SC23-3731
• RACF Messages and Codes, SC23-3730
• 3990/9390 Planning, Installation, and Storage Administration Guide,
GA32-0100
F.4 Referenced Web sites
These Web sites are also relevant as further information sources:
• IBM site for Lotus Domino for S/390:
http://www.s390.ibm.com/products/domino
• IBM home page:
http://www.ibm.com
• Lotus home page:
http://www.lotus.com
F.5 Lotus documentation
These books are shipped with the Lotus Domino for S/390 Release 5 server
code CD-ROM:
• Setting Up the Domino for HTTP Connector
• Lotus Domino for S/390 Install Guide for Servers (part number AB0999)
• Lotus Domino for S/390 R5 Release Notes (part number AA0814)
• R5 Domino Administration Doc Pack
• Administering the Domino System: Volume 1 & 2
• Moving to Notes and Domino Release 5
• Setting up a Domino Server
184
Domino for S/390 and Web Server Integration
• Configuring the Domino Network
• Administering Domino Clusters
• Managing Domino Databases
• Domino R5 Administration Help (online guide)
Related publications
185
186
Domino for S/390 and Web Server Integration
How to Get ITSO Redbooks
This section explains how both customers and IBM employees can find out about ITSO redbooks,
redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided.
• Redbooks Web Site http://www.redbooks.ibm.com/
Search for, view, download, or order hardcopy/CD-ROM redbooks from the redbooks Web site. Also
read redpieces and download additional materials (code samples or diskette/CD-ROM images) from
this redbooks site.
Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few
chapters will be published this way. The intent is to get the information out much quicker than the
formal publishing process allows.
• E-mail Orders
Send orders by e-mail including information from the redbooks fax order form to:
In United States
Outside North America
e-mail address
usib6fpl@ibmmail.com
Contact information is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
• Telephone Orders
United States (toll free)
Canada (toll free)
Outside North America
1-800-879-2755
1-800-IBM-4YOU
Country coordinator phone number is in the “How to Order”
section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
• Fax Orders
United States (toll free)
Canada
Outside North America
1-800-445-9269
1-403-267-4455
Fax phone number is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
This information was current at the time of publication, but is continually subject to change. The latest
information may be found at the redbooks Web site.
IBM Intranet for Employees
IBM employees may register for information on workshops, residencies, and redbooks by accessing
the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button.
Look in the Materials repository for workshops, presentations, papers, and Web pages developed
and written by the ITSO technical professionals; click the Additional Materials button. Employees
may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements.
© Copyright IBM Corp. 2000
187
IBM Redbook Fax Order Form
Please send me the following:
Title
Order Number
First name
Quantity
Last name
Company
Address
City
Postal code
Country
Telephone number
Telefax number
VAT number
Card issued to
Signature
Invoice to customer number
Credit card number
Credit card expiration date
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.
188
Domino for S/390 and Web Server Integration
Abbreviations and acronyms
ACL
Access Control List
HTTP
APF
Authorized Program
Facility
Hypertext Transfer
Protocol
IBM
API
Application
Programming Interface
International Business
Machines Corporation
ICM
ASCII
American Standard
Code for Information
Interchange
Internet Cluster
Manager
IIOP
Internet Inter-Orb
Protocol
ASID
Address Space ID
IMAP
CA
Certificate Authority
Internet Message
Access Protocol
IPC
CGI
Common Gateway
Interface
Inter-Process
Communication
CORBA
Common Objects
Request Broker
Architecture
IPCS
Inter-Process
Communication
Services
IPL
Direct Access Storage
Device
Initial Program Load
DASD
ISV
DECS
Domino Enterprise
Connection Services
Independent Software
Vendor (now called a
Solution Developer)
ITSO
DGW
Domino Go Webserver
(predecessor of the
IBM HTTP Server)
International Technical
Support Organization
JDBC
Java Data Base
Connection
JDK
Java Development Kit
JES
Job Entry Subsystem
DLL
Dynamic Link Library
DOMCON
Domino Console
Interface Package
DSAPI
Domino Web Server
API
JSP
Java Server Pages
JVM
Java Virtual Machine
EJB
Enterprise Java Beans
LDAP
FRCA
Fast Response Cache
Accelerator
Lightweight Directory
Access Protocol
LE
Language Environment
FTP
File Transfer Protocol
LPA
GWAPI
Go Webserver API
(OS/390) Link Pack
Area
HFS
Hierarchical File
System
LPAR
Logical Partition (S/390
Hardware Feature)
HTML
Hypertext Markup
Language
MVS
Old name for OS/390
NNTP
Network News Transfer
Protocol
© Copyright IBM Corp. 2000
189
OEDIT
OpenEdition Editor
OMVS
OpenEdition MVS, old
name for OS/390 UNIX
System Services
OpenEdition
Old name for UNIX
System Services
ORB
Object Request Broker
PID
Process ID
PPID
Parent Process ID
PDS
Partitioned Data Set
PDS/E
Partitioned Data
Set/Extended
POP3
Post Office Protocol 3
RACF
Resource Access
Control Facility
PTF
Program Temporary Fix
SD
Solution Developer
(formerly ISV)
SSL
Secure Socket Layer
TSO
Time Sharing Option
URL
Uniform Resource
Locator
USS
UNIX System Services
VIPA
Virtual IP Addressing
WAS
WebSphere Application
Server
WebAS
WebSphere Application
Server
WLM
Workload Manager
190
Domino for S/390 and Web Server Integration
Index
Symbols
.profile file 24
_DOMIHTTP_DEBUG 155
A
access control - Web server admin 77
Access Control List 84
access-control checking 13
AccessLog 157
ACL 84
administration access control 77
Administration Client 54
administration client 54
administration facility 68
administrator
user ID 25
Administrator client 32, 55
Administrator ID 31, 32
agents 16
ALOCPROD 17, 20
APPLENV 130
Authentication 79
Basic 79
SSL client certificate 80
authentication 2, 7
availability 5
B
Bind specific 128
BPX.DAEMON 41
BPX.FILEATTR.PROGCTL 9, 172, 175
BPX.SERVER 10, 41
BPX.SMF 19
BPX.SRV.DOMINO1 10
BPX.STOR.SWAP 19
BPX.SUPERUSER 18
Browser requirements 65
C
C/C++ 16
caching 17
Calendar Connector 27
CD-ROM 16
Certificate
© Copyright IBM Corp. 2000
Certificate request 103
Client Certificates 111
Common Name 100
Distinguished Name 100
Keysize 100
Level 100
Operational server certificate 98
Self signed 98
Certificate authority 94
Certificates 80
Certification authority 97
Certifier ID 25
CLASSPATH 24
Client certificates 111
Common Name 100, 113
Configuration 5
Configuration merge utility 144
Cookies 80
Credentials 81
Cryptographic 80
D
DASD
fast-write function 16
DASD space requirements 17
DECS 29
Distinguished Name 100
DNS entry 129
domain 25
DOMCON 48
3.0 package 48
Starting the Domino server 50
Startup parameters 50
Stopping the Domino server 52
DOMIHTTP-001 169
0x0102 169
0x175b 170
0x1902 170
0xff99 171
0xff9a 171
DOMIHTTP-o01
0x0107 169
Domino 54
Certificate Authority 97
domain 25
Domino administrator client 32, 55
Domino Application Server 23
191
Domino CA server 114
Domino Certificate Authority 105, 111
Setup 111
Domino Console Interface (DOMCON) 45
Domino Enterprise Connection Services 29
Domino Enterprise Server 23
Domino for IBM HTTP Server 1
Authentication 79
Configuration 5
Configuration merge utility 144
Configuration scenarios 127
Migration 143
Operation 45
Domino Internet Cluster Manager 145
Domino Mail Server 23
Domino Partitioned Servers 23
Domino server
Abnormal terminations 58
Authentication 79
first 25
First in Domain 15
Install program 22
Installation 15
Administrator ID 31
LPA modules 33
Network and Communication Settings 31
Server Audience 29
Installation parameters 22
Monitoring 56
Operation 54
SSL setup 125
Starting 45
Stopping 52
TAR file 21
Domino Servlet Manager 145
Domino Session Authentication 80
Domino shortname 90
Domino UNIX group 8
Domino Web server API 144
Domino Web server API (DSAPI) 2
domino_global_env 47
DOMINS 50
DSAPI 144
E
Electronic certificate 80
Electronic certificates 97
Enterprise Connection Services 29
192
Domino for S/390 and Web Server Integration
environment
variables 24
Environment variable
_DOMIHTTP_DEBUG 155
LIBPATH 11
PATH 11
Environment variables 98
environment variables 5
Error 404 166
Error 500 161, 172
ErrorLog 157
Event Manager 27
extattr
+p 9, 172
command 9
F
failures 18
fast-write 16
files 46
First in Domain 15
First Server in Domain 24
Configuration 26
flag
p 9
FRCA cache 1
Free Time 27
FTP 32
FTP example 20
G
Getting started 15
GWAPI 5, 11, 45
plug-in module 8
GWAPI program 1
H
Hardware requirements 16
help
quick 26
HFS 8, 16
HTTP
hyperlinks 2
HTTP basic authentication 79
httpd.conf 11, 38
httpd.envvars 38
https 80
httpsetup 26
J
I
Java Development Kit 16
Java for OS/390 16
JavaScript 66
IBM HTTP Server 1
Administration 65
Authentication 79
Configuration file 11
Configuration files 37
Display configuration information 64
Installation 35
Directory structure 36
Logging 156
Persistent connections 64
Secure server setup 97
Security environment 41
SSL configuration 108
Started procedure 43
Starting 63
Stopping 63
User ID 7
-vv trace 158
IBM WebSphere Application Server 145
ICH408I 171
ICM 145
IIOP 28
IKEYMAN 97
IMAP 28
IMW_Admin protection 77
IMW0003E Configuration not loaded 157
IMW0240E Access denied - unauthorized program
loaded 161
IMW0241E Access denied - surrogate user setup
error 161
IMW0243E Configuration file /etc/httpd.conf not
found or in error 157
IMWEBSRV 63
Installation Guide
Domino for System 390 15
Installation parameters 22
Internet Message Access Protocol 28
introduction page 69
IPC
Cleanup 129
Resources 129
IPC resources
cleaning up 46
IPCS 54
K
Key ring 97
Key size 113
KeyFile 108
L
Last minute comments 15
LDAP 29
LIBPATH 11, 24, 98
Lightweight Directory Access Protocol 29
LNOTES 90, 167
LocalDomainServers 25
Lotus Domino server
Installation 15
Lotus Notes/Domino shortname 90
LPA 33
M
mapping 7
MDFYBPXP 22
MDFYPROG 33
message queues 46
Microsoft Internet Explorer 66
migration 21
MODIFY command 65
mount statements 22
N
name lookup 7
NAMES.NSF 25
Netscape Communicator 26
Netscape Navigator 65
Network and Communication Settings 31
Network News Transfer Protocol 29
NLSPATH 98
NNTP 29
NoAmbiguousWebNames 7, 171, 175
Normalmode 108
normal-mode 12, 35
notes.ini 7
editing 7
NoAmbiguousWebNames 7
193
notes.rc 46
Notesdata 23
NRPC protocol 128
O
oeditascii 7
Operating
Domino for IBM HTTP Server 45
OS/390 authentication 84, 88
OW35502 152, 166
OW39716 152, 166
P
p flag 9
Parm field 43
Pass rule 12
PATH 11, 24, 98
permissions 5
PersistTimeout 64
Person entry 117
Pickup ID 105
platcreds allow 133
POP3 28
Port 80 128
Post Office Protocol 3 28
private key 80
processes
cleaning up 46
program-control 8, 41
Protection directive 76
PTFs 152
PUBLIC 41
public-key cryptographic 80
PUBNAMES.NTF 25
PUTINLPA 33
Q
quick help 26
R
RACF 9, 18
Digital certificate support 91
LNOTES segment 90
sample commands 42
STARTED 44
surrogate authority 49
RACF profile
194
Domino for S/390 and Web Server Integration
SURROGAT class 10
Release Notes
Domino for System 390 15
rlogin 47
Root certificate 98
S
scalable 2
Schedule Manager 27
SCLBDLL 16
SDSF 48
Secure Web server
Setup 97
security
exposures 7
Self-signed certificate 98
semaphores 46
server
instances
cannot start two 46
shutdown 45
startup 45
server ID 25
server.id 7
ServerInit 13
platcreds allow 133
ServerKeyFilename 7
Session authentication 81
shared memory segments, 46
Shortname 90
shutdown 45
SMP/E 35
Software requirements 16
SSL 12
SSL client certificate authentication 80
SSLClientAuth 126
SSLMode 108
SSLPort 108
sslport 13
Standard Domino authentication 84
startup 45
stash file 98
su command 18
superuser 8, 46
SURROGAT 10
SYS1.PARMLIB 16
BPXPRMxx 22
COMMNDxx 33
LPALSTxx 33
PROGxx 33
T
tar file 21
TCP/IP 16, 164
VIPA 2
telnet 47
Tracing 155
Troubleshooting 151
Trusted signer 94
TSO
console facility 48
WEBADM 77
WEBSRV 7
WLM Application Environment 129
X
X.509 certificates 80
X.509 client certificates 117
U
UID=0 46
UNIX shell commands 8
user ID 25
V
variables
environment 5
viascii 7
VIPA 2
W
Web administrator client interface 55
Web browser 24
Web connector 1
Configuration 5
Operating 45
Web server
Administration ID 41
API filters 144
Configuration files 37
Configuration for SSL 108
Installation 35
Directory structure 36
Key database 103
Scalable 129
Secure server setup 97
Secure setup 97
Started procedure 43
PARM field 43
-vv trace 158
Web server admin GUI 75
Web server administration facility 68
195
196
Domino for S/390 and Web Server Integration
IBM Redbooks review
Your feedback is valued by the Redbook authors. In particular we are interested in situations where a
Redbook "made the difference" in a task or problem you encountered. Using one of the following
methods, please review the Redbook, addressing value, subject matter, structure, depth and
quality as appropriate.
• Use the online Contact us review redbook form found at http://www.redbooks.ibm.com/
• Fax this form to: USA International Access Code + 1 914 432 8264
• Send your comments in an Internet note to redbook@us.ibm.com
Document Number
Redbook Title
SG24-5437-00
Domino for S/390 and Web Server Integration
Review
What other subjects would you
like to see IBM Redbooks
address?
Please rate your overall
satisfaction:
O Very Good
Please identify yourself as
belonging to one of the
following groups:
O Customer
O Business Partner
O IBM, Lotus or Tivoli Employee
O None of the above
Your email address:
The data you provide here may
be used to provide you with
information from IBM or our
business partners about our
products, services or activities.
O Please do not use the information collected here for future
marketing or promotional contacts or other communications beyond
the scope of this transaction.
Questions about IBM’s privacy
policy?
The following link explains how we protect your personal information.
http://www.ibm.com/privacy/yourprivacy/
© Copyright IBM Corp. 2000
O Good
O Average
O Poor
O Solution Developer
197
SG24-5437-00
®
Domino for S/390 and Web Server Integration
SG24-5437-00
Printed in the U.S.A.