Domino for IBM HTTP Server Guide 5.0.9 (Documentation)

DisclaimerTHIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, LOTUS AND IBM DISCLAIM ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS AND IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS AND IBM (OR THEIR SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

CopyrightUnder the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of IBM Corporation, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software.

© Copyright 1985 - 2001 Lotus Development Corporation© Copyright IBM Corporation

Lotus Software, IBM Software GroupOne Rogers StreetCambridge, MA 02142All Rights Reserved. Printed in the United States.

Revision History: Original material produced for Lotus Notes and Lotus Domino Release 5.0.9.

List of Trademarks IBM, the IBM logo, S/390, and WebSphere are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Lotus, Domino, Lotus Notes, and Notes are trademarks or registered trademarks of Lotus Development Corporation and/or IBM Corporation in the United States, other countries, or both. Tivoli/Courier is a trademark of Tivoli Systems Inc. and/or IBM Corporation in the United States, other countries, or both. Other company, product and service names may be trademarks or service marks of others.

Domino for IBM HTTP Server Guide 5.0.9 Contents

iii

Chapter 1 - Introduction 1.......................................................................................Overview 1....................................................................................................................................

Overview 1..............................................................................................................................Where to Find More Information 2................................................................................................

Where to Find More Information 2..........................................................................................Features 4.....................................................................................................................................

Database Security 4...............................................................................................................Optional RACF Authentication 4.............................................................................................Server Document Options 5...................................................................................................Web Application Features 6...................................................................................................

Restrictions 7................................................................................................................................Connections and Logging 7....................................................................................................Internet Cluster Manager 7.....................................................................................................Java Web Agents 7................................................................................................................Servlet Manager 7..................................................................................................................Web Configuration Documents 7............................................................................................Web Server API Filters 8........................................................................................................Domino Off-Line Services 8....................................................................................................

Chapter 2 - Setup and Installation 9.......................................................................Prerequisites 9..............................................................................................................................

Prerequisites 9........................................................................................................................Setup Procedure 10........................................................................................................................

Installation Overview 10...........................................................................................................Preinstallation 11......................................................................................................................RACF Setup Procedure 12.......................................................................................................Setting up the Web Connector 13............................................................................................Optional RACF Authentication Setup 19..................................................................................

Chapter 3 - Using the IBM HTTP Server 23.............................................................Starting and Stopping the IBM HTTP Server 23.............................................................................

Starting and Stopping the IBM HTTP Server 23.......................................................................Recovering from Failures 24...........................................................................................................

Recovering from Failures 24....................................................................................................

Chapter 4 - Troubleshooting 27................................................................................Problem Determination 27..............................................................................................................

Problem Determination 27........................................................................................................Messages and Codes 27................................................................................................................

Messages and Codes 27..........................................................................................................

Chapter 5 - Appendixes 35........................................................................................Appendix A: Authentication 35........................................................................................................

Authentication 35......................................................................................................................Appendix B: Authentication Processing Details 37.........................................................................

Authentication Processing Details 37.......................................................................................Appendix C: Configuration Merge Utility 40....................................................................................

Configuration Merge Utility 40..................................................................................................Appendix D: SPRs 43.....................................................................................................................

SPRs 43...................................................................................................................................

Chapter 6 - Reader Comments 45............................................................................

About Domino for IBM HTTP Server GuideNovember 2001

The Domino for IBM HTTP Server Guide contains the following chapters: Introduction introduces you to the Domino for IBM HTTP Server and summarizes its features and restrictions.

Setup and Installation describes how to set up and install the Domino for IBM HTTP Server.

Using the IBM HTTP Server describes how to start and stop the Domino for IBM HTTP Server, enable tracing and logging, and recover from failure.

Troubleshooting describes how to determine problems and lists the messages and codes.

Appendices contains sections on authentication, authentication details, the Configuration Merge Utility, and Domino for IBM HTTP Server (Web Connector) SPRs.

Readers Comments enables you to send us comments, questions, or concerns about this publication.

Domino for IBM HTTP Server Guide 5.0.9 Chapter 1 - Introduction

Chapter 1 - Introduction

Overview

Server

OverviewThe Domino for IBM HTTP Server (commonly called the Web Connector) is an optional component of Domino for S/390 that enables you to use the IBM HTTP Server to process HTTP requests for Domino databases by browser clients. It allows clients, such as Web browsers, to use the IBM HTTP Server to access Domino data, such as Notes databases. When this optional Domino configuration is in effect, the Web Connector receives all URL requests from browser clients and passes to Domino any requests that include the file extension .NSF, which indicates a request for data in a Domino database. It uses the GWAPI (Go Webserver Application Programming Interface). It can optionally use RACF and RACF-managed internet certificates to validate users' authentication credentials.

The choice of which Web Server to use--the IBM HTTP server or the Domino Web Server that is part of the core Domino server package--should be driven by the features you require and the infrastructure that you have to work with. There are no performance or scale advantages that we have identified that make the IBM HTTP Server solution preferable to the Domino Web Server. If you are already using the IBM HTTP Server and you want to integrate with Domino, then the Web Connector is probably the correct solution for you, since you will already have much of the infrastructure in place. If you have a more conventional Domino environment, or if you exploit Domino-specific interfaces, the Domino Web Server is the logical choice for you. To help you decide how and when to use the Web Connector, see the Domino for S/390 and Web Server Integration Red Book, SG24-5437. This Red Book provides different scenarios and usage examples that will help you to decide which to implement. This book is available at www.s390.ibm.com/products/domino/redbooks. For additional information on the Domino Web Server, see the Domino 5 Administration Help database that comes with the Domino Administrator client. This database is also available at www.notes.net.

1


Where to Find More Information

Server

Where to Find More InformationDomino for S/390 reference materialDomino for S/390 5.0.9 Installation Guide Domino for S/390 5.0.9 Release NotesOS/390 Console Support for Domino

Domino for S/390 Home Page, provides valuable pointers to marketing and technical information. http://www.ibm.com/servers/eserver/zseries/software/domino/

Links to Technical Information for Lotus Domino on S/390http://www.ibm.com/servers/eserver/zseries/software/domino/dom390_devinfo.html

List of required Service and PTF Checker for Domino S/390http://www.ibm.com/servers/eserver/zseries/software/domino/servchoice.html

The latest documentation and macros.for smf record type 108http://www.ibm.com/servers/eserver/zseries/software/domino/smf.html

The Domino S/390 & Notes Doc Library can be found athttp://notes.net/doc

Lotus Notes/Domino Knowledge basehttp://www.support.lotus.com/sims2.nsf/notesdocscat

C api tool kithttp://www.ibm.com/servers/eserver/zseries/software/domino/dom390_devinfo.htmlhttp://www.lotus.com/developers/devbase.nsf/homedata/downloadlist

Domino for S/390 Redbooks Deploying Domino in a S/390 Environment SG24-2182Domino for S/390 and Web Server Integration SG24-5437Enterprise Integration with Domino for S/390 SG24-5150Lotus Domino for S/390 Performance Tuning & Capacity Planning SG24-5149Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products SG24-5682Lotus Domino for S/390 Release 5: Installation Customization and Administration SG24-2083Lotus Domino for S/390 Release 5: Problem Determination Guide SG24-5599Lotus Domino for S/390: Running a Large Domino System ("Best Practices" manual) SG24-5984Porting C Applications to Lotus Domino on S/390 SG24-2092

Links to the Domino Redbooks can be found at:http://www.ibm.com/servers/eserver/zseries/software/domino/redbooks.html

2


Discussion ListCustomers discuss Domino 390 issues on the DOM390-L discussion list.

To subscribe to the DOM390-L discussion, send a note to:

[email protected] include the following line in the body of the note, SUBSCRIBE DOM390-L. Subject: SUBSCRIBE DOM390-L,

After you are subscribed, you will receive further instructions on how to use the mailing list.

OS/390 Publications

39903990/9390 Planning, Installation, and Storage Administration Guide GA32-0100

DFSMSHierarchical File System Usage Guide SG24-5482

JDK Home Page: http://www.ibm.com/servers/eserver/zseries/software/java/

OS/390OS/390 MVS Initialization and Tuning Reference SC28-1752 OS/390 Planning for Installation GC28-1726

OS/390 Planning: Workload Management GC28-1761OS/390 Resource Measurement Facility Report Analysis SC28-1950OS/390 Resource Measurement Facility User's Guide SC28-1949

TCP/IPOS/390 IBM CS: IP Configuration Guide SC31-8725OS/390 IBM CS: IP Configuration Reference SC31-8726OS/390 eNetwork Communication Server IP Configuration SC31-8513OS/390 eNetwork Communication Server IP Planning and Migration SC31-8512TCP/IP Performance Tuning Guide SC31-7188

DB2DB2 Installation Guide GC26-8970DB2 for OS/390 Call Level Interface Guide and Reference SC26-8959

UNIX System ServicesUNIX System Services Planning SC28-1890

Home Page http://www.ibm.com/servers/eserver/zseries/zos/unix

OS/390 Internet library On-line book manager for all OS390 releases, pdf files are also available

http://publibfp.boulder.ibm.com:80/cgi-bin/bookmgr/LIBRARY

OS/390 messages and codes databasehttp://www.ibm.com/servers/s390/os390/bkserv/msg_codes.html

3


LookAtLookAt is an online facility that enables you to look up explanations for z/OS messages and system abends. Using LookAt to find information is faster than a conventional search because in most cases LookAt goes directly to the message explanation.

LookAt is on the Internet at: http://www.ibm.com/servers/eserver/zseries/zos/bkserv/lookat/lookat.html

z/OS 1.2 TCP/IP manuals that discuss resolver z/OS V1R2.0 CS: IP Migration GC31-8773-01z/OS V1R2.0 CS: IP Configuration Reference SC31-8776-01z/OS V1R2.0 CS: IP Configuration Guide SC31-8775-01

Features

Server

Database SecurityAll Domino database security features -- for example, database ACLs and Readers fields -- are supported by the Web Connector. Before Installing the Web Connector, you will need to decide which Authentication method and process is correct for your site.

There are three Authentication methods to choose from: The HTTP Basic Authentication, the SSL Client Authentication or the Domino specific Session Authentication. Both the HTTP Basic and SSL Client Authentications can be used alone or together with the Standard Domino Authentication or the OS/390 Authentication Support. The Domino specific Session Authentication can only be used with the Standard Domino Authentication.

Please review Appendix A for a description of the different Authentication options and Appendix B for detailed description of the authentication processing done by the Domino for IBM HTTP Server.

Server

Optional RACF AuthenticationThe Web Connector's OS/390 authentication support extends the Web authentication process to allow Web users to authenticate for Domino 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 userid 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, the user can provide an SSL internet certificate that has been registered either in RACF, or in the Domino directory, when authenticating via certificates.

The Web Connector's OS/390 authentication support works in two major steps. It first authenticates the Web user as an OS/390 userid, and second, if successful, it maps that OS/390 userid to the corresponding Domino user identity that Domino uses when processing the request.

4


The mapping between OS/390 userids and Domino user identities is done using Domino shortnames. Domino shortnames are one way of identifying Domino users (for example for internet mail) and are assigned to Domino users in their Person documents in the Domino directory. When a Web user wishes to authenticate to Domino using the OS/390 authentication support, the user's Domino shortname must be associated with the user's RACF USER profile so that the correct Domino identity (shortname) can be determined from the user's OS/390 userid.

If the Web Connector is unable to authenticate the Web user as an OS/390 userid (i.e. the first step fails), the connector passes the request to Domino as not-yet-verified, supplying the original username and password and/or internet certificate received with the request. This allows Domino to perform its standard authentication processing for the request. If the connector is able to authenticate the Web user as an OS/390 userid (i.e. the first step succeeds), but there is no Domino shortname associated with the user's RACF profile, the connector passes the request to Domino as an anonymous request, that is without any username/password or internet certificate.

As part of the optional OS/390 Authentication support, the Web Connector allows users to identify and authenticate themselves to Domino using X.509 internet certificates that have been registered in the RACF database. This method of authentication is available when the OS/390 authentication option has been activated and users connect using SSL (via https: URLs).

For information on the concepts involved in performing authentication using client certificates and using the RACF digitial certificate support (including using the RACDCERT command to register internet certificates in the RACF database), refer to the OS/390 Security Server (RACF) Planning: Installation and Migration (GC28-1920), OS/390 Security Server (RACF) Security Administrator's Guide ( SC28-1915), and OS/390 Security Server (RACF) Command Language Reference (SC28-1919) .

Note: The terms internet certificate, client certificate, digital certificate and browser certificate are alternative terms that are often used when describing the authentication of Web users using X.509 certificates. This description uses the term "internet certificate" to be consistent with the terminology used in other parts of the Domino administration documentation. RACF documentation tends to use the term "digital certificate". You should consider these terms synonymous.

A detailed description of the connector's authentication processing, both with and without the Optional OS/390 authentication support, is provided in Appendix B: "Authentication Processing Details."

Server

Server Document OptionsThe Web Connector uses a subset of the native Domino HTTP service settings in the Server document. The following table lists the Server document settings that the native Domino HTTP service uses and indicates which of them the Web Connector uses.

5


Tab Field: Used by Domino for IBM HTTP Server Connector?

Security Internet server authentication: Yes

Ports - Internet Ports - Web

TCP/IP port number: NoTCP/IP port status: YesAuthentication options:

Name & password: YesAnonymous: Yes

<All SSL settings>: No

Internet Protocols - HTTP

Host name: NoBind to host name: NoDNS lookup: NoDefault home page: NoAllow HTTP clients to browse databases: YesMaximum requests over a connection: NoNumber active threads: No<Mapping settings>: No<Enable logging settings>: No<Log file settings>: No<Log file names settings>: No<Exclude from logging settings>: No<Timeouts settings>: No

Internet Protocols - Domino Web Engine

<HTTP Sessions settings>: Yes<Java Servlets settings>: No<POST Data settings>: Yes<Memory Caches settings>: Yes<Character Set Mapping settings>: YesImage conversion format: NoInterlaced rendering: NoDefault lines per view page: YesMaximum lines per view page: YesDefault search results limit: YesMaximum search results limit: YesMake this site accessible to crawlers: Yes

Server

Web Application FeaturesThe Web Connector supports all Web application features available in Domino Designer, including Java Web agents. Please review Chapter 1, Section 03 - Restrictions, Java Web Agents, for important information on Java Web agents.

When you run a Web application using the Web Connector, the Web Connector processes only requests that specify a Domino database -- that is, a file with an .NSF file extension. All other requests -- for example, requests for HTML files and Java applets -- are handled by the IBM HTTP Server.

Applications that access Domino databases generally do not need to be modified when using the Web Connector; however, applications that access other files -- such as, HTML, CGI scripts, and Java servlets -- may need to be modified to work with the Web Connector.

6


Restrictions

Server

Connections and LoggingThe IBM HTTP Server handles network connection and server request logging; therefore, these features on the Domino server are not supported.

Server

Internet Cluster ManagerThe Domino Internet Cluster Manager (ICM) is not supported.

Server

Java Web AgentsThe Web Connector supports Java Web agents, with the following important caveats.

You cannot use both Java Web agents and WebSphere Application Server managed servlets in the 1.same instance of the IBM HTTP Server. The IBM HTTP Server, however, can be configured in WLM goal mode. In such a configuration, there are two instances of the IBM HTTP Server, one dedicated for servlet processing, and the other would be used for Java Web agents. See http://www.s390.ibm.com/products/wlm/ for information on getting started.

Java Web agents are responsible for managing their own threads. Earlier versions of WebSphere had 2.a restriction on the number of threads that could be created in its address space for its own use. This restriction prevented GWAPI/Domino Java Web agents from creating additional threads (which is almost always required) when run through the Web Connector. However, by applying APAR PQ29395, this restriction will be removed. With this fix in place, a properly coded Java Web agent will work through the Web Connector.

Server

Servlet ManagerThe Domino Servlet Manager is not supported. You can use the servlet manager provided with the IBM WebSphere Application Server (WAS). For additional information on the IBM WAS, please visit the following Web sites: WebSphere Application Server for OS/390 documentation http://www-4.ibm.com/software/webservers/appserv/library_390.html and WebSphere Troubleshooter for OS/390 http://www-4.ibm.com/software/webservers/appserv/troubleshooter.html.

Server

Web Configuration DocumentsThe Web Configuration documents defined in the Domino Directory (that is, virtual servers, URL mappings/redirections, realms, and file protection) are not supported. You can protect system files using OS/390 UNIX file permissions.

7


Server

Web Server API FiltersDomino Web server API (DSAPI) filters are not supported.

Server

Domino Off-Line ServicesDomino Off-Line Services (DOLS) is a DSAPI filter that is not supported under Web Connector.

8

Domino for IBM HTTP Server Guide 5.0.9 Chapter 2 - Setup and Installation

Chapter 2 - Setup and Installation

Prerequisites

Server

PrerequisitesInstalling the Web Connector has the following system requirements:

Lotus Domino for S/390 Release 5.0.1or later, configured and workingl

OS/390 version 2.7 or laterl

IBM HTTP Server for OS/390 version 5.1 or laterl

APARs OW35502 (PTF UW90534) and OW39716l

If you wish to use the optional RACF authentication feature, the following service is required to be l

applied to your OS/390 system if running with OS/390 2.7 or 2.8. These PTFs have been incorporated into the base of OS/390 2.9 and above.

If running OS/390 2.7l

PTF: UW60089 APAR: OW38704


If running OS/390 2.8l


Java Web Agent Support: APARs PQ29395 and PQ31202 installed. l

9


Setup Procedure

Server

Installation Overview

Installation Overview

1. The following steps need to be performed under all circumstances

Install the IBM HTTP Server if not already installed. l

Set up SSL connections if you will be using them. (This step is required for the Optional RACF l

Authentication Mechanism.)Set up the Domino HTTP IP/port addresses if you will be using both the IBM HTTP Server and the l

Domino Web Server simultaneously.Define facility and surrogate classes.l

Connect appropriate RACF groups. l

Update the notes.ini file.l

Verify IBM HTTP Server ID has access to /notesdata.l

Set the program-control bit for all of the Domino executable libraries: l

Update the PATH and LIBPATH environment variable.l

Update the IBM HTTP Server's configuration file.l

Start up the Domino for IBM HTTP Server Connector as part of the IBM HTTP Server. l

Verify that it is working correctly by accessing some Domino Database via the Connector, l

including both public databases and databases that require authentication.

(If you will be using the Optional RACF Authentication Mechanism, skip to number 4 below)

2. If you will be using Domino Managed Internet Certificates for Authentication:

Set up the Domino Certificate Authority application database.l

Enable SSL connections. l

Set up the Certificate Authority certificate. l

Activate SSL client authentication.l

Stop and restart the IBM HTTP Server. l

3. Setting Up Domino-managed Internet Certificate Authentication for a User.

Enroll the user in the Domino directory.l

Obtain an Internet/Client Certificate for the user.l

Register the user's internet certificate.l

4. If you will be using the Optional RACF Authentication Mechanism:

Update the RACF IRR.RUSERMAP facility class.l

Update connector's ServerInit directive in the IBM HTTP Server configuration file.l

Ensure that the user's Person document in the Domino directory has a shortname defined.l

Add shortnames for users in the RACF database.l

5. The following optional steps are needed to implement the RACF managed internet certificates.

Add Certificate Authority certificates to the IBM HTTP Server's key database.l

Update the SSLClientAuth directive in the IBM HTTP Server's configuration file. l

Stop and restart the IBM HTTP Server. l

10


6. The following optional steps are needed to implement the RACF managed internet certificate authentication for a client.

Install a internet (digital) certificate in the client's Web browser. l

Use the RACF self-registration sample Web application or use the RACF RACDCERT command l

to set up the certificate for the user.

Server

Preinstallation

Preinstallation

If you have not installed the IBM HTTP Server, follow the steps outlined in the IBM HTTP Server l

Planning, Installing and Using manual (SC31-8690) to install and configure your basic IBM HTTP Server.

You may also use the configuration merge utility provided with the Web Connector as an aid in setting up the IBM HTTP Server instance that will run the Web 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. For additional information on this utility see APPENDIX C.

If you wish to use SSL connections, follow the instructions in the IBM HTTP Server Planning, l

Installing and Using manual to configure the IBM HTTP Server for SSL.

The following steps outline the procedure to set up an SSL connection:

1. Obtain an SSL server certificate for your IBM HTTP Server, or generate a self-signed server certificate for test purposes, and create a key database containing this server certificate.

Note: Although the IKEYMAN utility provides an option to convert existing (from previous releases) keyring files (*.kyr file) to its key database format, IKEYMAN can not be used to migrate a Domino SSL keyring file to be used as an IBM HTTP Server key database. The format of a Domino keyring file is not the same as the format that IKEYMAN can convert. Also, the Domino Server Certificate Management application does not provide an option for exporting an existing server key and certificate. Because of this, it is not possible to reuse a server key and certificate that you may have previously obtained for configuring Domino's built in HTTP task for SSL connections. You will need to set up a new key and certificate for the IBM HTTP Server.

2. Update the SSL-related directives in the IBM HTTP Server's configuration file (/etc/httpd.conf, by default).

3. Stop and restart the IBM HTTP Server after making these changes.

11


4. Verify that SSL is correctly related by attempting to establish an SSL connection with the server using an https:// URL, for example https://<your_server_hostname> to access its welcome page.

You can also verify your SSL setup is working by checking to see that the IBM HTTP Server is listening on the SSL port. To do this, log on to OS/390 and use the onetstat UNIX shell command to get a list of all active TCP/IP connections and listening ports for your system. Look for an entry associated with the IBM HTTP Server's userid and the SSL port number you configured the IBM HTTP Server to use. If you don't find an entry, then there is an error in your SSL setup. Consult the IBM HTTP Server: Planning, Installing and Using manual for troubleshooting tips.

If you wish to run the Domino Web Server at the same time as you use the IBM HTTP Server and the l

Web Connector, you must either use different IP addresses or configure the Domino Web Server and the IBM HTTP Server to use different internet ports, since only one server can listen on a particular port at a time.

Server

RACF Setup Procedure

RACF Setup Procedure

We include sample JCL that performs all of the required and optional RACF commands for installing the product. Please see the JCL DOMSAF sample for instructions on its use. You will have to use the RACF special attribute to run this JCL. Please read the instructions in the JCL very carefully if you choose to use it.

1 The installer ID must have read access to the bpx.fileattr.progctl facility class prior to issuing the commands to set the program-control bit for all the Domino executable libraries.

Example:RDEFINE FACILITY BPX.FILEATTR.PROGCTL UACC(NONE)SETROPTS RACLIST(FACILITY) REFRESHPERMIT BPX.FILEATTR.PROGCTL CLASS(FACILITY) ACCESS(READ) ID(INSTALL)SETROPTS RACLIST(FACILITY) REFRESH

2) Define the BPX.SERVER facility class and SURROGAT class.

Example:RDEFINE FACILITY BPX.SERVER UACC(NONE)SETROPS RACLIST(FACILITY) REFRESHSETROPTS CLASSACT(SURROGAT)

3) Permit the IBM HTTP Server userid update access to the BPX.SERVER Facility Class.

Example:PERMIT BPX.SERVER CLASS(FACILITY) ACCESS(UPDATE) ID(WEBSRV) SETROPTS RACLIST(FACILITY) REFRESHRLIST FACILITY BPX.SERVER AUTHUSER

12


4) Setup the IBM HTTP Server userid to act as a surrogate for the Domino server userid. You will need to repeat these steps for each Domino Server. (See the OS/390 UNIX System Services Planning manual (SC28-1890) for background on surrogate user setup.)

Example:RDEFINE SURROGAT BPX.SRV.<domino server userid> UACC(NONE)PEMIT BPX.SRV.<domino server userid> CLASS(SURROGAT) ID(WEBSRV) ACCESS(READ)SETROPTS RACLIST(SURROGAT) REFRESH

5) Modify the attributes of the Domino Server userid so that it is connected to the IBM HTTP Server RACF/UNIX group (IMWEB, by default). This is required for proper sharing of IPC resources between the Domino server and the IBM HTTP Server running the Web Connector.

You will need to repeat this command for each Domino Server.

Example:CONNECT DOMINO GROUP(IMWEB)

6) You must modify the attributes of the IBM HTTP Server userid (WEBSRV, by default) so that it is connected to the Domino RACF/UNIX group (for example, NOTES). This is required for proper sharing of IPC resources between the Domino server and the IBM HTTP Server running the Web Connector. You can accomplish this by executing the following TSO RACF command from a userid with RACF SPECIAL authority:

Example:CONNECT WEBSRV GROUP(NOTES)

If you will be implementing the optional RACF Authentication, please see the Optional RACF Authentication Set Up section for additional RACF requirements.

Server

Setting up the Web Connector1) Update the notes.ini file

a) 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 can use the viascii or oeditascii utility to examine notes.ini and update this setting if necessary.

b) Use the viascii or oeditascii utility to add the line NoAmbiguousWebNames=1 to notes.ini

Note: 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 NoAmbiguousWebNames configuration setting prevents successful Web user name lookup if the results are not unique. The Web Connector requires this setting to be in effect and checks that it is in effect at initialization. The Web Connector's initialization will fail if this setting does not exist in the Domino server's notes.ini file.

2) Verify that the Domino server ID file does not use a password.

You cannot enter a password when the IBM HTTP Server starts up the Web Connector.

13


3) Verify IBM HTTP Server ID has access to /notesdata

The IBM HTTP Server userid (WEBSRV by default) is usually configured as a UNIX superuser. When it is configured as a superuser, no special action has to be taken to grant it read-write access to the log.nsf, names.nsf, notes.ini, and server.id files. If, however, the IBM HTTP Server userid 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 and permits read-write access to members of that group. You should also ensure that members of the Domino UNIX group have read, write and execute access to the Domino data directory. Refer to the following examples:

Example: $ chgrp notes /notesdata /notesdata/log.nsf /notesdata/names.nsf /notesdata/notes.ini /notesdata/server.id$ chmod g+rwx /notesdata$ chmod g+rw /notesdata/log.nsf /notesdata/names.nsf /notesdata/notes.ini /notesdata/server.id

(In this example, NOTES is the Domino UNIX group and /notesdata is the Domino data directory)

4) Set the program-control bit for all of the Domino executable libraries:

Make sure you use the Installer ID that was granted read access to the bpx.fileattr.progctl facility class in the previous section.

Example:$ cd /usr/lpp/lotus/notes/latest/os390$ extattr +p *

Note: This should be done each time the Domino server release is upgraded.

5) Update the PATH environment variable

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 running Domino in English (that is, in the "C" locale) and installed in the default locations, add the following directories to the PATH environment variable.

Example:/notesdata/usr/lpp/lotus/notes/latest/os390/usr/lpp/lotus/notes/latest/os390/res/C

NOTE1: You should not include the Domino "bin" directory (/usr/lpp/lotus/bin, by default) in the PATH environment variable. Doing so may cause the connector initialization to fail with an error code of 0x1007.

NOTE2: If you're running the IBM HTTP 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're running with some alternate setup, then you probably have a private httpd.envvars file. In addition, if you're running the IBM HTTP Server from a UNIX shell session, you may be inheriting environment variable settings from that shell environment:

6) Update the LIBPATH environment variable

Update the LIBPATH environment variable to include the Domino product executable directory. For example, if you've installed Domino in the default locations, add the following directory to the LIBPATH environment variable:

Example:/usr/lpp/lotus/notes/latest/os390

14


7) Update the IBM HTTP Server's configuration file

Update the IBM HTTP Server's configuration file to add directives to activate the connector GWAPI plugin module and route requests for Domino databases to it. If you're running the IBM HTTP Server from a started procedure using the standard setup, the HTTP Server's configuration file is /etc/httpd.conf. If you're running with some alternate setup, then you probably have a private httpd.conf. In either case, add the following set of directives to the appropriate httpd.conf file before that file's default Pass rule:

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, as follows:

Placeholder Represents Example/Typical value

DOM_DATA_DIR Domino data directory /notesdata

DOM_INST_DIR Domino product installation directory /usr/lpp/lotus

DOM_SERVER_ID Domino server userid domino

SSL_PORT SSL-mode port number 443

ServerInit DOM_INST_DIR/notes/latest/os390/domihttp:ServerInit "-sslport SSL_PORT" < Note 1 & 2>

ServerTerm DOM_INST_DIR/notes/latest/os390/domihttp:ServerTerm

Protection DOMINO-CONNECTOR-SETUP {Mask Anybody < Note 3 >UserId DOM_SERVER_ID

}

NameTrans /icons/* DOM_INST_DIR/notes/latest/os390/domihttp:DomIconsNameTrans / DOM_INST_DIR/notes/latest/os390/domihttp:DomRootCmds

Protect *.nsf DOMINO-CONNECTOR-SETUPProtect *.nsf/* DOMINO-CONNECTOR-SETUPProtect /domicons/* DOMINO-CONNECTOR-SETUPProtect /domjava/* DOMINO-CONNECTOR-SETUP

Service *.nsf DOM_INST_DIR/notes/latest/os390/domihttp:ServiceService *.nsf/* DOM_INST_DIR/notes/latest/os390/domihttp:Service

Pass /domicons/* DOM_DATA_DIR/domino/icons/* < Note 4 >Pass /domjava/* DOM_DATA_DIR/domino/java/*

Note 1:If your Web server is using an SSL-mode port other than 443, you must include the -sslport option on the Web Connector's ServerInit directive.

15


The -sslmode option does not change the SSL-mode port number being used by the Web server. 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 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 Connector's 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.

Note 2: 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 Web 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.

Note 3:The purpose of the "Mask Anybody" directive shown above is to request that the IBM HTTP Server perform no access-control checking for requests that it passes through to the Web Connector. However, all normal Domino security mechanisms apply because they are enforced by the Web Connector and Domino while processing the request.

Note 4: 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. The block of directives shown above must appear before the configuration file's default Pass rule (the "Pass /* <someplace>" rule) otherwise they will not have the correct effect.

Example with the symbolic substitution:ServerInit /usr/lpp/lotus/notes/latest/os390/domihttp:ServerInit "-sslport 443"ServerTerm /usr/lpp/lotus/notes/latest/os390/domihttp:ServerTerm

Protection DOMINO-CONNECTOR-SETUP {Mask AnybodyUserId domino

}

NameTrans /icons/* /usr/lpp/lotus/notes/latest/os390/domihttp:DomIconsNameTrans / /usr/lpp/lotus/notes/latest/os390/domihttp:DomRootCmds

Protect *.nsf DOMINO-CONNECTOR-SETUPProtect *.nsf/* DOMINO-CONNECTOR-SETUPProtect /domicons/* DOMINO-CONNECTOR-SETUPProtect /domjava/* DOMINO-CONNECTOR-SETUP

Service *.nsf /usr/lpp/lotus/notes/latest/os390/domihttp:ServiceService *.nsf/* /usr/lpp/lotus/notes/latest/os390/domihttp:Service

Pass /domicons/* /notesdata/domino/icons/*Pass /domjava/* /notesdata/domino/java/*

16


Optional:

Enabling the Use of Domino-Managed CertificatesPerform the following steps to enable the Web Connector to perform authentication using the Domino-managed Internet ( X.509 ) certificates: As part of its support for the standard Domino Web authentication model, the Web Connector allows users to identify and authenticate themselves to Domino using X.509 client (browser) certificates that have been registered in the Domino directory. This method of authentication is available when users connect using SSL.

IMPORTANT NOTE: If you will be using the Optional OS/390 Authentication support, then you are done with the Base Install and you should continue with the OS/390 Authentication Set up section.

These steps will enable the Web Connector to perform authentication using the Domino managed X509 certificates. The procedures for issuing and/or registering Domino-managed internet certificates via the Domino Certificate Authority application/database are the same whether you are using the built-in HTTP task or the Web Connector. Consult the Domino Administering the Domino System manual for information on using the Domino Certificate Authority application. After you have set up the Domino Certificate Authority application database you will use to issue and/or register your internet certificates, perform the following steps to enable the Web Connector to perform authentication using the Domino-managed X.509 certificates:

8) Set up the Domino Certificate Authority application database

If the Domino Certificate Authority application database is not already set up, set it up now . This is the database you will use to issue/or register your internet certificates. See the Domino Administration Guide and the Domino 5 Administration Help for additional information.

9) Enable SSL connections

If you have not already done so, update the IBM HTTP Server configuration to enable the use of SSL connections as described in the Preinstallation section. Client certificates can be used only on SSL connections.

10) CA Certificate Set up

Obtain the certificate authority (CA) certificate for the certificate authority that is signing your client certificates, and then use the IBM HTTP Server's Key Management Utility (IKEYMAN) to add this CA certificate to the IBM HTTP Server's key database, and mark this CA as a trusted signer. The IBM HTTP server will not accept a client certificate from a browser unless it finds the certificate signer in its key database, marked as a trusted signer. Consult the documentation for your CA to determine how to obtain its CA certificate. For additonal information on CA certificates and the IKEYMAN utility see the HTTP Server Planning, Installing, and Using manual (SC31-8690)

11) Activate SSL client authentication

Update the IBM HTTP Server's configuration file (/etc/httpd.conf by default) to activate SSL client authentication. Edit the file /etc/httpd.conf (or the httpd.conf file for your IBM HTTP Server configuration if you are using a different configuration file) and change the setting of the SSLClientAuth directive to be:

SSLClientAuth local

The SSLClientAuth directive controls the type of SSL client authentication in effect for the IBM HTTP Server. The default value is "off". Setting this value to "local" instructs the IBM HTTP Server to request client certificates from browsers when they establish SSL connections with the IBM HTTP Server. (SSL connections are requested by using URLs that specify "https:" as the protocol.) With this setting, the IBM HTTP Server validates the certificates provided by clients by checking that the certificates are signed by a certificate authority (CA) marked as trusted in the server's local key database.

17


Note: Do not use set the SSLClientAuth directive to the "passthrough" setting. This setting is intended for use with GWAPI application functions or CGI scripts that perform their own validity checking of the certificates provided by clients. The Web Connector does not perform such checking, but rather relies on the IBM HTTP Server to perform validity checking on the certificates.

12) Stop and restart the IBM HTTP Server.

The change to the SSLClientAuth directive does not take effect until the IBM HTTP Server is stopped and restarted.

13) Verify set up

Verify that it is working correctly by accessing some Domino databases via the Web Connector, including both public databases and databases that require authentication.

Setting Up Domino-managed Internet Certificate Authentication for a Client

After completing the above steps to enable the use of Domino-managed certificates with the Web Connector, follow these steps to permit a client to authenticate for Web requests using Domino-managed internet certificates:

14) Enroll the user in the Domino directory.

Create a person document in the Domino NAB (name and address book). Refer to the Domino Administration Guide for the procedure.

15) Obtain an Internet/Client Certificate for the user

Obtain an internet/client certificate for the user from the Certificate Authority you are using, and install that certificate in the user's Web browser. Consult the documentation for the Certificate Authority you are using for the procedure to follow to accomplish this.

16) Register the client's internet certificate

Use the Domino Certificate Authority application to register the user's internet certificate in the Domino directory, associating it with the user's Domino Person document.

NOTE: If you are using the Domino Certificate Authority application to issue your internet certificates, this step can be performed automatically at the time the administrator approves the certificate request for the user. Refer to the Domino Administration Guide for information on the Domino Certificate Authority application.

With the above changes in effect, when the user connects to the IBM HTTP Server using an SSL (https:) connection, 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 trusted signer. Assuming it is, if the URL request is for a Domino database and is thus handled by the Web Connector (and the OS/390 Authentication option is not enabled), the Web Connector will obtain the certificate from the IBM HTTP Server and pass it to Domino as part of the request. Domino will use the certificate to determine the Domino user (Person document in the Domino directory) making the request in the same way it determines the Domino user associated with client certificates provided via the built-in HTTP task. The Domino user name determined by this lookup will be used to perform ACL checking for protected databases.

18


Server

Optional RACF Authentication SetupTo activate the Optional RACF Authentication Mechanism perform steps 1 thru 3.

To activate the Optional RACF managed internet (digital) certificates authentication perform steps 1 thru 6.

To enable the optional RACF managed Internet (digital) certificate authentication for a client, perform all the steps 1 thru 8.

We include sample JCL that performs all of the required and optional RACF commands for installing the product. Please see the JCL DOMSAF sample for instructions on its use. You will have to use the RACF special attribute to run this JCL. Please read the instructions in the JCL very carefully if you choose to use it.

1. Give the IBM HTTP Server userid authority to use the RACF application identity mapping service.

Permit the IBM HTTP Server userid Read access to the the identity mapping service facility class IRR.RUSERMAP (IRRSIM00).

Example:RDEFINE FACILITY IRR.RUSERMAP UACC(NONE)PERMIT IRR.RUSERMAP CLASS(FACILITY) ID(WEBSRV) ACCESS(READ)SETROPTS RACLIST(FACILITY) REFRESHNote: In this example, WEBSRV is the IBM HTTP Server userid

2. Activate the Connectors OS/390 Authentication Processing

To activate the connector's OS/390 Authentication processing, edit the IBM HTTP Server configuration file in use by your IBM HTTP Server instance. The IBM HTTP Server's configuration file (/etc/httpd.conf, by default) already includes a sequence of connector-related directives, including a Serverlnit directive.

Update the connector's ServerInit directive to add the option "-platcreds allow" to the connector's initialization string, as shown in bold below:

ServerInit PATHNAME/domihttp:ServerInit "-sslport SSL_PORT -platcreds allow"

The PATHNAME and SSL_PORT placeholders shown above should have already been filled in with values for your configuration; leave those values unchanged. Also, ensure that the entire set of initialization options on the ServerInit directive (everything following the domihttp:ServerInit part) are 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 connector will report syntax errors with the initialization options.

19


3. Define mappings between OS390 userids and Domino userids.

3a. Ensure that the user's Person document in the Domino directory has a shortname defined, and that shortname uniquely identifies that Person in the Domino directory.

Important Note: The shortname can be from 1 to 64 characters in length and contain lower or upper case alphabetic characters, the characters '0' through '9', '&' (ampersand), '-' (dash), '.' (period), '_' (underscore) and blank. Shortnames that do not meet these restrictions can not be used with the OS/390 authentication support because RACF limits the shortnames registered in the RACF user profile to these characteristics.

3b. The shortname specified in the LNOTES(SNAME) operands below should match the shortname defined for the user in the Domino directory. The following are examples of how to add or delete the shortnames for a user in the RACF database.

To create a new userid to RACF with the LNOTES segment (Domino shortname):l

ADDUSER NEWID LNOTES(SNAME('NEW_GUY')) PASSWORD('password')

Note: In this example the RACF Userid is NEWID with a domino shortname of NEW_GUY.

To update an exisiting RACF userid with a new LNOTES segment: (Domino shortname)l

ALTUSER TSOID LNOTES(SNAME('TSO_GUY'))

Note: In this example the RACF Userid is TSOID with a domino shortname of TSO_GUY.

To remove the LNOTES segment (Domino shortname) from an existing RACF userid, use l

either the NOLNOTES operand or the LNOTES(NOSNAME) operand:

ALTUSER NEWGUY NOLNOTES

- or -

ALTUSR NEWGUY LNOTES(NOSNAME)

To list the Domino shortname associated with a RACF uesrid.l

LISTUSER TSOID LNOTES

Note: In this example the RACF Userid is TSOID

The following optional steps are needed to implement the RACF managed internet certificates.

As part of the optional OS/390 Authentication support, the Domino for IBM HTTP Server connector allows users to identify and authenticate themselves to Domino using X.509 internet certificates that have been registered in the RACF database. This method of authentication is available when the OS/390 authentication option has been activated and users connect using SSL (via https: URLs).

4. Enable the use of RACF managed Internet certificates

Obtain the CA certificate for the certificate authority that is signing the client certificates that you will be registering in RACF, and then use the IBM HTTP Server's Key Management Utility (IKEYMAN) to add this CA certificate to the IBM HTTP Server's key database, and mark this CA as a trusted signer. The IBM HTTP server will not accept a client certificate from a browser unless it finds the certificate signer in its key database, marked as a trusted signer. Consult the documentation for your CA to determine how to obtain its CA certificate. For additonal information on CA certificates and the IKEYMAN utility see the HTTP Server Planning, Installing, and Using manual (SC31-8690)

20


5. Activate SSL client authentication

Update the IBM HTTP Server's configuration file (/etc/httpd.conf by default) to activate SSL client authentication. Edit the file /etc/httpd.conf (or the httpd.conf file for your IBM HTTP Server configuration if you are using a different configuration file) and change the setting of the SSLClientAuth directive to be:

SSLClientAuth local

The SSLClientAuth directive controls the type of SSL client authentication in effect for the IBM HTTP Server. The default value is "off". Setting this value to "local" instructs the IBM HTTP Server to request client certificates from browsers when they establish SSL connections with the IBM HTTP Server. (SSL connections are requested by using URLs that specify "https:" as the protocol.) With this setting, the IBM HTTP Server validates the certificates provided by clients by checking that the certificates are signed by a certificate authority (CA) marked as trusted in the server's local key database.

Note: Do not use set the SSLClientAuth directive to the "passthrough" setting. This setting is intended for use with GWAPI application functions or CGI scripts that perform their own validity checking of the certificates provided by clients. The Domino for IBM HTTP Server connector does not perform such checking, but rather relies on the IBM HTTP Server to perform validity checking on the certificates.

6. Stop and restart the IBM HTTP Server.

The change to the SSLClientAuth directive does not take effect until the IBM HTTP Server is stopped and restarted.

The following optional steps are needed to enable RACF managed internet certificate authentication for a client. Before enabling the optional RACF managed internet certificate authentication for a client , the steps above all need to be completed. The Domino for IBM HTTP Server requires that the OS/390 userid to Domino identity mappings be defined. The use of RACF-managed certificates takes the place of using an OS/390 userid and password for authenticating Web requests. The result of this certificate authentication process is that the Web user is identified as an OS/390 userid, just as if userid and password authentication is used. The Domino identity mapping is required so the user's identify can then be translated to a Domino identity (shortname) before passing the request to Domino for processing.

7. Obtain an internet (digital) certificate for the user from the certificate authority you are using, and install that certificate in the user's Web browser. Consult the documentation for the certificate authority you are using for the procedure to follow.

8. The RACF support for digital (internet) certificates includes a self-registration sample Web application that can be used to permit users to register their digital certificates in RACF. To use this sample, Consult the OS/390 Security Server (RACF) Administration Guide ( SC28-1915).

You can also register the user's internet certificate by following the steps below.

1) Using the user's Web browser, export the internet certificate in a format that is compatible with the certificate formats accepted by the RACF RACDCERT command.

2) Transfer the exported certificate to your OS/390 system, storing it in a sequential dataset. (You cannot place the certificate in an HFS file because the RACDCERT command does not operate on HFS files.)

3) Use the RACDCERT command to obtain the certificate from the dataset in step two above and associate it with the RACF User's profile. For additional information on the RACDCERT command see the OS/390 V2R6.0 Security Server (RACF) Security Administrator's Guide, and OS/390 Security Server (RACF) Command Language Reference (SC28-1919) .

21


With the above changes in effect, the following will occur: When a user connects to the IBM HTTP Server using an SLL (https:) connection, the IBM HTTP Server will request a client certificate from the browser. The IBM HTTP Server will verify that the certificate provided by the browser is signed by a trusted signer. Assuming it is, if the URL request is for a Domino database and is thus handled by the Domino for IBM HTTP Server connector (and assuming the OS/390 Authentication option is enabled), the connector obtains the certificate from the IBM HTTP Server and passes it to RACF as part of its processing to try to authenticate the Web user as an OS/390 user. If the Web user is successfully authenticated as an OS/390 user via this certificate, then the certificate provided by the browser will not be passed to Domino. Instead, the results of the mapping of the OS/390 userid to a Domino user identity are passed to Domino. If the OS/390 authentication processing is not successful, the certificate is passed to Domino for Domino to use in its standard authentication processing.

22

Domino for IBM HTTP Server Guide 5.0.9 Chapter 3 - Using the IBM HTTP Server

Chapter 3 - Using the IBM HTTP Server

Starting and Stopping the IBM HTTP Server

Server

Starting and Stopping the IBM HTTP ServerThe Web Connector runs as an integral part of the IBM HTTP Server process. You start and stop the Web Connector by starting and stopping the IBM HTTP Server instance in which the Web Connector runs.

Important Note: Due to the design of the Web Connector, it is necessary to stop (and then later restart) the IBM HTTP Server instance in which the Web Connector is running any time the Domino Server is being stopped, or terminates abnormally. In the case of an IBM HTTP Server running as a scaleable server subsystem exploiting Workload Manager (WLM), it is necessary to stop the WLM Application Environments (APPLENVs) being used to process Domino/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 Web Connector can be properly cleaned up. This IPC cleanup is necessary for a successful restart of your Domino and Web Connector environment.

Starting the Web ConnectorStart the Domino server if it is not running already.

Note: The Domino server must be running while the Web Connector is running in order to allow Notes clients to access the Domino server, and to allow the Domino server to run important server tasks such as mail routing and replication. The Domino server can run any tasks including the Domino Web Server that is part of the core Domino server package. However, if you wish to run the Domino Web Server at the same time as you use the IBM HTTP Server and the Web Connector, you must either use different IP addresses or configure the Domino Web Server and the IBM HTTP Server to use different internet ports, since only one server can listen on a particular port at a time.

Start the IBM HTTP Server. The IBM HTTP Server loads the Web Connector automatically and runs it as part of the IBM HTTP Server process. Depending on how you set up the IBM HTTP Server, you can start it from the system console as a started procedure, or you can start it from a UNIX shell session. Refer to the IBM HTTP Server: Planning, Installing and Using manual (SC31-8690) for more information on starting and running the IBM HTTP Server.

Stopping the Web Connector You must shut down the IBM HTTP Server in order to stop the Web Connector. For information on shutting down the IBM HTTP Server, refer to the IBM HTTP Server: Planning, Installing and Using manual.

It is not necessary to stop the Domino server when you stop the IBM HTTP Server and the Web Connector running in it, provided that the IBM HTTP Server stops normally. If the IBM HTTP Server and the Web Connector stop normally, you can stop and restart the IBM HTTP Server and the Web Connector while Domino server continues to run. However, if you are going to stop the Domino server, you must first stop the IBM HTTP Server (and thus the Web Connector) first. Also, if the IBM HTTP Server or the Web Connector terminates abnormally or is canceled, you must stop the Domino Server as part of the recovery procedure.

23


Starting and Stopping the IBM HTTP Server and Domino Server Using the OS/390 Console Support for DominoYou can use the Domino Console support to start and stop the IBM HTTP Server along with the Domino Server. The console support observes the required start and stop sequencing between the two, ensuring that the IBM HTTP Server is started after the Domino Server on startup and is stopped before the Domino Server on shutdown. To direct the console support to provide this function, enable the SRVxx_WAS environment variable for the appropriate Domino Server in the console support's domino_global_env file. Set the value for this variable to the name of the proc that starts/stops the IBM HTTP Server (normally IMWEBSERV). Processing for the DOMINS proc will them start both the Domino Server and the IBM HTTP server (in that order). Similarly, processing for the DOMINK proc will stop first the IBM HTTP Server and then the Domino server. Refer to the Domino Console User's Guide for more detailed information regarding Domino Console setup and use.

Recovering from Failures

Server

Recovering from FailuresIf either the Domino server, or the IBM HTTP Server in which the Web Connector is running, terminates abnormally or is canceled, it is possible Domino IPC resources may not have been cleaned up properly and will cause restart of the Domino server and/or the Web Connector to fail. If either the Domino Server or the IBM HTTP Server fails, perform the following steps to recover:

Try to stop the IBM HTTP Server normally, for example by using the STOP console command if the l

server is running as a started task. If this is unsuccessful, force the IBM HTTP Server to terminate by using the CANCEL console command (if running as a started task), or by using the UNIX shell kill command to send a SIGTERM signal to the IBM HTTP Server process (kill -9 or kill -KILL).

Try to stop the Domino server normally, using the server's quit command. If normal shutdown fails, l

force the Domino server to terminate using the Domino "nsd -kill" command from another UNIX shell session logged on as the Domino server userid. For example:

/usr/lpp/lotus/bin/tools/diag/nsd -kill

After both the IBM HTTP Server and the Domino server have terminated, log on to the OS/390 system l

as the Domino server userid, and use the UNIX shell "ipcs -a" command to verify that all server IPC resources have been removed.

If the "ipcs -a" command does not show any IPC resources owned by the Domino server userid, then l

cleanup was successful and you can start the Domino server and then the IBM HTTP Server as described above.

If the "ipcs -a" command displays some IPC resource owned by the Domino server, use the Domino l

"nsd -kill" command shown above to remove the IPC resources, and again verify that they have been removed using the "ipcs -a" command again. If the "nsd -kill" command is successful in removing the IPC resources, you can start the Domino server and the IBM HTTP Server as described above. If not, use the UNIX shell ipcrm command to remove the IPC resources manually.

See the OS/390 UNIX System Services Command Reference manual (SC28-1892) for information on the UNIX shell ipcrm, ipcs, and kill commands.

24


Failure recovery using OS/390 Console support for DominoUnder most conditions, running the DOMINK proc will stop the server(s) and provide subsequent resource cleanup if needed. Always try running the DOMINK proc with the default type parameter (type=n) first. This allows the servers to attempt a normal shutdown before any resource cleanup is performed. When a normal shutdown attempt is unsuccessful, run DOMINK with the type=q parameter. This function forcibly kills the server processes and also provides ipcs resource cleanup. If this is not effective, follow the suggestions above.

25

Domino for IBM HTTP Server Guide 5.0.9 Chapter 4 - Troubleshooting

Chapter 4 - Troubleshooting

Problem Determination

Server

Problem DeterminationThe Web Connector can optionally issue debug/trace messages to the IBM HTTP Server's trace log. These messages may be helpful in diagnosing problems for IBM Support personnel. You should only set this variable if you are having problems which you will need IBM assistance on. These messages are controlled by the _DOMIHTTP_DEBUG environment variable. You can set this variable in the /etc/httpd.envvars file or in the current shell with the following command: export _DOMIHTTP_DEBUG=n. If it is set in both locations, then the value in the httpd.envvars will override the shell setting. If running from a non-Shell environement file Domino for S/390 Console Support, then you will need to use the httpd.envvars file.

Setting this variable to an integer value of 9 activates messages, a value of 0 will turn them off.

With the variable set to 9, the IBM HTTP Server's trace log includes debug trace messages.

Messages and Codes

Server

Messages and CodesMessage DOMIHTTP-001: Unable to initialize interface to dominoExplanation:The Web 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. Refer to the following list that summarizes the error codes, for suggestions on resolving the error:

Action:Refer to the following reason code that is displayed with message DOMIHTTP-001 in the server's trace and error logs for additional information.

27


Reason Codes

0x0102 (PKG_OS, ERR_PROTECTED) - Cannot write or create file (file or disk is read-only)Explanation:When this occurs during initialization, it is because the HTTP Server process, running under the security identity of the Domino server userid, does not have write access to the names.nsf database. The Domino server userid being used by the connector is the userid that is listed as the owner of the notes.ini file.

Action:Ensure that the correct Domino data directory is listed in the IBM HTTP Server's PATH environment variable, and use the "ls -l" command to check that the notes.ini file in that directory is owned by the correct userid. Use the "chown" command to correct the ownership of notes.ini if required. Also, check the ownership/permissions of the names.nsf file, and use the "chown" and "chmod" commands to change the ownership/permissions associated with this file so that the Domino server userid has write access.

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. 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.

0x0107 (PKG_OS, ERR_MEMORY) - Insufficient memoryExplanation:There is not enough memory for the IBM HTTP Server.

Action:Set the region size of the job running the IBM HTTP Server to be region=0k. If running from a login session, ensure there is a sufficient region size.

x0111 (PKG_OS, ERR_NO_MORE_FILES)Explanation:Domino initialization can not find the Domino executables directory, Default location: /usr/lpp/lotus/notes/latest/os390). Domino determines the location of its executable directory by searching the directories listed in the PATH environment variable for the Domino executable programs.

Action: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 the PATH environment variable can cause Domino to incorrectly conclude that it is the Domino executable directory.

0x1007 Explanation: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. Default Location: usr/lpp/lotus/notes/latest/os390. Domino determines the location of its executables directory by searching the directories listed in the PATH environment variable for the Domino executable programs.

28


Action: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 the PATH environment variable can cause Domino to incorrectly conclude that it is the Domino executable directory.

0x175b (ERR_BSAFE_WRITE_PROTECTED) - The ID file is write protectedExplanation:The HTTP Server process, running under the security identity of the Domino server userid, 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 ServerKeyFile variable in notes.ini Default Location: /notesdata/server.id. The Domino server userid being used by the connector is the userid that is listed as the owner of the notes.ini file.

Action:Ensure that the correct Domino data directory is listed in the IBM HTTP Server's PATH environment variable, and use the "ls -l" command to check that the notes.ini file in that directory is owned by the correct userid. Use the "chown" command to correct the ownership of notes.ini if required.

Check the ownership/permissions of the server.id file, and use the "chown" and "chmod" commands to change the ownership/permissions associated with this file so that the Domino server userid has write access.

Use the RLIST command to verify that the IBM HTTP Server userid has UPDATE access to the BPX.SERVER facility class profile. example: RLIST FACILITY BPX.SERVER AUTHUSER

READ access to this profile is NOT sufficient. To verify you have set up the BPX.SERVER facility class correctly, please review Chapter 2 Setup and Installation - The RACF set up procedure section.

0x1902 (PKG_SECURE_ERR_SECURE_NOKEYFILE) - Could not open the id fileExplanation:This error results from a number of underlying errors:

The notes.ini file could not be found. Domino searches the current directory and then the directories listed in the PATH environment variable for this file and could not locate the file.

The notes.ini file was found, but the HTTP server process, running under the security context of the Domino server userid, does not have write access to the file. The Domino server userid being used by the connector is the userid listed as the owner of the notes.ini file.

The IBM HTTP Server userid does not have UPDATE access to the BPX.SERVER facility class.

Action:Add the Domino data directory to the IBM HTTP Server's PATH environment variable.

Ensure that the correct Domino data directory is listed in the IBM HTTP Server's PATH environment variable, and use the "ls -l" command to check that the notes.ini file in that directory is owned by the correct userid. Use the "chown" and "chmod" command to correct the owner/permissions of the notes.ini file so that the Domino server userid has write access.

Use the RLIST command to verify that the IBM HTTP Server userid has UPDATE access to the BPX.SERVER FACILITY-class profile. Example: RLIST FACILITY BPX.SERVER AUTHUSER

READ access to this profile is not sufficient. To verify you have set up the BPX.SERVER facility class correctly, please review Chapter 2 Setup and Installation - The RACF set up procedure section.

29


0xff99 Explanation:The Domino server is not configured to require unambiguous Web user names using the NoAmbiguousWebNames Domino setting. Domino for IBM HTTP requires this setting in order to avoid potential security exposures in its translation of OS/390 credentials to Domino credentials

Action:Use the viascii utility to add the following setting to the notes.ini file for your Domino server:

NoAmbiguousWebNames=1

0xff9a Explanation:Domino initialization could not find the notes.ini file in either the current directory nor any of the directories named in the PATH environment variable.

Action:Add the Domino data directory to the IBM HTTP Server's PATH environment variable.

Message DOMIHTTP-014: Unable to determine the Domino Server's uid

Explanation:Message DOMIHTTP-014 is issued to the IBM HTTP Server's standard output/job log and error log during Web server initialization. The Domino for IBM HTTP Server connector was not able to determine the Domino server's UNIX uid. It needs this uid in order to set up the proper security context for processing requests. The connector determines the Domino server's uid by finding the server's notes.ini file in one of the directories listed in the PATH and using the uid recorded as the owner of that file.

Action:Ensure that the Domino data directory (eg. /notesdata) is listed in the IBM HTTP Server's PATH environment variable and check that this directory contains the notes.ini file.

Ensure that the IBM HTTP Server userid is a member of the Domino UNIX group (eg. NOTES). If it is not, use the CONNECT command to add the IBM HTTP Server userid to that group. For example: CONNECT WEBSRV GROUP(NOTES)

Ensure that the Domino UNIX group has read access to the log.nsf, names.nsf, notes.ini and server.id files, and read-write and execute permission ("r" "w" and "x" permission bits) to the Domino data directory. If it does not, use the "chgrp" and "chmod" shell command to give the Domino UNIX group the required permissions.

For example:chgrp notes /notesdata /notesdata/log.nsf /notesdata/names.nsf /notesdata/notes.ini /notesdata/server.idchmod g+rwx /notesdatachmod g+rw /notesdata/log.nsf /notesdata/names.nsf /notesdata/notes.ini /notesdata/server.id

(In this example, NOTES is the Domino UNIX group and /notesdata is the Domino data directory)

30


Message DOMIHTTP-015: Unable to determine the Domino server's userid

Explanation:Message DOMIHTTP-015 is issued to the IBM HTTP Server's standard output/job log and error log during Web server initialization. The Domino for IBM HTTP Server connector was not able to determine the Domino server's OS/390 userid. It needs this userid in order to set up the proper security context for processing requests. It determines the Domino server's userid using the server's notes.ini file. Although the connector was able to find the server's notes.ini file and determine its UNIX uid from that file, it was not able to translate the UNIX uid into its corresponding OS/390 userid..

Action:Ensure that the correct Domino data directory (eg. /notesdata) is listed in the IBM HTTP Server's PATH environment variable: The connector uses the first notes.ini file it finds by searching the directories listed in the PATH environment variable.

Ensure that the Domino server's notes.ini file is owned by a properly-defined OS/390 userid. Use the UNIX shell's "ls -l" command to display the attributes of the file. If the command shows a numeric uid value for the owning user rather than a user name, then that uid is not associated with an OS/390 userid. Use the shell's "chown" command to change the owner of the file to the Domino server userid. For example: chown domino /notesdata/notes.ini

Message DOMIHTTP-016: Insufficient authority to BPX.SERVER profile

Explanation:Message DOMIHTTP-016 is issued to the IBM HTTP Server's standard output/job log and error log during Web server initialization. The Domino for IBM HTTP Server connector processes all requests under the identity (security context) of the Domino server userid. However, the connector was unable to set up the necessary security context because the userid running the IBM HTTP Server has not been authorized to use the security-context-switching services.

Action:Use the RLIST command to verify that the IBM HTTP Server userid has UPDATE access to the BPX.SERVER FACILITY-class profile. For example: RLIST FACILITY BPX.SERVER AUTHUSER

READ access to this profile is not sufficient. To verify you have set up the BPX.SERVER facility class correctly, please review Chapter 2 (Setup and Installation), Section 02 (Setup Procedure), RACF Setup Procedure.

Message DOMIHTTP-017: A non-program-controlled module has been loaded

Explanation:Message DOMIHTTP-017 is issued to the IBM HTTP Server's standard output/job log and error log during Web server initialization. The Domino for IBM HTTP Server connector processes all requests under the identity (security context) of the Domino server userid. The system services used to set up the necessary security context require that all of the modules (e.g. executable programs and DLLs) loaded into the IBM HTTP Server's address space come from datasets or HFS files that are marked as program controlled. One or more modules have been loaded from non-program-controlled datasets or HFS files, causing the connector's attempt to establish the necessary security context to fail.

31


Action:First, verify that the IBM HTTP Server's execution environment is properly program controlled without the connector being active. Remove the connector-related directives from your server's httpd.conf file (ServerInit, ServerTerm, NameTrans and Service directives that refer to "domihttp"). Then start the IBM HTTP Server and have it serve some requests that run under the identity of the Web client (with userid %%CLIENT%% in effect), or that run under some surrogate identity (with userid <userid> in effect). If the IBM HTTP Server reports errors regarding unauthorized programs being loaded, then the problem is that the IBM HTTP Server's basic environment is not properly program controlled.

Ensure that the following modules/datasets are property defined as program controlled:

System load library (SYS1.LINKLIB)l

Language Environment load library (SCEERUN dataset)l

C++ run-time library load library (SCLBDLL dataset)l

CBC.SCBCCMPl

SYS1.CSSLIB, l

TCPIP.SEZALINK all have to be set as welll

IBM HTTP Server modules in HFS under /usr/lpp/internet/sbin l

Java modules in the HFS under /usr/lpp/java/J1.1/lib/mvs/native_threadsl

You can verify the above datasets are program controlled by entering the following command from a a User ID with the the RACF Special Attribute set.

RLIST PROGRAM * ALL

You can verify this for the HTTP Server modules and the Java modules by entering the following commands in Unix System Services.

ls -E /usr/lpp/internet/sbinls -E /usr/lpp/java/J1.1/lib/mvs/native_threads

Consult informational APARs II10548 and II08176 , OS/390 Unix System Services Planning (SC28-1890), and the IBM HTTP Server documentation for information on resolving program-control problems (dirty environment).

If the IBM HTTP Server is working correctly without the connector being active, but you encounter message DOMIHTTP-017 with the connector, the likely cause is that the connector DLL or one of the Domino DLLs is not marked as program-controlled. Use the "ls -E" UNIX shell command to verify that the program-controlled external attribute is set for all of the files in the /usr/lpp/lotus/latest/os390 directory. If not, use the "extattr +p" command to set the program-controlled extended attribute.

For Example: extattr +p /usr/lpp/lotus/latest/os390/*

Message DOMIHTTP-018: Insufficient authority to BPX.SRV.userid profile

Explanation:Message DOMIHTTP-018 is issued to the IBM HTTP Server's standard output/job log and error log during Web server initialization. The Domino for IBM HTTP Server connector processes all requests under the identity (security context) of the Domino server userid. However, the connector was unable to set up the necessary security context because the userid running the IBM HTTP Server has not been authorized to act as a surrogate for the Domino Server userid.

Action:You must make sure that the webserver userid (for example: WEBSRV) has read access to the the BPX.SRV.domino server user id SURROGAT class.

32


Example:

RLIST SURROGAT BPX.SRV.WEBSRV AUTHUSER

Please review Chapter 2 (Setup and Installation), Section 02 (Setup Procedure), RACF Setup Procedure.

Message DOMIHTTP-019: Unable to create thread-level security contextThe errno2 value provided in this message is the OS/390 UNIX System Services reason code for the failure. Look up this reason code in the OS/390 UNIX System Services Messages and Codes manual (SC28-1908) to determine the reason for the failure and to determine corrective actions.

Message ICH408I (Insufficient access authority) for BPX.SRV.userid profileExplanation: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 profiles for the Domino Server userid. The Web Connector processes all requests under the identity (security context) of the Domino Server userid. However, the userid running the IBM HTTP Server has not been authorized to act as a surrogate for the Domino Server userid.

Action:You must make sure that the webserver userid (for example: WEBSRV) has read access to the the BPX.SRV.domino server user id SURROGAT class.

Example:

RLIST SURROGAT BPX.SRV.WEBSRV AUTHUSER

Please review Chapter 2 Setup and Installation - The RACF set up procedure. section.

Message ICH408I (Insufficient access authority) for BPX.SRV.userid profile

Explanation: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 profiles for the Domino Server userid. The Web Connector processes all requests under the identity (security context) of the Domino Server userid. However, the userid running the IBM HTTP Server has not been authorized to act as a surrogate for the Domino Server userid.

Action:Use the TSO command to verify that the IBM HTTP Server userid has been given READ access to the SURROGAT-class profile for the Domino Server userid. For example, if the Domino Server userid is DOMSRV, this profile is called BPX.SRV.DOMSRV and it can be listed with the following command:

Example:

RLIST SURROGAT BPX.SRV.DOMSRV AUTHUSER

If this profile has not been defined, it can be defined with the TSO RDEFINE command, for example:

RDEFINE SURROGAT BPX.SRV.DOMSRV UACC(NONE)

If the profile is defined but IBM HTTP Server userid is not listed, use the TSO PERMIT command to grant it READ access to this profile. For example, if the IBM HTTP Server userid is WEBSRV, access can be granted with the command:

Example:

PERMIT BPX.SRV.DOMSRV CLASS(SURROGAT) ID(WEBSRV) ACC(READ)

33


Browser Error 500: IMW0240E Access denied - unauthorized program loaded

Explanation:The browser receives an Error 500 response, with message IMW0240E (Access denied - unauthorized program loaded) after a user responds to a browser username/password challenge for access to some URL. This error may occur even if the request is for something other than a Domino database. One or more modules (programs or DLLs) have been loaded into the IBM HTTP Server's address space from HFS files or datasets that are not defined as program controlled.

Action:See the troubleshooting description for message DOMIHTTP-017.

Browser Error 500: IMW0241E Access denied - surrogate user setup error

Explanation:The browser receives an Error 500 response, with message IMW0241E (Access denied - surrogate user setup error) when a user enters a URL to access a Domino database. You may also receive this message as a response for non-Domino requests. The connector-related Protection directives in the IBM HTTP Server's httpd.conf file specify that requests handled by the connector should be processed under the identity (security context) of the Domino server userid. This message indicates that the IBM HTTP Server was not able to establish the proper security context for processing the request.

Action:First, check the IBM HTTP Server's standard output/job log and error log to verify that the Domino for IBM HTTP Server connector is initializing cleanly. In particular, look for connector-issued errors DOMIHTTP-016, -017, -018 or -019 (all of which are related to setting up a surrogate-user security context) and resolve any problems indicated by those messages.

If the connector is initializing cleanly and you still receive this browser error message, the following are possible causes:

The userid directive in effect for processing Domino database requests specifies the wrong userid. l

Make sure this directive specifies the OS/390 userid for the Domino server. Locate the Domino Server's notes.ini file and use the "ls -l" shell command to check that this same userid is listed as the owner of the notes.ini file.

One or more modules (programs or DLLs) have been loaded into the IBM HTTP Server's address l

space from HFS files or datasets that are not defined as program controlled.

If this is the cause of the IMW0241E error, the IBM HTTP Server's trace log may also include an error message reporting an errno2 value of 0x0be802af.

See the troubleshooting information for message DOMIHTTP-017 for suggestions on how to resolve this problem.

34

Domino for IBM HTTP Server Guide 5.0.9 Chapter 5 - Appendixes

Chapter 5 - Appendixes

Appendix A: Authentication

Server

AuthenticationWhen a Web user accesses a database through the IBM HTTP Server running the Web Connector, 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. The process of determining and verifying a user's identity is called authentication.

Web User Authentication Methods

The Web Connector supports the following three methods: HTTP Basic Authentication, SSL Client Certificate Authentication, and Session Authentication.

1. HTTP Basic Authentication:

This method is sometimes called username and password authentication. In this method, when a Web user attempts to access 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 authentication "realm"), the browser prompts the user to enter a username and password, then reissues the request supplying this information as the user's 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.

This method can be used with the standard Domino Web authentication process and optional OS/390 authentication process, described below, under Authentication Processes.

2. SSL Client Certificate Authentication:

This method uses X.509 certificates in conjunction with secure/SSL (https:) connections. X.509 certificates are also sometimes referred to as internet certificates. In this method, a Web user configures his or her browser to hold an internet certificate (and corresponding private key) that identities 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 internet certificate. Using public-key cryptographic techniques, the Web server verifies that the internet certificate belongs to the user that supplied it, and verifies that the certificate is trustworthy by checking that the certificate has been issued by a trusted issuer or certificate authority. The certificate is used to identify the user. Client certificate authentication can only be used on secure/SSL (https:) connections.

This method can be used with the standard Domino Web authentication process and optional OS/390 authentication process, described below, under Authentication Processes.

35


3. Session Authentication:

This method is specific to Domino. 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.

This method can be used only with the standard Domino Web authentication process, described below, under Authentication Processes.

Authentication Processes

Standard Domino Web Authentication Process: 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 Web Connector treats all authentication credentials received from Web users, that is usernames and passwords or internet certificates, as being Domino usernames/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 internet certificate received with the request. These credentials are used by 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. In the case of certificate authentication, Domino uses information in the certificate to locate the user's Person document. This Domino Web authentication processing is the same as that done for Web requests made through Domino's built-in HTTP task.

Optional OS/390 Authentication Process: The Web Connector's OS/390 authentication support extends the Web authentication process to allow Web users to authenticate for Domino request 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 userid and password, or their Domino username and internet password when challenged to provide a username and password as part of HTTP Basic authentication. Similarly, the user can provide an SSL internet certificate that has been registered either in RACF, or in the Domino directory, when authenticating via certificates. For additonal information on this support see the "Optional RACF Authentication" section in this manual.

36


Appendix B: Authentication Processing Details

Server

Authentication Processing DetailsThis section provides a detailed description of the authentication processing done by the Web Connector.

Standard Domino Authentication Only (OS/390 Authentication Support Disabled)

In its default configuration, the Web Connector treats all security credentials it receives from Web users as being Domino (rather than OS/390) credentials. The Web Connector passes all requests to Domino as not-yet-verified requests, passing along the original username and password and/or internet 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. If the Web user makes a request anonymously, that is without supplying either a username/password or internet certificate, Domino processes the request as the "Anonymous" user.

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.

In the case of SSL requests that include internet certificates, the IBM HTTP Server plays a role in the authentication process. As part of the process of establishing the SSL connection and accepting the certificate from the browser, the IBM HTTP Sever 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, the IBM HTTP Server does not accept the certificate from the browser, and request processing continues as if no certificate were supplied.

With OS/390 authentication Support Enabled

Anonymous Requests:

If a Web user makes a request anonymously, that is without supplying any username/password nor internet certificate, the connector passes the request to Domino without any security credentials. Domino processes the request as the Anonymous user. If the Web user's 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.

Requests with Basic Authentication Credentials:

If a Web user makes a request and that request includes a Basic Authentication username and password, the Web Connector first uses the username and password to attempt to authenticate the user as OS/390 userid using RACF and, if successful, then maps that OS/390 userid 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 Web Connector either passes the original username and password to Domino (for use by Domino's standard Basic Authentication process) or passes the request to Domino as an Anonymous request. The complete process is as follows:

37


First, the Web Connector considers the username and password supplied with the request as being l

an OS/390 userid and password and attempts to verify the userid and password using RACF. If the verification succeeds, the process continues to the next step. If this verification fails, the OS/390 authentication process ends and the Web 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.

If the username and password were successfully verified as being an OS/390 userid and password, l

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 the USER profile has a shortname associated with it, the process continues to the next step. If not, the OS/390 authentication process ends and the Web 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 l

verifies this shortname with Domino to ensure that it is a valid shortname registered in the Domino directory. If this verification succeeds, the Web Connector passes the request to Domino as a pre-authenticated request, specifying the Domino shortname as the user's security credentials. If this verification fails, the Web 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.

SSL Requests with Internet Certificates:If a Web user makes a request using an SSL connection and provides an internet certificate signed by a trusted signer, the Web Connector first uses that certificate to attempt to authenticate the user as OS/390 userid using RACF digital certificate support and, if successful, then maps that OS/390 userid 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 Web Connector either passes the original certificate to Domino (for use by Domino standard certificate Authentication process) or passes the request to Domino as an Anonymous request. The complete process is as follows:

As part of establishing the SSL connection with the Web browser, the IBM HTTP Server obtains the l

internet certificate from the browser and verifies that the certificate is signed by certificate authority that is marked as trusted in the IBM HTTP Server's key database. If the certificate is signed by a trusted signer, the process continues to the next step. Otherwise, the certificate is not accepted by the IBM HTTP Server and thus not passed to the Web Connector. The Web Connector passes the request to Domino without any security credentials (that is, as an anonymous request).

The Web Connector considers the certificate to be one that identifies an OS/390 userid and attempts l

to maps that certificate to the corresponding OS/390 userid using RACF digital certificate support. If this mapping succeeds, the process continues to the next step. If this verification fails, the OS/390 authentication process ends and the Web Connector passes the request to Domino as a not-yet-authenticated request, passing the certificate to Domino as the user's security credentials along with the request. This certificate is used by Domino as part of its normal certificate authentication process.

If the certificate is successfully mapped to an OS/390 userid, the Web Connector uses the RACF l

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 the USER profile has a shortname associated with it, the process continues to the next step. If not, the OS/390 authentication process ends and the Web Connector passes the request to Domino without any security credentials (that is, as an anonymous request).

38



verifies this shortname with Domino to ensure that it is a valid shortname registered in the Domino directory. If this verification succeeds, the Web Connector passes the request to Domino as a pre-authenticated request, specifying the Domino shortname as the user's security credentials. If this verification fails, the Web Connector passes the request to Domino without any security credentials (that is, as an anonymous request). The original certificate provided with the request are not passed to Domino.

SSL Requests with Internet Certificates and Basic Authentication Credentials:

It is possible for an SSL request to have both an internet certificate and Basic Authentication username and password credentials. If a Web user makes such a request using an SSL connection and provides an internet certificate signed by a trusted signer, the Web Connector first uses the certificate to attempt to authenticate the user as OS/390 userid using RACF. If that fails, the Web Connector then tries to use the Basic Authentication username and password as an OS/390 userid and password and verify them using RACF. If either of these authentication methods succeeds, the Web Connector map that OS/390 userid 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 Web Connector either passes the original username and password and certificate to Domino (for use by Domino standard certificate and basic authentication processes) or passes the request to Domino as an Anonymous request. The complete process is as follows:

As part of establishing the SSL connection with the Web browse, the IBM HTTP Server obtains the l

internet certificate from the browser and verifies that the certificate is signed by certificate authority that is marked as trusted in the IBM HTTP Server's key database. If the certificate is signed by a trusted signer, the process continues to the next step. Otherwise, the certificate is not accepted by the IBM HTTP Server and thus not passed to the Web Connector. Processing continues as if no certificate were provided, as described above for "Requests with Basic Authentication Credentials."

The Web Connector considers the certificate to be one that identifies an OS/390 userid and attempts l

to map that certificate to the corresponding OS/390 userid using RACF's digital certificate support. If this mapping succeeds, the process continues to the next step. If this verification fails, the Web Connector attempts to use the username and password as an OS/390 userid and password and verify them using RACF. If this verification succeeds, the process continues with the next step. If both the certificate and the username/password fail to authenticate the Web user as an OS/390 user, the OS/390 authentication process ends and the Web Connector passes the request to Domino as a not-yet-authenticated request, passing both the certificate and the username/password 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 userid, l

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 the USER profile has a shortname associated with it, the process continues to the next step. If not, the OS/390 authentication process ends and the Web Connector passes the request to Domino without any security credentials (that is, as an anonymous request).


verifies this shortname with Domino to ensure that it is a valid shortname registered in the Domino directory. If this verification succeeds, the Web Connector passes the request to Domino as a pre-authenticated request, specifying the Domino shortname as the user's security credentials. If this verification fails, the Web 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.

39


Appendix C: Configuration Merge Utility

Server

Configuration Merge UtilityThe Configuration Merge Utility works by starting with an existing IBM HTTP Server configuration file (for example a copy of the sample httpd.conf file provided with the IBM HTTP Server) as the base file into which values are merged. It also obtains the values of selected HTTP-related fields, listed below, from a specified Server document in the Domino directory. For each of the fields it processes, the utility maps the field to a corresponding IBM HTTP Server configuration directive, as indicated in the table below. If the corresponding configuration directive is found in the base file, the utility comments out each existing occurrence of the directive using a comment that starts with "#DOMIHTTP:", and adds below the commented-out directive a new (not-commented-out) directive that specifies the value from the Server document. If the directive corresponding to a field is not found in the base file, the utility adds a new directive to the end of the file. It writes the resulting configuration file as a new file. The original base configuration file is left unchanged. You should review the merged output file after it is created and verify that the merged settings are the values you want to keep. Look for the "#DOMIHTTP:" comment to see the changes made by the utility.

Running the Utility:

The Configuration Merge Utility is a Notes C API application that is run from the UNIX System Services shell. As a Notes C API application, it has setup requirements similar to those for all Notes applications. Note that you don't have to shut down the Domino Server to run this utility. Before running the utility, you should update the settings for the userid you will run it from so that:

The Domino data directory for the Domino server (for example, /notesdata) is listed in the PATH l

environment variable. The directories listed in PATH are searched to locate the notes.ini file for the Domino Server configuration.

The userid is a member of the Domino UNIX group for your Domino server (for example, NOTES).l

The userid has read/write access to the Domino data directory, and to the notes.ini, names.nsf and l

server.id files located in the Domino data directory. The utility does not change data in any of these files, but write access is required for successful initialization of the Notes API.

You may want to consider running the utility from the Domino server userid since it already has been set up to have the required characteristics.

Invoke the utility from a UNIX shell session using the following syntax:

/usr/lpp/lotus/bin/tools/domihttp_cfgmerge

[-n <NAB_DB>] [-d <BASE_HTTP_CONF>]

[-s <SERVER_NAME>] [-o <OUTPUT_HTTPD_CONF>]

You should enter the command on a single line; it has been split here for readability.

The utility accepts the following options:

-n <NAB_DB>Specifies the name of the Domino directory database. The default is names.nsf. If you specify this database name as a relative pathname, it is interpreted as being relative to the Domino data directory for your Domino server, as is usually done for Notes applications.

40


-d <BASE_HTTP_CONF>Specifies the name of the existing IBM HTTP Server configuration file which is used as the base file for the merge. Specify <BASE_HTTP_CONF> as the (absolute or relative) pathname of the configuration file in the HFS. If you specify the base configuration file name as a relative pathname, it is interpreted as being relative to the current directory.

The default value is /etc/httpd.conf.

-o <OUTPUT_HTTPD_CONF>Specifies the name of the merged output configuration file written by the utility. Specify <OUTPUT_HTTPD_CONF> as the (absolute or relative) pathname of the output file you want. If you specify the output file name as a relative pathname, it is interpreted as being relative to the current directory.

By default, the utility will create a file in the current directory with the same base name as <BASE_HTTP_CONF> plus the suffix ".merge." For example, if the default value for <BASE_HTTP_CONF> is used (/etc/httpd.conf), the default output file is httpd.conf.merge in the current directory. If you specify the -o option, the <OUTPUT_HTTPD_CONF> name is used as specified, without appending the ".merge" suffix.

-s <SERVER_NAME>Specifies the name of the Server document to process. If your Domino directory contains only one Server then this option is optional. Otherwise, it is required. Specify <SERVER_NAME> as the hierarchical name of the Server entry (for example myserver/myorgunit/myorg) you wish to extract HTTP-related fields from. You can also specify <SERVER_NAME> as simply the first component of the hierarchical name if that uniquely identifies the Server document within the Domino directory.

Fields Processed by the Utility:

The following table lists the Server document fields processed by the configuration-merge utility, and the IBM HTTP Server configuration directive each is mapped to.

Domino Server Document Tab Field Label (Field Name): IBM HTTP Server directive

Ports - Internet Ports - Web TCP/IP port number (HTTP_Port): PortTCP/IP port status (HTTP_NormalMode): NormalModeSSL port number (HTTP_SSLPort): SSLPortSSL port status (HTTP_SSLMode): SSLModeClient certificate (HTTP_SSLCert): SSLClientAuth

Internet Protocols - HTTP - Basics

Host name(s) (HTTP_HostName): HostNameBind to host name (HTTP_BindToHostName): BindSpecificDNS lookup (HTTP_DNSLookUp): DNS-LookupNumber active threads (HTTP_MaxActiveThreads): MaxActiveThreads

Internet Protocols - HTTP - Log File Settings

Time format (HTTP_LogTime): LogTime

Internet Protocols - HTTP - Exclude From Logging

URLs (HTTP_ExcludeURLs): AccessLogExcludeURLMethods (HTTP_ExcludeMethods): AccessLogExcludeMethodMIME types (HTTP_ExcludeMIMETypes): AccessLogExcludeMimeTypeReturn codes (HTTP_ExcludeReturnCodes): AccessLogExcludeReturnCodeHosts and Domains (HTTP_NoLog): NoLog

Internet Protocols - HTTP - Timeouts

Input timeout (HTTP_InputTimeout): InputTimeoutOutput timeout (HTTP_OutputTimeout): OutputTimeoutCGI timeout (HTTP_ScriptTimeout): ScriptTimeout

41


Troubleshooting:

If the utility issues an error message regarding "Error from NSFDbOpen, sysrc=28", check to ensure these items are setup:

The userid invoking the utility has read-write permission to the Domino Server's notes.ini file.l

Check to ensure that the notes.ini file contains the keyword Directory. The Directory keyword should l

be set to the path where the notes data can be found.

42


Appendix D: SPRs

Server

SPRsThe following SPRs for the Web Connector were fixed in the releases as indicated. For a complete list of Domino for S/390 SPRs, see the Domino for S/390 Release Notes.

Fixed in Release 5.0.3:SPR # DescriptionJGDC4GSMQH Web Connector: HTTP Server loops on shutdown or restart when running with

WASJGDC4GSNW6 Web Connector: Error 503 on all requests after HTTP Server is restartedJGDC4GSRGG Web Connector: Intermittent program check during termination when running in

WLM-mode queue serverJGDC4GSRYS Web Connector: Hang during shutdown when Web connector is first/only Domino

process

Fixed in Release 5.0.2:SPR # DescriptionJGDC4DALUE Web Connector: Init and Term aren't being runJGDC4DRJFV Web Connector reports internal error when browser session closed in

mid-transmissionJGDC4DRJSV Acrobat reader refetches entire document for each page viewed when using Web

connectorJGDC4E5N6U Web connector user not challenged for new username/password when using

OS/390 authentication

Fixed in Release 5.0.1:SPR # DescriptionJGDC4ALQPZ Web Connector crashes IBM HTTP Server instead of reporting "Lotus Notes

Exceptions" to browserJGDC4ALRCD Web Connector initialization fails with 0x1007 error when ltscu2e.tlb not in current

directoryJGDC4AM54Z Web Connector: Inotes starts JVM at initialization time, conflicting with

WebSphere servlet supportJGDC4AM5MV Web Connector: Internal error occurs during OS/390 authentication with cert and

no basic auth credsJGDC4B4KTW Web Connector: OS/390 authentication checking of Domino shortname is case

sensitive but shouldn't beYLFH4ANK3N Random characters on http view with Web connector

43

Domino for IBM HTTP Server Guide 5.0.9 Chapter 6 - Reader Comments

Chapter 6 - Reader Comments

Reader Comments

Server

Reader CommentsReader Comments Form

Domino for S/390 Version 5.0.9IBM HTTP Server Connector Guide

We appreciate your feedback. Please tell us how we can improve this document:

How to Notify Us:

By e-mail: [email protected]

On the Web: http://www.s390.ibm.com/os390/webqs.html

By FAX: (International Access Code)-1-845-432-9405

By Mail: IBM CorporationDept. 55JA, Mail Station P3842455 South RoadPoughkeepsie, NY 12601-5400USA

In your mailings, please include the name of this publication and the page or section number.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.

May we contact you? Yes No

Name:

Company or organization:

Address:

Phone Number:

e-mail address:

45