Vous êtes sur la page 1sur 488

Lotus Domino for S/390 Release 5: Installation, Customization and Administration

Mike Ebbers, Marco Foellmer, Joachim Heinrich, Andre Mueller, Simon Williams

International Technical Support Organization www.redbooks.ibm.com

SG24-2083-02

International Technical Support Organization Lotus Domino for S/390 Release 5: Installation, Customization and Administration December 1999

SG24-2083-02

Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix H, Special notices on page 421.

Third Edition (December 1999) This edition applies to Version 5 Release 5 of Lotus Domino for S/390 for use with the OS/390 Operating System V2R6 or V2R7. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. HYJF Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1998, 1999. All rights reserved. Note to U.S Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiii The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Comments Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Part 1. Planning for Notes on the S/390 platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Chapter 1. The value of Lotus Domino on S/390 . . . . . 1.1 What Lotus Domino R5 is . . . . . . . . . . . . . . . . . . . . . 1.1.1 Domino R5 and the competition . . . . . . . . . . . . 1.2 What Lotus Notes R5 is . . . . . . . . . . . . . . . . . . . . . . 1.2.1 Benefits of R5 . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.2 New Lotus Notes R5 client interface . . . . . . . . . 1.3 Domino Application Studio . . . . . . . . . . . . . . . . . . . . 1.4 Lotus Domino R5 family of servers and clients . . . . . 1.5 New terminologies used in Lotus Notes Release 5 . . 1.6 Available platforms . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7 S/390 is just another server platform . . . . . . . . . . . . . 1.7.1 S/390 as an application server . . . . . . . . . . . . . 1.8 The unique benefits of S/390 as a Domino platform . 1.8.1 The value of a large Domino server . . . . . . . . . . 1.8.2 Other unique S/390 benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 . .4 . .5 . .6 . .7 . .8 . .9 .10 .12 .13 .13 .14 .14 .15 .17

Chapter 2. Notes deployment using S/390 servers . . . . . . . . . . . . . . . . . . .23 2.1 Planning for Notes deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 2.1.1 About selecting a pilot application . . . . . . . . . . . . . . . . . . . . . . . . . . .23 2.1.2 About identifying a workgroup for initial rollout . . . . . . . . . . . . . . . . .23 2.1.3 About taking an inventory of existing network infrastructure . . . . . . .24 2.1.4 About assessing hardware and software needs . . . . . . . . . . . . . . . . .25 2.1.5 About preparing for administration and support . . . . . . . . . . . . . . . . .26 2.1.6 About developing administrative processes . . . . . . . . . . . . . . . . . . . .26 2.2 Understanding the Notes environment . . . . . . . . . . . . . . . . . . . . . . . . . . .27 2.3 Planning a Notes system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 2.3.1 About dedicating servers by task . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 2.3.2 About connecting Notes servers . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 2.4 Populating Notes with servers and users . . . . . . . . . . . . . . . . . . . . . . . . .27 2.5 Planning a replication strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 2.6 Developing a plan for Notes mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 2.7 Maintaining a Notes system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 2.8 Maintaining security in a Notes system . . . . . . . . . . . . . . . . . . . . . . . . . . .28 2.8.1 Notes internal security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29 2.9 Planning for optimal performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29 2.10 Extending your Notes system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 2.11 Using Notes with the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 2.12 Notes directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 2.12.1 How Domino data is stored on OS/390 . . . . . . . . . . . . . . . . . . . . . .30 2.12.2 Space restriction when running DFSMS 1.4 and earlier . . . . . . . . . .32 2.12.3 Implications of UNIX directory size . . . . . . . . . . . . . . . . . . . . . . . . .33 iii

Copyright IBM Corp. 1999

2.12.4 Structuring Notes directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.12.5 Naming standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.13 Domino in a Parallel Sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.13.1 Restart on an alternate OS/390 image using Virtual IP Addressing 2.13.2 Shared access to operational data . . . . . . . . . . . . . . . . . . . . . . . . . 2.13.3 Exploitation of CTC connections through a coupling facility . . . . . . 2.14 Migrating a host mail system to Domino on S/390 . . . . . . . . . . . . . . . . . 2.14.1 Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.14.2 Coexistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.15 More information on deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

34 39 40 40 41 41 42 42 45 47

Part 2. Installing the Domino Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Chapter 3. Prerequisites . . . . . . . . . . . . 3.1 Hardware . . . . . . . . . . . . . . . . . . . . . . 3.1.1 Processor . . . . . . . . . . . . . . . . . 3.1.2 DASD space . . . . . . . . . . . . . . . 3.1.3 Workstation . . . . . . . . . . . . . . . . 3.2 Software . . . . . . . . . . . . . . . . . . . . . . 3.2.1 OS/390 release level . . . . . . . . . 3.2.2 TCP/IP . . . . . . . . . . . . . . . . . . . . 3.2.3 A Lotus Notes workstation client 3.3 Skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 51 51 51 51 51 52 54 55 55 57 57 58 60 62 62 63 64 64 64 65 66 66 67 71 71 72 73 74 74 74 77 77 77 81 82 82 82

Chapter 4. Prepare the OS/390 operating environment . . . . . . 4.1 Customize the OS/390 UNIX environment . . . . . . . . . . . . . . . 4.1.1 UNIX System Services customization . . . . . . . . . . . . . . 4.1.2 TCP/IP customization . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Set OS/390 parameters for the Domino Server . . . . . . . . . . . 4.2.1 System resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Make Domino Server tasks non-swappable . . . . . . . . . . . . . . 4.4 How to remove non-swappability for a task . . . . . . . . . . . . . . 4.5 Define user IDs to OS/390 Security Services (RACF) . . . . . . 4.5.1 OS/390 UNIX security . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5.2 HFS file authorization . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5.3 Authorization of the user who will install Domino Server 4.5.4 Authorization of the Domino Server when it runs . . . . . . 4.5.5 Defining a user to RACF with UNIX authority . . . . . . . . . Chapter 5. Prepare to install the Domino Server . . . . . . . . 5.1 Task checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Collect the information you will need . . . . . . . . . . . . . . . . 5.3 Review the documentation. . . . . . . . . . . . . . . . . . . . . . . . 5.4 Upload the installation files to OS/390 . . . . . . . . . . . . . . . 5.4.1 Allocate two OS/390 data sets . . . . . . . . . . . . . . . . . 5.4.2 Upload the files using FTP . . . . . . . . . . . . . . . . . . . . 5.4.3 Upload the files using IND$FILE (Send/Receive) . . . 5.4.4 Check the files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.5 Allocate HFS data sets (ALOCPROD) . . . . . . . . . . . 5.5 Use MDFYBPXP to mount the HFS data sets at IPL time 5.6 Load the server code into the HFS . . . . . . . . . . . . . . . . . 5.6.1 Copy the tar file into HFS. . . . . . . . . . . . . . . . . . . . . 5.6.2 FTP the tar file into HFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

iv

Lotus Domino for S/390 R5 Installation, Customization and Administration

5.7 Untar the server code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 Chapter 6. Installing a Domino Server . . . . . . . . . . . . . . . . . . . 6.1 NLS considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Task Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Description of Domino Server installation and configuration . 6.3.1 Domino Server terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.2 Domino Server installation program . . . . . . . . . . . . . . . 6.3.3 Domino Server configuration program . . . . . . . . . . . . . . 6.4 Server installation information . . . . . . . . . . . . . . . . . . . . . . . . 6.5 Running the installation program. . . . . . . . . . . . . . . . . . . . . . 6.5.1 Interactive installation . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5.2 Running the install program using the script . . . . . . . . . 6.6 Verifying path statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85 .85 .86 .86 .86 .87 .87 .89 .90 .90 .98 .99

Chapter 7. Configuring a Domino Server . . . . . . . . . . . . . . . . . . . . . . . . .101 7.1 Setting up the first Domino Server in a domain . . . . . . . . . . . . . . . . . . . .102 7.2 Setting up additional Domino Servers . . . . . . . . . . . . . . . . . . . . . . . . . . .104 7.3 Running the server configuration program. . . . . . . . . . . . . . . . . . . . . . . .106 7.4 Rerunning the setup process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115 7.5 Downloading important files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 7.5.1 Using FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117 7.5.2 Using send/receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117 7.5.3 Recovering a lost or corrupted file . . . . . . . . . . . . . . . . . . . . . . . . . .117 7.5.4 Detaching the user.ID file from the Name and Address Book . . . . .117 7.6 What to do next. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118 Chapter 8. Preparing Dynamic LPA . . . . . . . . . . . . . . . . . . . . . . 8.1 Putting Domino modules into Dynamic LPA . . . . . . . . . . . . . . 8.1.1 Change PARMLIB to load Dynamic LPA modules at IPL . 8.2 Loading the Dynamic LPA modules. . . . . . . . . . . . . . . . . . . . . 8.2.1 Considerations when upgrading from previous releases . 8.3 Start the server and verify that it is working . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. . . . . . . . . . . . . .119 .119 .122 .123 .123 .124

Chapter 9. Start, stop and monitor the server . . . . . . . . . . . . . . . . . . . . . .127 9.1 Ways to operate the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 9.1.1 Domino Administrator Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 9.1.2 Web browser using the Domino Web Administrator . . . . . . . . . . . . .128 9.1.3 Workstation using rlogin or Telnet . . . . . . . . . . . . . . . . . . . . . . . . . .128 9.1.4 TSO screen using OMVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128 9.1.5 IOS/390 operator console: DOMCON . . . . . . . . . . . . . . . . . . . . . . .129 9.1.6 Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 9.2 Starting the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 9.2.1 Checklist before you start the server . . . . . . . . . . . . . . . . . . . . . . . .130 9.2.2 Logon with the server user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133 9.2.3 Starting the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134 9.3 Starting the server in the background using rc.notes . . . . . . . . . . . . . . . .136 9.3.1 Customization for rc.notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 9.3.2 Starting the server with rc.notes . . . . . . . . . . . . . . . . . . . . . . . . . . .140 9.4 Stopping the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140 9.4.1 Stopping the server from the server console . . . . . . . . . . . . . . . . . .140 9.4.2 Stopping the server using the concom utility . . . . . . . . . . . . . . . . . .141 9.4.3 Stopping the server using the character console . . . . . . . . . . . . . . .143 9.4.4 Stopping the server from the Domino Administrator client . . . . . . . .144 v

9.4.5 Stopping the server using the Web Administrator. . 9.5 Monitoring the status of the server . . . . . . . . . . . . . . . . . 9.5.1 From an OS/390 console . . . . . . . . . . . . . . . . . . . . 9.5.2 From the UNIX System Services environment . . . . 9.5.3 From the server . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.6 What to do if the server does not start or stop . . . . . . . . 9.6.1 Terminating the server with nsd -kill. . . . . . . . . . . . 9.6.2 Additional options in nsd . . . . . . . . . . . . . . . . . . . . 9.6.3 Cleaning up the server resources manually . . . . . . 9.7 DOMCON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.7.1 Accessing the DOMCON package . . . . . . . . . . . . . 9.8 Monitoring the Domino Server using SMF . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

.. .. .. .. .. .. .. .. .. .. .. ..

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . .

.. .. .. .. .. .. .. .. .. .. .. ..

147 148 148 150 153 155 156 158 159 160 160 161 163 163 164 166 167 173 175 175 176 177 177 179 181 182 182 183

Chapter 10. Lotus Domino R5 and the Internet . . . . . . . . . . . . . . 10.1 Lotus Domino Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.1.1 Setting up a Domino Web server . . . . . . . . . . . . . . . . . . . 10.1.2 Starting, stopping and refreshing the Domino Web server 10.1.3 Lotus Domino virtual Web servers . . . . . . . . . . . . . . . . . . 10.1.4 Managing Java servlets on a Web server. . . . . . . . . . . . . 10.2 Internet cluster manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.2.1 Server Web navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3 NNTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3.1 Starting and stopping an NNTP server . . . . . . . . . . . . . . . 10.3.2 Configuring newsfeeds . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3.3 Creating a newsgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.4 LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.4.1 Lotus Domino R5 and LDAP . . . . . . . . . . . . . . . . . . . . . . 10.4.2 Installation and configuration . . . . . . . . . . . . . . . . . . . . . . 10.4.3 Starting and stopping the LDAP server task . . . . . . . . . . .

... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...

Part 3. Advanced installation topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Chapter 11. Domino Enterprise Server. . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Domino Enterprise Server lab environment . . . . . . . . . . . . . . . . . . . . . 11.2 Domino Enterprise Server installation . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Domino Server partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3.1 Planning a partitioned server deployment . . . . . . . . . . . . . . . . . . 11.3.2 Domino partitioning and S/390 logical partitioning . . . . . . . . . . . . 11.3.3 Configuring partitioned servers for TCP/IP . . . . . . . . . . . . . . . . . . 11.3.4 Setting up partitioned servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3.5 Installing partitioned servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3.6 Considerations for Internet server tasks . . . . . . . . . . . . . . . . . . . . 11.3.7 Starting and stopping partitioned servers . . . . . . . . . . . . . . . . . . . 11.3.8 Tuning partitioned server memory usage . . . . . . . . . . . . . . . . . . . 11.4 Domino server clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.4.1 Differences between Domino clustering and Parallel Sysplex . . . 11.4.2 How many servers a cluster should contain . . . . . . . . . . . . . . . . . 11.4.3 Cluster replication vs. scheduled replication . . . . . . . . . . . . . . . . 11.4.4 Domino R5 clustering enhancements . . . . . . . . . . . . . . . . . . . . . . 11.4.5 Use of private LAN for cluster communication . . . . . . . . . . . . . . . 11.4.6 Configuration of a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.4.7 NOTES.INI file settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.4.8 Mail delivery failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 187 188 189 189 190 190 194 195 198 200 200 200 202 202 203 205 205 208 215 216

vi

Lotus Domino for S/390 R5 Installation, Customization and Administration

11.4.9 Calendaring and scheduling support . 11.4.10 The Internet Cluster Manager (ICM) 11.4.11 Monitoring cluster processes . . . . . . 11.4.12 Managing databases in a cluster . . . 11.5 Domino Server billing . . . . . . . . . . . . . . . . 11.5.1 Billing classes . . . . . . . . . . . . . . . . . . 11.5.2 Enabling the billing process. . . . . . . . 11.5.3 Optimizing billing performance . . . . . 11.5.4 Sample billing records . . . . . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

.217 .218 .222 .223 .225 .225 .226 .227 .227

Chapter 12. Upgrading the Domino Server . . . . . . . . . . . . . . . . . . . . . . . .231 12.1 Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231 12.1.1 Planning the order of your upgrade . . . . . . . . . . . . . . . . . . . . . . . .231 12.1.2 Testing your upgrade procedures . . . . . . . . . . . . . . . . . . . . . . . . .233 12.1.3 Pre-installation upgrade requirements . . . . . . . . . . . . . . . . . . . . . .234 12.1.4 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 12.1.5 Task checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 12.1.6 Stop the Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 12.2 Upgrade operating system software . . . . . . . . . . . . . . . . . . . . . . . . . . .242 12.2.1 Back Up the current server's files . . . . . . . . . . . . . . . . . . . . . . . . .243 12.2.2 Remove the symbolic link to existing server code . . . . . . . . . . . . .243 12.2.3 Remove the Notes binary directory . . . . . . . . . . . . . . . . . . . . . . . .244 12.2.4 Check HFS space requirements . . . . . . . . . . . . . . . . . . . . . . . . . .244 12.2.5 Install a new release of server code . . . . . . . . . . . . . . . . . . . . . . .247 12.2.6 Migrating directory/database links to Domino R5 . . . . . . . . . . . . . .248 12.2.7 Upgrade MAIL.BOX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248 12.2.8 Domino directory compaction and indexing . . . . . . . . . . . . . . . . . .249 12.2.9 Start the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250 12.2.10 Upgrade searching and indexing . . . . . . . . . . . . . . . . . . . . . . . . .250 12.2.11 Modifying Mail.box properties . . . . . . . . . . . . . . . . . . . . . . . . . . .250 12.2.12 Server task and API program testing . . . . . . . . . . . . . . . . . . . . . .251 12.3 Additional system database upgrades . . . . . . . . . . . . . . . . . . . . . . . . . .252 12.3.1 Administration Requests database . . . . . . . . . . . . . . . . . . . . . . . .252 12.3.2 Directory Assistance database . . . . . . . . . . . . . . . . . . . . . . . . . . .253 12.3.3 Statistics and Events database . . . . . . . . . . . . . . . . . . . . . . . . . . .253 12.4 Upgrading Domino mail topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . .256 12.4.1 Router transfer and delivery options . . . . . . . . . . . . . . . . . . . . . . .256 12.4.2 SMTP/MIME considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259 12.4.3 Considerations in a mixed-release cluster . . . . . . . . . . . . . . . . . . .260 12.4.4 Upgrading an SMTP MTA server . . . . . . . . . . . . . . . . . . . . . . . . . .260 12.5 Recovering from a failed upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267 Chapter 13. HFS data set management . . . . . . . . . . . . . . . . . . 13.1 Creating and mounting HFS data sets . . . . . . . . . . . . . . . . . 13.1.1 Creating a new HFS data sSet . . . . . . . . . . . . . . . . . . 13.1.2 Creating a mount point . . . . . . . . . . . . . . . . . . . . . . . . 13.1.3 Mounting the HFS data sets . . . . . . . . . . . . . . . . . . . . 13.1.4 Displaying mounted HFS data sets and mount points . 13.1.5 Unmounting and deleting HFS data sets . . . . . . . . . . . 13.2 Space management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2.1 Domino database size . . . . . . . . . . . . . . . . . . . . . . . . . 13.2.2 HFS data set full condition . . . . . . . . . . . . . . . . . . . . . 13.2.3 Monitoring HFS data set utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . .269 .269 .269 .269 .270 .272 .272 .272 .272 .273 .273

vii

13.2.4 Monitoring DASD volume . . . . . . . . 13.2.5 Recovering from space problems . . 13.3 DFSMS 1.5 . . . . . . . . . . . . . . . . . . . . . . 13.3.1 Allocating a multivolume HFS . . . . 13.3.2 Using the utility confighfs . . . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

.. .. .. .. ..

. . . . .

. . . . .

. . . . .

.. .. .. .. ..

. . . . .

. . . . .

. . . . .

. . . . .

.. .. .. .. ..

. . . . .

. . . . .

. . . . .

. . . . .

.. .. .. .. ..

275 276 277 278 280

Chapter 14. Data backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 14.1 Understanding your backup and recovery needs . . . . . . . . . . . . . . . . . 283 14.2 Backup using Notes replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 14.3 Backup using UNIX commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 14.4 Backup using Tivoli ADSM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 14.4.1 Activate the ADSM (TSM) OS/390 UNIX client . . . . . . . . . . . . . . . 286 14.4.2 Get the TSM server administrator to register your client. . . . . . . . 288 14.4.3 Back up files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 14.4.4 Restore files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 14.4.5 TSM disaster recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 14.4.6 TSM performance considerations. . . . . . . . . . . . . . . . . . . . . . . . . 294 14.4.7 TSM considerations when backing up Domino . . . . . . . . . . . . . . . 295 14.5 Backup using DFSMShsm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 14.6 Backup using DFSMSdss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 14.6.1 DFSMSdss Concurrent Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 14.6.2 Using DFSMSdss Concurrent Copy . . . . . . . . . . . . . . . . . . . . . . . 297 14.6.3 Back up an HFS data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 14.6.4 Restore an HFS data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 14.6.5 Increasing the size of an HFS data set. . . . . . . . . . . . . . . . . . . . . 300 14.7 RAMAC Virtual Array-based backup options . . . . . . . . . . . . . . . . . . . . 301 14.7.1 SnapShot function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 14.7.2 RVA considerations for storage of HFS/Domino data . . . . . . . . . . 303 14.7.3 DFSMSdss SnapShot for Domino backups . . . . . . . . . . . . . . . . . 304 14.7.4 DFSMSdss Virtual Concurrent Copy . . . . . . . . . . . . . . . . . . . . . . 306 14.8 Tivoli Data Protection for Lotus Domino . . . . . . . . . . . . . . . . . . . . . . . . 306 14.8.1 . . . . . . . . . . . . . . . R5 transaction logging, backup, and recovery306 14.8.2 Description of Tivoli Data Protection . . . . . . . . . . . . . . . . . . . . . . 307 14.8.3 TDP backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 14.8.4 TDP restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 14.8.5 TDP performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 14.8.6 Using Tivoli Data Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 14.9 Backup recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Chapter 15. OS/390 parameter recommendations for Domino 15.1 How Domino uses OS/390 facilities . . . . . . . . . . . . . . . . . . . 15.1.1 Domino Server tasks . . . . . . . . . . . . . . . . . . . . . . . . . . 15.1.2 OS/390 UNIX processes . . . . . . . . . . . . . . . . . . . . . . . 15.1.3 The Domino processing model. . . . . . . . . . . . . . . . . . . 15.1.4 OS/390 UNIX threads . . . . . . . . . . . . . . . . . . . . . . . . . 15.1.5 OS/390 address spaces . . . . . . . . . . . . . . . . . . . . . . . . 15.1.6 Effect of Domino on OS/390 parameters . . . . . . . . . . . 15.2 Overall system parameters in SYS1.PARMLIB(IEASYSxx) . 15.3 OS/390 UNIX parameters in SYS1.PARMLIB(BPXPRMxx) . 15.4 CSM parameters in SYS1.PARMLIB(IVTPRMxx) . . . . . . . . . 15.5 Notes_SHARED_DPOOLSIZE parameter . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. 311 312 312 312 313 314 314 316 316 317 321 321

viii

Lotus Domino for S/390 R5 Installation, Customization and Administration

Part 4. Notes administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323 Chapter 16. Simple administration tasks. . . . . . . . . . . . . . . 16.1 Installing the Lotus Domino Administrator client . . . . . . . 16.1.1 System requirements . . . . . . . . . . . . . . . . . . . . . . . 16.1.2 Pre-installation steps . . . . . . . . . . . . . . . . . . . . . . . . 16.1.3 Client software installation. . . . . . . . . . . . . . . . . . . . 16.1.4 Customizable installation options . . . . . . . . . . . . . . 16.1.5 Client configuration . . . . . . . . . . . . . . . . . . . . . . . . . 16.1.6 Configuration of a new client . . . . . . . . . . . . . . . . . . 16.1.7 Configuration of an upgraded client . . . . . . . . . . . . . 16.2 Using the Domino Administrator . . . . . . . . . . . . . . . . . . . 16.2.1 Selecting a server . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2.2 Refresh server list . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2.3 Registering a user . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2.4 Registering a Domino Server. . . . . . . . . . . . . . . . . . 16.3 Access the Domino Server with DOMCON . . . . . . . . . . . 16.4 The Domino Character Console . . . . . . . . . . . . . . . . . . . 16.4.1 Starting the Domino Character Console . . . . . . . . . 16.4.2 Character Console Commands . . . . . . . . . . . . . . . . 16.5 Domino R5 Web Administrator . . . . . . . . . . . . . . . . . . . . 16.5.1 Managing a database ACL with Web Administrator . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325 .325 .325 .325 .326 .328 .331 .331 .335 .341 .341 .341 .341 .348 .351 .351 .351 .352 .352 .353

Chapter 17. Connecting Domino servers. . . . . . . . . . . . . . . . . . . . . . . . . .355 17.1 Choosing a topology for mail routing and replication . . . . . . . . . . . . . . .355 17.2 Mail routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356 17.2.1 Introduction to mail routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356 17.2.2 Setting up mail routing Connection documents . . . . . . . . . . . . . . .356 17.2.3 Cross-certification and authentication . . . . . . . . . . . . . . . . . . . . . .359 17.3 Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364 17.3.1 Introduction to replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364 17.3.2 Creating the Connection document for replication . . . . . . . . . . . . .364 17.3.3 Required authorizations in Server document . . . . . . . . . . . . . . . . .366 17.3.4 Creating the replica on the Spoke server. . . . . . . . . . . . . . . . . . . .367 17.3.5 Database Replica IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368 17.3.6 Access Control Lists (ACLs) and replication . . . . . . . . . . . . . . . . .368 Chapter 18. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371 18.1 Domino Server protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371 18.1.1 Access during Domino Server setup . . . . . . . . . . . . . . . . . . . . . . .371 18.1.2 Domino Server access and network connectivity . . . . . . . . . . . . . .371 18.1.3 Database access controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375 18.1.4 Session-based Web client authentication . . . . . . . . . . . . . . . . . . .376 18.1.5 Access via the Internet Cluster Manager . . . . . . . . . . . . . . . . . . . .377 18.2 Secure Sockets Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377 18.2.1 SSL and the Internet Cluster Manager . . . . . . . . . . . . . . . . . . . . .378 18.3 Restricting SMTP server access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378 18.3.1 Mail relaying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378 18.3.2 Mail spamming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .379 18.4 Domino Server Character Console . . . . . . . . . . . . . . . . . . . . . . . . . . . .381

ix

Part 5. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Appendix A. Troubleshooting and hints and tips. . . . . . . . . . . . . . . . . . . . . 385 A.1 JCL Files Not Uploaded Properly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 A.2 Errors in running ALOCPROD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 A.3 Error when starting the server - 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 A.4 Error when starting the server - 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 A.5 Error when stopping the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387 A.6 Running the server without notes.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 A.7 mail.box missing on the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 A.8 The remote server is not a known TCP/IP host . . . . . . . . . . . . . . . . . . . . . . . 388 A.9 Error message server: FSUM7351 Not Found. . . . . . . . . . . . . . . . . . . . . . . . 388 A.10 Mount error return code 0000009C, reason code 0507014D . . . . . . . . . . . 389 A.11 Gaining access to the USER.ID file after configuration . . . . . . . . . . . . . . . . 389 A.12 MAXQUEUEDSIGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 A.13 Not enough disk space for installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 A.14 Could not backup notes.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390 A.15 Server panic errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390 A.16 IOSTREAM not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391 A.17 Java Virtual Machine not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391 A.18 Installation failed for local host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 A.19 Other recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 A.20 Hints and tips for Lotus Domino and Lotus Notes . . . . . . . . . . . . . . . . . . . . 393 A.20.1 Who can I call to find my local reseller and licensing information? . . . 393 A.20.2 Can you keep multiple versions of Lotus Notes on the same system? 393 A.20.3 How do I get rid of the encap2.ond attachment on outgoing mail? . . . 393 A.20.4 Can you run Notes 4.6 and 5.x clients simultaneously? . . . . . . . . . . . 394 A.20.5 How do you bypass Enforce ACL DB security? . . . . . . . . . . . . . . . . . . 394 A.20.6 When Are Database Subscriptions Checked? . . . . . . . . . . . . . . . . . . .394 A.20.7 How do you install the Notes client without user intervention? . . . . . . 394 A.20.8 Can fields be added to the N&A Book? . . . . . . . . . . . . . . . . . . . . . . . . 394 A.20.9 What would change the list of servers in the Database Open dialog?. 395 A.20.10 How do you make backup copies of created user IDs? . . . . . . . . . . . 395 A.20.11 Notes Full Text Search Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Appendix B. Our testing of the Domino Server on S/390 . . . . . . . . . . . . . . 397 B.1 Our Test Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 B.2 What We Tested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 B.3 Differences We Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Appendix C. Useful commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 C.1 MVS commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 C.1.1 D OMVS,F . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 C.1.2 D OMVS,A=ALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 C.1.3 D OMVS,A=asid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 C.1.4 D OMVS,PID=processid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 C.1.5 SETOMVS MAXPROCSYS=n. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .401 C.2 Some commands for problem determination . . . . . . . . . . . . . . . . . . . . . . . . .401 C.2.1 D OMVS,U=xxxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 C.2.2 D OMVS, OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 C.2.3 icps -bom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 C.3 UNIX System Services commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 C.3.1 df command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Lotus Domino for S/390 R5 Installation, Customization and Administration

C.3.2 env command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C.3.3 iconv command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C.3.4 ls command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C.3.5 ps command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C.4 Domino Server Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C.5 Using the UNIX vi editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix D. Editing the notes.ini file . . . . . . . . . . . . . . . . . . . . . . . D.1 The notes.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.1.1 Changing settings in the notes.ini file . . . . . . . . . . . . . . . . . . . D.1.2 Edit from an OMVS session using oeditascii . . . . . . . . . . . . . D.1.3 Edit from rlogin or Telnet using viascii . . . . . . . . . . . . . . . . . . D.1.4 Transfer to a workstation and edit it there. . . . . . . . . . . . . . . . D.1.5 Edit remotely using NFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....... ....... ....... ....... ....... ....... .......

405 405 406 406 406 407 409 409 410 411 411 411 411

Appendix E. Automating the operation of Domino using NetView. . . . . . 413 E.1 Restarting a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 E.2 Highlight resource constraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Appendix F. The ps shell command for threads . . . . . . . . . . . . . . . . . . . . . F.1 The new ps command for OS/390 V2R7. . . . . . . . . . . . . . . . . . . . . . . . . . . . F.2 Sample shell script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F.3 Description of new fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F.3.1 Thread only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F.3.2 State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 415 416 416 416 417

Appendix G. Real-life BPX parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Appendix H. Special notices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Appendix I. Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I.1 IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I.2 Lotus publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I.2.1 Lotus documentation online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I.3 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I.4 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I.5 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 423 423 424 424 424 426

How to Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427 IBM Redbook Fax Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433 ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .461

xi

xii

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. Domino R5 protocols, languages, services, and platforms . . . . . . . . . . . . . . . . 6 New Lotus Notes R5 client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Network traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 New LNOTES segment in OS/390 Security Server (RACF) . . . . . . . . . . . . . . 29 HFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Example of a directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Recommended name for the notesdata directory . . . . . . . . . . . . . . . . . . . . . . 37 Recommended name for HFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 OfficeVision support for Lotus Notes Clients . . . . . . . . . . . . . . . . . . . . . . . . . . 45 HFS file permission bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Output of a RACF LISTUSER command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Adding OMVS parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Setting the UNIX UID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Setting the user's initial directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Setting the program path name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Displaying a RACF user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Commands to FTP the installation files to the OS/390 server . . . . . . . . . . . . . 76 ALOCPROD JCL supplied with Domino R5 (screen 1 of 4). . . . . . . . . . . . . . . 78 ALOCPROD JCL supplied with Domino R5 (screen 2 of 4). . . . . . . . . . . . . . . 79 MDFYBPXP JCL supplied with Domino R5 . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Copying the tar file into HFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Uploading the tar file into the HFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Untar the tar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Installation introduction screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Introduction to License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 First screen of License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Final screen of License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Select Yes to agree to the terms of the License Agreement . . . . . . . . . . . . . . 92 Choose which type of server you want to install . . . . . . . . . . . . . . . . . . . . . . . 93 Set the directory path for Domino Server code . . . . . . . . . . . . . . . . . . . . . . . . 93 Introduction screen to setting up Domino Data Directories . . . . . . . . . . . . . . . 94 Single or partitioned server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Specify the number of data directories you wish to create. . . . . . . . . . . . . . . . 95 Specify the pathname for the notes data directory. . . . . . . . . . . . . . . . . . . . . . 95 Enter a RACF userid to own the Domino data files . . . . . . . . . . . . . . . . . . . . . 96 Enter the RACF group that the userid is connected to. . . . . . . . . . . . . . . . . . . 96 Configuration of the Install program is now complete . . . . . . . . . . . . . . . . . . . 97 Review the settings you have made before continuing . . . . . . . . . . . . . . . . . . 97 Completion of the install program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Completed install program (script mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Sample .profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Output after the HTTP task has been started . . . . . . . . . . . . . . . . . . . . . . . . 107 Create a new Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Server Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Administration settings screen for first server . . . . . . . . . . . . . . . . . . . . . . . . 110 Administration settings screen for additional server. . . . . . . . . . . . . . . . . . . . 112 Network and communications settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 UNIX Shell session output at completion of configuration . . . . . . . . . . . . . . . 114 Final screen of httpsetup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Download files using FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Copyright IBM Corp. 1999

xiii

51. PUTINLPA job supplied with CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 52. Check the sticky bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 53. Output of the ls -l command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 54. MDFYPROG supplied with Domino R5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 55. Remove the libnotes module from Dynamic LPA . . . . . . . . . . . . . . . . . . . . . .124 56. Display user ID information in OS/390 USS . . . . . . . . . . . . . . . . . . . . . . . . . . 131 57. Checking whether HFS data sets are mounted . . . . . . . . . . . . . . . . . . . . . . . 131 58. Display mounted file systems from the OS/390 USS shell . . . . . . . . . . . . . . . 132 59. Job to mount HFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 60. Mounting a file system from the OS/390 UNIX shell . . . . . . . . . . . . . . . . . . . . 132 61. HFS handling from the ISHELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 62. Using the OMVS shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 63. Login using Telnet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 64. Commands to start the Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 65. Console display as R5 server starts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 66. Error when starting a server twice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 67. Domino standard input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 68. Creating the files for rc.notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 69. Server startup script rc.notes - part 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 70. Server startup script rc.notes - part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 71. Starting the server in the background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 72. Check the notes.log after starting the server . . . . . . . . . . . . . . . . . . . . . . . . . 140 73. Console display as the server stops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 74. The concom utility for server DOMINO1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 75. Using concom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 76. Using the character console utility cconsole . . . . . . . . . . . . . . . . . . . . . . . . . . 144 77. Selecting a server to administer in the Domino Administrator . . . . . . . . . . . . 145 78. Shutting down the server with the Domino Administrator . . . . . . . . . . . . . . . . 145 79. Loading the server console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 80. Server shutdown with the live console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 81. Domino Web Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 82. Stopping the server with the Domino Web Administrator . . . . . . . . . . . . . . . . 148 83. MVS console display of address spaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 84. MVS console display of address spaces - sample output. . . . . . . . . . . . . . . . 150 85. UNIX System Services display of processes . . . . . . . . . . . . . . . . . . . . . . . . . 151 86. Output of the onetstat command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 87. Output of onetstat -b directly after server startup . . . . . . . . . . . . . . . . . . . . . .152 88. Output of command onetstat -b after connection establishment. . . . . . . . . . . 153 89. Output from the show tasks command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 90. Output from the show users command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 91. List of available server consol commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 92. Terminating the server with nsd -kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 93. Options of the nsd utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159 94. List IPC resources with ipcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 95. Web server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 96. TCP/IP profile data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 97. HTTP server setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 98. Creating a virtual host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 99. Virtual server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 100.Virtual server mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 101.Virtual server security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 102.URL-to-URL mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 103.URL-to-directory mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

xiv

Lotus Domino for S/390 R5 Installation, Customization and Administration

104.Redirection URL-to-URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105.File protection - basic settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106.Access control for file permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.Access Control List for file protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108.Creating a realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109.Domino Web Engine - servlet support settings . . . . . . . . . . . . . . . . . . . . . . . 110.Server proxy settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.Adding an NNTP connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.NNTP server connection - Basic tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.NNTP server connection - NNTP tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.Create a newsgroup database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.Newsgroup database profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116.LDAP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117.Our test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118.Partitioned servers using unique IP addresses . . . . . . . . . . . . . . . . . . . . . . . 119.Partitioning servers using unique port numbers on one IP address . . . . . . . 120.IP Definitions on Notes client - multiple IP addresses . . . . . . . . . . . . . . . . . . 121.Port mapper server TCP/IP definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.Second partitioned server TCP/IP definitions . . . . . . . . . . . . . . . . . . . . . . . . 123.IP Definitions on client or Domino Administrator -- single IP address . . . . . . 124.Choosing to run multiple server partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.Setting the number of server partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126.Choosing to manually generate partitioned data directory names. . . . . . . . . 127.Changing the name of the partitioned data directory. . . . . . . . . . . . . . . . . . . 128.Reviewing Installation Settings for Partitioned Servers . . . . . . . . . . . . . . . . . 129.Enabling Bind to host name for HTTP task . . . . . . . . . . . . . . . . . . . . . . . . . . 130.Clustering in an OS/390 environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.Dual network cluster server connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.Setting up a new server port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.Server port configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.Creating a new network port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.Adding a cluster port entry on the server document . . . . . . . . . . . . . . . . . . . 136.Output of the show cluster command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137.Selecting servers to create a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138.Confirm creation of a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139.Choosing or adding a cluster name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140.Creating a new cluster name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.Create cluster immediately or via Administration Process. . . . . . . . . . . . . . . 142.Confirmation of Cluster Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.Confirm submission of Admin Request to create cluster . . . . . . . . . . . . . . . . 144.Cluster directory task startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145.A new cluster directory database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146.Removing a server from a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147.Confirm removal of server from cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148.Remove cluster immediately or via Administration Process . . . . . . . . . . . . . 149.Successful removal of server from cluster. . . . . . . . . . . . . . . . . . . . . . . . . . . 150.Confirm submission of Admin Request to remove server from cluster . . . . . 151.Enabling mail cluster failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.Running the ICM outside the cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.Running the ICM inside the cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.Configuring ICM in the server document . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.Selecting databases for cluster management . . . . . . . . . . . . . . . . . . . . . . . . 156.Choosing a cluster management action . . . . . . . . . . . . . . . . . . . . . . . . . . . .

170 171 171 172 172 173 176 178 178 179 180 181 183 188 190 191 192 193 194 194 195 196 196 197 197 199 201 205 206 207 207 208 208 210 210 210 211 211 211 211 212 213 214 214 215 215 215 217 219 219 220 224 224

xv

157.Sample session billing document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 158.Sample database billing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 159.Sample replication billing document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 160.Sample mail billing document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 161.Sample agent billing document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229 162.Sample HTTP request billing document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 163.Adding the pubnames.ntf icon to the desktop . . . . . . . . . . . . . . . . . . . . . . . . 236 164.Creating a new database replica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 165.Replacing the design of the Public NAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 166.Replace database design warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 167.Editing the Domino Directory profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240 168.Editing the notes.ini file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 169.Removing the Report task from the notes.ini file . . . . . . . . . . . . . . . . . . . . . .241 170.Remove the symbolic link to server code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 171.Changing the location of the Transaction Log Extent . . . . . . . . . . . . . . . . . . .246 172.Changing the program install directory during upgrade . . . . . . . . . . . . . . . . . 247 173.Changing the data install directory during upgrade . . . . . . . . . . . . . . . . . . . . 248 174.Renaming MAIL.BOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 175.Compacting the Domino directory (names.nsf) . . . . . . . . . . . . . . . . . . . . . . . 249 176.Updating names.nsf view indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 177.Setting properties for the R5 router mailbox database . . . . . . . . . . . . . . . . . . 251 178.Forcing adminp to process outstanding requests . . . . . . . . . . . . . . . . . . . . . . 252 179.Stopping the adminp task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 180.Error on event task startup after server upgrade . . . . . . . . . . . . . . . . . . . . . .253 181.Error on collect task startup after server upgrade . . . . . . . . . . . . . . . . . . . . .253 182.Specifying a server to collect statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 183.Specifying statistics collection Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 184.Increasing the number of router mailbox databases . . . . . . . . . . . . . . . . . . . 257 185.Increasing the maximum router transfer threads . . . . . . . . . . . . . . . . . . . . . .258 186.Increasing the maximum router delivery threads . . . . . . . . . . . . . . . . . . . . . .259 187.Disable MTA daily housekeeping task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 188.Stopping the mail router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 189.Stopping the SMTPMTA inbound message transport task. . . . . . . . . . . . . . . 263 190.Editing the notes.ini file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 191.Removing the SMTPMTA task from the notes.ini file . . . . . . . . . . . . . . . . . . .263 192.Adding or editing a server configuration document . . . . . . . . . . . . . . . . . . . . 264 193.Enabling the SMTP listener task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265 194.Setting a relay host and smart host for external SMTP traffic . . . . . . . . . . . . 266 195.Reverting databases back from R5 to R4 ODS . . . . . . . . . . . . . . . . . . . . . . . 267 196.Sample job to create an HFS data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 197.Sample job to create a mount point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 198.HFS mount commands in BPXPRMxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 199.Define Notes Server name in SYS1.PARMLIB(IEASYMxx) . . . . . . . . . . . . . . 271 200.Procedure to issue the mount commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 201.Job to unmount HFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 202.Disk full error message to Notes Workstation . . . . . . . . . . . . . . . . . . . . . . . . 273 203.Domino Server log when the mail file system is running out of space . . . . . .273 204.Disk full error message on Domino Server console . . . . . . . . . . . . . . . . . . . . 273 205.Monitoring data set utilization from ISMF - 1 . . . . . . . . . . . . . . . . . . . . . . . . . 274 206.Monitoring data set utilization from ISMF - 2 . . . . . . . . . . . . . . . . . . . . . . . . . 274 207.Monitoring data set utilization from ISPF 3.4 . . . . . . . . . . . . . . . . . . . . . . . . . 275 208.Monitoring data set utilization from OMVS . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 209.Monitoring DASD volume utilization from ISMF . . . . . . . . . . . . . . . . . . . . . . . 276

xvi

Lotus Domino for S/390 R5 Installation, Customization and Administration

210.Monitoring DASD volume status from ISMF . . . . . . . . . . . . . . . . . . . . . . . . . 211.Sample mount statement in BPXPRMxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.Sample JCL to allocate a multivolume HFS . . . . . . . . . . . . . . . . . . . . . . . . . 213.ISPF data set list for multivolume HFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.ISPF data set information for multivolume HFS. . . . . . . . . . . . . . . . . . . . . . . 215.Output of ISMF data set list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.Output of ISMF data set list after extension to next volume . . . . . . . . . . . . . 217.Using the utility confighfs - part 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218.Using the utility confighfs - part 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219.Example AF_INET definition in SYS1.PARMLIB(BPXPRMxx) . . . . . . . . . . . 220.Set UNIX file permission bits and symbolic links . . . . . . . . . . . . . . . . . . . . . . 221.Option file dsm.sys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.Start the TSM client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.incremental backup example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.query filespace example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225.query backup example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226.query filespace example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227.incremental backup example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228.selective backup example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229.selective backup example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230.restore example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.DFSMSdss DUMP using Concurrent Copy . . . . . . . . . . . . . . . . . . . . . . . . . . 232.Back up an HFS data set using DFSMSdss . . . . . . . . . . . . . . . . . . . . . . . . . 233.Restore an HFS data set using DFSMSdss . . . . . . . . . . . . . . . . . . . . . . . . . 234.Delete and Reallocate HFS Data Sets Bigger . . . . . . . . . . . . . . . . . . . . . . . . 235.Domino Tasks in OS/390 address spaces. . . . . . . . . . . . . . . . . . . . . . . . . . . 236.Server tasks in notes.ini. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237.Domino tasks and UNIX processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238.Address spaces for the Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239.Address space IDs for the Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . 240.Error message on Notes client for hang of Domino Server . . . . . . . . . . . . . . 241.D OMVS,A=asid to find the address space ID. . . . . . . . . . . . . . . . . . . . . . . . 242.D OMVS,PID=process_id to display number of threads . . . . . . . . . . . . . . . . 243.Server fails to start - Iisufficient IPCSHMMPAGES value . . . . . . . . . . . . . . . 244.Set or edit User Name and Company details . . . . . . . . . . . . . . . . . . . . . . . . 245.Choosing client program and data directories . . . . . . . . . . . . . . . . . . . . . . . . 246.Choosing the client installation type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247.Choosing a folder for the client program icons . . . . . . . . . . . . . . . . . . . . . . . 248.Customizing client installation options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249.Changing sub-components of an install option . . . . . . . . . . . . . . . . . . . . . . . 250.The Client Configuration wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251.Choosing to connect to a Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.Choosing to connect via a LAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.Enter the server name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.Specifying the User ID file during client setup . . . . . . . . . . . . . . . . . . . . . . . . 255.Completed client connection definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.Choosing not to create an Internet mail account . . . . . . . . . . . . . . . . . . . . . . 257.Completing the Client Configuration Wizard . . . . . . . . . . . . . . . . . . . . . . . . . 258.Client setup progress indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259.Creating the bookmark database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260.The Administration Client welcome screen . . . . . . . . . . . . . . . . . . . . . . . . . . 261.Closing the Administration Client welcome screen . . . . . . . . . . . . . . . . . . . . 262.Administration Client servers bookmark icon. . . . . . . . . . . . . . . . . . . . . . . . .

276 278 279 279 279 279 280 281 281 287 287 287 288 289 289 290 290 291 292 293 294 298 299 300 301 312 312 313 315 316 318 319 319 322 326 327 327 328 329 329 331 332 332 333 333 334 334 335 335 336 336 337 337

xvii

263.The Administration Client server bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . 337 264.Adding a server to bookmark favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 265.Setting Administration Client preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 266.Administration Preferences - Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339 267.Administration Preferences - Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 268.Administration Preferences - Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . .340 269.Administration Preferences - Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 270.Server icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341 271.Listing of all servers in the domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 272.User Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 273.User Registration - Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 274.Set Internet Address Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 275.User Registration - Mail Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 276.User Registration - ID Info section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 277.User Registration - Other section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 278.Advanced Person Registration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 279.Person Registered Successfully dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . 348 280.Prepare for Domino Server registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 281.Register a Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 282.Register a Domino Server - Basics section . . . . . . . . . . . . . . . . . . . . . . . . . . 350 283.Register a Domino Server - Other section . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 284.End of registration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 285.Web Administration example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 286.Our test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 287.New server connection for mail routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 288.Replication/routing tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 289.Lotus Notes - Connection document in the Domino Directory . . . . . . . . . . . . 358 290.Mail routing Connection document for second server . . . . . . . . . . . . . . . . . . 359 291.Choose ID file to examine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 292.User ID management screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 293.Name of the Safe Copy ID file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 294.Choose Certifier ID screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 295.Choose ID to Cross-Certify screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 296.Cross Certify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 297.Lotus Domino - new LAN connection (for replication) . . . . . . . . . . . . . . . . . . 365 298.Lotus Domino - new Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 299.Creating a new replica of a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 300.Replica ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 301.Restricting server access and execution of Java/Javascript applets . . . . . . . 373 302.Setting available SSL cipher types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 303.Setting TCP/IP port information for IIOP communication . . . . . . . . . . . . . . . . 375 304.Enabling Web client session-based authentication . . . . . . . . . . . . . . . . . . . . 377 305.Mail relaying - outbound control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 306.SMTP inbound control - deny SMTP domain . . . . . . . . . . . . . . . . . . . . . . . . .380 307.Invalid JCL file format after FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 308.MVS command D OMVS,F sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 309.D OMVS,A=ALL sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400 310.MVS command D OMVS,AID=asid sample output. . . . . . . . . . . . . . . . . . . . . 401 311.MVS command D OMVS,PID=processid sample output . . . . . . . . . . . . . . . . 401 312.MVS command SETOMVS MAXPROCSYS=n sample output . . . . . . . . . . . 401 313.D OMVS,U=EBBERS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 314.ps -ef command output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 315.Display active OMVS options BPXPARMS . . . . . . . . . . . . . . . . . . . . . . . . . . 403

xviii

Lotus Domino for S/390 R5 Installation, Customization and Administration

316.ipcs -bom command showing shared memory segments . . . . . . . . . . . . . . . 317.UNIX System Services df command sample output . . . . . . . . . . . . . . . . . . . 318.UNIX System Services env command sample output . . . . . . . . . . . . . . . . . . 319.UNIX System Services iconv command sample output. . . . . . . . . . . . . . . . . 320.UNIX System Services ls command sample output . . . . . . . . . . . . . . . . . . . 321.UNIX System Services ps command sample output . . . . . . . . . . . . . . . . . . . 322.Sample notes.ini file - part 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.Sample notes.ini file - part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324.Console message when task ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.NetView procedure DOMPROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326.NetView IF-THEN statement to run DOMPROC . . . . . . . . . . . . . . . . . . . . . . 327.Console message when not enough resources. . . . . . . . . . . . . . . . . . . . . . . 328.NetView procedure to issue WTO macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 329.New ps Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330.Sample Shell Script for OS390 2.7 (also Newer and Older Releases) . . . . . 331.Sample BPXPRMH0 member for mounting file systems. . . . . . . . . . . . . . . .

404 405 405 405 406 406 409 410 413 413 413 414 414 416 416 420

xix

xx

Lotus Domino for S/390 R5 Installation, Customization and Administration

Tables
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. User interface features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Available platforms for Release 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Host office migration tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Minimum disk space requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 OS/390 and UNIX System Services installation tasks . . . . . . . . . . . . . . . . . . . 58 TCP/IP for MVS setup tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Domino Server installation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 OS/390 System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Data sets created by ALOCPROD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Domino Server installation and configuration tasks . . . . . . . . . . . . . . . . . . . . . 86 Information required to run the install program . . . . . . . . . . . . . . . . . . . . . . . . 89 Information for the first server in a new domain . . . . . . . . . . . . . . . . . . . . . . . 101 Information for an additional server in an existing domain . . . . . . . . . . . . . . 104 Partitioned server lab parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Partitioned servers with unique IP addresses . . . . . . . . . . . . . . . . . . . . . . . . 191 Domino partitioned server definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Clustering specific notes.ini variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Intra-cluster traffic statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Workload balancing statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 General ICM statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Billing classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Locations for billing records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Fields used in the Domino Directory profile . . . . . . . . . . . . . . . . . . . . . . . . . . 240 The tasks required to upgrade the Domino Server code . . . . . . . . . . . . . . . . 242 DASD terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Options of confighfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 IEASYSxx Parameter for Domino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 OS/390 UNIX parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Domino Server UNIX parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Backing up important client files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Client installation components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Domino Character Console command line switches . . . . . . . . . . . . . . . . . . . 351 Domino Character Console commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Changes that will replicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Web server authentication definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Useful USS-related MVS console commands . . . . . . . . . . . . . . . . . . . . . . . . 399 Useful UNIX System Services commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Useful Domino Server commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Useful vi commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Examples of BPX parameters in production environments . . . . . . . . . . . . . . 419

Copyright IBM Corp. 1999

xxi

xxii

Lotus Domino for S/390 R5 Installation, Customization and Administration

Preface
This redbook will help you install, customize and manage the Lotus Domino Server Release 5 for S/390. It discusses in detail: Planning for Notes on the S/390 platform Installing the Domino Server Advanced installation topics Administering Notes on the S/390 platform This redbook is written for OS/390 system programmers and Notes administrators who will implement a Domino Server on a S/390. Examples are included, and we have also documented functions, commands and scripts, which can greatly help the administrator who is new to the OS/390 or UNIX environment. The first two chapters discuss the value of S/390 as a Domino Server, and planning considerations. These will be especially useful to managers and planners.

The team that wrote this redbook


Mike Ebbers is a Senior I/T Specialist at the International Technical Support Organization (ITSO), Poughkeepsie Center. He produces redbooks and workshops on Domino for S/390. He has worked for IBM for 25 years, including 10 years in the field with large systems customers and 11 years in education as an instructor/developer. Marco Foellmer is a Lotus Domino Engineer for EBF, an IBM/Lotus Business Partner in Cologne, Germany. He has worked with Lotus Notes since the days of 3.x and now develops Lotus Domino Intranet/Internet solutions. His areas of expertise include architecture, documentation, performance tuning, upgrading, messaging-migration and coexistence architecture. Email: mf@ebf.de Joachim Heinrich is a Senior Consultant in Betriebswirtschaftliche und -Technische Beratungsgesellschaft (BTB) GmbH in Leinfelden, Germany (http://www.btbnet.de). The BTB is a S/390 e-business Solution Competence Center. Joachim has 13 years of experience in host programming. He works as a system programmer on the OS/390 platform. Email:heinrich@btbnet.de Andre Mueller is an e-business/390 Specialist with IBM Global Services in Germany. He has five years experience in OS/390 and specializes in e-business server platforms and OS/390 USS. Andre holds a degree in computer science. Simon Williams is a Senior I/T Specialist with IBM in Sydney, Australia. Simon has 11 years experience in the Information Technology industry, working primarily with large systems. He currently specializes in OS/390 Unix System Services and many of the technologies and applications it supports. Before joining IBM, Simon was an MVS Systems Programmer. The original redbook was produced by a team of specialists from around the world working at the International Technical Support Organization Poughkeepsie Center: xxiii

Copyright IBM Corp. 1999

Brian Macfaden Steven Cooper Gordon Culpan Alexander Fernandez Paos Michael Finkenbrink Ger Goedvolk Ingo Karge May Lee-Wong Julian Lin Sonomi Ohkubo Osamu Shimomura

IBM U.K. IBM Australia Lotus Canada IBM Spain Lotus Germany Lotus Netherlands Lotus Germany IBM USA IBM Taiwan IBM Japan IBM Japan

Thanks to the following people for their invaluable contributions to this project: Tom Byrnes Jim Caffrey Rich Conway Jim Dewan Cathy Eilert Mike Essenmacher Barbara Filippi Clark Goodrich Bob Haimowitz Tony Llopis Brian Macfaden Jim Ray Joe Sweeney John Woods IBM S/390 Division IBM S/390 Division ITSO, Poughkeepsie Center IBM S/390 Division IBM S/390 Division IBM S/390 Division IBM Lotus Integration Center, Dallas IBM S/390 Division ITSO, Poughkeepsie Center IBM Lotus Integration Center, Dallas IBM Lotus Integration Center, Boeblingen IBM S/390 Division IBM S/390 Division IBM S/390 Division

Comments Welcome
Your comments are important to us! We want our redbooks to be as helpful as possible. Please send us your comments about this or other redbooks in one of the following ways: Fax the evaluation form found in , ITSO Redbook Evaluation on page 461 to the fax number shown on the form. Use the electronic evaluation form found on the Redbooks Web sites: For Internet users For IBM Intranet users
http://www.redbooks.ibm.com/ http://w3.itso.ibm.com/

Send us a note at the following address:


redbook@us.ibm.com

xxiv

Lotus Domino for S/390 R5 Installation, Customization and Administration

Part 1. Planning for Notes on the S/390 platform

Copyright IBM Corp. 1999

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 1. The value of Lotus Domino on S/390


Users of both Lotus Notes and IBM S/390 are excited about Lotus Domino on S/390. It combines the power of Lotus Domino as an application platform with the strengths of S/390 as a server. This redbook hels you to plan, install and run Domino servers on S/390. In this chapter we describe the value of S/390 as a Domino server platform: We introduce the functions of the Lotus Domino server and Notes Workstation. We show how S/390, in many ways, is just another Domino server platform. We describe the unique benefits of S/390 as a Domino platform. Lotus Domino R5 brings messaging, Internet integration, and scalability to a whole new level. The new Domino server includes the latest innovations in Internet messaging, with native support for all the major Internet standards, such as industry-leading support for Web applications, including Common Object Request Broker Architecture (CORBA) support. The Domino Server has increased reliability and scalability, including improvements in performance, capacity, availability, and maximum database size. In addition, the server has a new administration interface, with a task-oriented approach that makes Domino easier to deploy, use, and manage. Lotus Domino R5 continues to support a wide variety of clients, in addition to the traditional Notes client. Messaging features are available to Web browsers and Internet mail clients such as Post Office Protocol Version 3 (POP3) and Internet Message Access Protocol Version 4 (IMAP4) clients. Directory features are available to browsers and Lightweight Directory Access Protocol (LDAP) clients. Discussion features are available to browsers and Network News Transfer Protocol (NNTP) newsreader clients, and administration features are available to browsers as well as the Notes client. Domino continues to be the best platform for designing dynamic Web applications. With the new Domino R5 you can easily build a single application that looks and runs the same for both the Web and Notes clients. The Lotus Notes R5 client gives you easy access to all the information that is important to you -- whether that information is personal (like your e-mail and calendar) or public (like your favorite Web sites and Internet newsgroups). The client includes a new browser-like user interface with a customizable welcome page for tracking your important daily information. It also includes improvements to the applications you use in your daily work, such as mail, calendar and scheduling, Web browsing and discussions. The Notes R5 client is server independent -- that is, you can use it with Domino R5 as well as other Internet-standard servers, such as the ones your Internet Service Provider (ISP) may use. For example, you can read and send messages to any Internet mail server, read and post topics to any Internet newsgroup, search any Internet directory, view HTML from any Web server, and use X.509 certificates for security. The best part is that you can do all these things from within one, consistent interface, without needing to know about the Internet standards involved. You simply do your work within the Notes interface, and Notes handles the rest for you.

Copyright IBM Corp. 1999

The rest of this chapter briefly outlines the new features and enhanced functionality of the Lotus Domino R5 server and the various clients. It describes the new concepts in R5 and the available platforms. The hardware and software we used to develop the material for this book is also described.

1.1 What Lotus Domino R5 is


Lotus Domino R5 is Lotus next generation of Internet products, which include Notes Integrated Internet client and Domino server platform for messaging, collaboration, and Internet and intranet applications. The Domino Designer is a Web and intranet application development tool. Dominos integrated platform delivers messaging and collaborative solutions for the Internet. Several key services enable IT professionals to manage and run their messaging and Web application infrastructures easily and efficiently. The new R5 Domino Administrator makes it faster and easier for administrators to manage users, configure systems, and optimize performance, all from an intuitive user interface. The Lotus Domino R5 server builds on its already strong foundation for messaging and Web applications. The R5 enhancements are the next step in making Domino even more easy to use, and a better fit for any size organization. Specific Lotus Domino R5 features include:

Internet messaging and directories Provide full-fidelity messaging for your users, with native MIME and SMTP support.
Use the new Directory Catalog to save space and provide quick name lookups. Use new LDAP features to authenticate users in external directories, customize the directory, and more.

Expanded Web application services Design applications with CORBA-standard distributed objects, Java, or JavaScript.
Use Web clusters for high availability of Web services, expanded security options, and more.

Database improvements Use transactional logging for faster restarts and data recovery.
Convert to the new on-disk structure (ODS) for better performance, data integrity, and more.

Easier administration Manage users, databases, and servers with the new Domino Administrator. It includes the Administration Process, a tool for analyzing what you need to do to decommission a server, topology maps and integration hooks for third-party tools to appear on the registration interface.
Migrate users from cc:Mail, Microsoft (MS) Mail, Exchange or Windows NT with the redesigned user registration. New tools for server monitoring and message management.

Lotus Domino for S/390 R5 Installation, Customization and Administration

1.1.1 Domino R5 and the competition


Domino R5 provides the most advanced messaging infrastructure and tightly integrates with Microsoft technologies like Windows NT, Office 95, Office 97, Microsoft FrontPage, and more, without being dependent upon a single vendor, enabling you to get the most advanced, best-of-breed functionality. Based on a single messaging and application architecture, Domino R5 deploys and manages an enterprise's messaging and application environment. Domino servers integrate with and leverage other supported infrastructure investments, such as operating systems, other e-mail products, and even enterprise systems. Microsoft Exchange currently only allows integration with other Microsoft solutions, and upgrades must be made in step with other Microsoft products. For example, Outlook 97 requires the user to upgrade to Office 97 with no backward support for Office 95. The same is true for Outlook 2000 and Office 2000. Microsoft has announced that it has no current plans for backward support for Office 97. Many of the advanced features of Domino R5 will not be available from Microsoft until Exchange "Platinum" ships later next year. But Exchange "Platinum" will require an upgrade to NT 5.0, for which many analysts recommend delaying deployment until 2001 or beyond. To help your customers get the most powerful and robust infrastructure without a massive operating system upgrade, Domino R5's stability, with its huge install base and product maturity, makes it a smart investment for future upgrades, services and usability.

The value of Lotus Domino on S/390

Figure 1. Domino R5 protocols, languages, services, and platforms

1.2 What Lotus Notes R5 is


The new Lotus Notes R5 interface is more intuitive and easier to use than ever. It provides a single integrated environment to manage e-mail, appointments, tasks, key contacts, and Web information. It gives you a headlines page that helps you stay on top of your most important priorities throughout the day. Lotus Notes R5 offers powerful, new knowledge management tools. Its bookmarks help get back to information quickly. It is state-of-the-art e-mail, calendaring, group scheduling, Web access, and information management -- all integrated in an easy-to-use and customizable environment. Lotus Notes R5 extends the lead in integrated collaboration clients with even more Internet support and a Web-style interface that adapts to your work style, plus scores of other improvements to help work smarter and be more productive. The new look-and-feel of Lotus Notes R5 focuses on creating an environment that makes it easy for both new and existing users to access all of their information. This is accomplished by new features that help new users, such as cc:Mail and Internet mail users, feel comfortable with the Notes mail interface, as well as by making existing features, such as calendar and scheduling, easier to use. Underlying both of these areas is the clients total embrace of Internet standards, so you can work with the information that matters to you, regardless of where that data is stored or what protocol is used to deliver it.

Lotus Domino for S/390 R5 Installation, Customization and Administration

Specific Lotus Notes R5 features include:

The new user interface Use the new Welcome page for instant access to your mail, calendar, and more; and customize it to track your important information.
Create bookmarks for anything that you want to return to later, whether it is from Notes or the Internet. Navigate through open pages of information with tabs and Web-like universal navigation buttons.

Improved applications Use new mail features, such as cc:Mail-like address headers, mail rules, easier mail archiving, and others.
Get organized with enhanced Calendar and Scheduling features, such as tasks that follow you, improved calendar management, a Group calendar, and more.

Native support of Internet standards View Internet mail messages, Web pages, and newsgroups with full fidelity (because of MIME and HTML support) and security (using SSL, S/MIME, and X.509 certificates).
Read and send messages from Internet mail servers (using POP3 or IMAP). Search any Internet directory (using LDAP). Read and post articles to any Internet newsgroup discussion (using NNTP).

1.2.1 Benefits of R5
Some of the benefits of R5 are given below: Ease of use Notes makes it easy to find, sort, and manage all your work in a way that makes sense to you. Notes works your way. You can personalize the new Headlines page or customize your Bookmarks so that the information you need is the information you see. Universal Inbox Notes support for Internet protocols lets you manage all your e-mail from one place, whether its from your network, or from an Internet account. One place for all information Notes is a truly integrated Internet client, providing access to a world of information and helping you manage it with ease. Mobile support Whether you are in the office or on the road, you can stay connected. Notes synchronizes data with PCs, pagers, faxes and popular hand-held devices. Easy to install and set up Simple install of software will get you right to work. A powerful tool for any infrastructure

The value of Lotus Domino on S/390

Current Notes users can upgrade quickly and easily to take advantage of all the tremendous enhancements in Notes and Domino R5. Scalability and performance On the S/390 platform, Domino R5 can scale up to thousands of users per server. A certified Notesbench run validated 32,000 mail users on a single machine, with a response time of under 1 second per transaction.

1.2.2 New Lotus Notes R5 client interface


Notes unveils a dramatically new user interface designed to let you take advantage of the new power of Notes, whether you are viewing Notes databases, contributing to a discussion group, reading mail from your ISP, or just surfing the Web. While the interface has changed, you can still use the legacy Notes Workspace from previous releases of Notes.
Table 1. User interface features

UI Features Welcomepage

Description Start on the Welcome page for all your important information. The Welcome page contains some basic tasks, and you can customize it: Instant access to mail, calendar, and to do lists. Customize the page to see your latest mail messages and appointments at a glance. Add your favorite Web sites or newsgroups. Instant search of Web sites, local documents, databases, or anything. Notes Tour. See Whats New.

Bookmarks Navigation

Create bookmarks for anything you want to return to later, whether it is from Notes or the Internet. Navigate through open pages of information with tabs and Web-like universal navigation buttons.

The Welcome page looks like the example shown in Figure 2 on page 9.

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 2. New Lotus Notes R5 client interface

1.3 Domino Application Studio


The Domino Application Studio provides seven of the industry's best Web development tools and two servers for rapidly creating and deploying highly creative, dynamic, collaborative Web applications. Each tool and server supports open standards, including Java, and all integrate with the Lotus Domino Application Server R5. You get these tools: Domino Designer R5 - Visual IDE for corporate developers. Use with all of the other tools in the Studio to assemble collaborative, dynamic Web applications for Lotus Domino. NetObjects Fusion - The graphic designers' tool for building cool-looking Web sites quickly and easily. Integrates with Domino through the free, downloadable Domino Fusion Connector (DFC). VisualAge for Java, Professional Edition - For programmers, this full-blown Java IDE has all the tools you need for writing, debugging, and testing Java applets, servlets, and applications. It integrates with Domino through the free, downloadable Domino Toolkit for Java. eSuite DevPack - Provides a wealth of prebuilt business applets for programmers to use with Domino Designer to create powerful interactive Web applications. Speeds development with ready-to-go sheets, a rich text processor, a library of charts, data access applets, and more. NetObjects BeanBuilder - Use this visual tool to create and manage JavaBean-based applets and applications without writing a single line of code.

The value of Lotus Domino on S/390

NetObjects ScriptBuilder - Quickly create client-side and server-side scripts. Easily build scripts with JavaScript and debug and test them. Lotus FastSite 2.0 - Deliver data trapped in proprietary file formats! Use this tool to deliver existing spreadsheet, presentation, and rich text files over the Web. And you get these servers: Domino Application Server - This server and a single developer license give you the tools to build e-business applications that create sustainable competitive advantage by supporting relationships among people within and between organizations. With its ability to connect people-oriented business processes to existing enterprise data and knowledge, Domino Application Server R5 provides the industry's best platform for hosting collaborative business application solutions -- such as customer relationship management, interactive self-service, supply chain management and value-chain integration. WebSphere Server Standard Edition - This server and single developer license give you a market-leading, Java-based execution and management environment for server-side critical business logic.

1.4 Lotus Domino R5 family of servers and clients


The Domino server family is an integrated messaging and Web application software platform for growing companies that need to improve customer responsiveness and streamline business processes. The only solution built on an open unified architecture, Domino is trusted by the worlds leading companies to deliver secure communication, collaboration and business applications. Lotus Domino R5 servers set a new standard for rich Internet messaging, ease of administration, integration with backend systems and reliability. The Domino server family is comprised of three core servers. Each provides an additional set of functions on top of the previous server type: 1. Domino R5 Mail Server The Domino Mail Server combines full support for the latest Internet mail standards with Dominos industry-leading messaging capabilities -- all in one manageable and reliable infrastructure 2. Domino R5 Application Server The Domino Application Server (in addition to the Mail Server functions) is an open, secure platform optimized to deliver collaborative Web applications that integrate your enterprise systems with rapidly changing business processes. 3. Domino R5 Enterprise Server The Domino Enterprise Server includes services previously provided in the Advanced Server. It delivers all the functionality of the Domino Mail and Application Servers, reinforced with clustering for the high availability and reliability required by mission-critical applications. It also provides the capability of partitioning and billing.

10

Lotus Domino for S/390 R5 Installation, Customization and Administration

One of these server types is chosen during setup, and the customer must have purchased a license to match the server type being installed. The Domino client family is comprised of three core clients: 1. Domino Administrator Domino Administrator is the new administration client for Notes and Domino. It has a completely new interface with different navigation from the R4.x Administration panel. 2. Domino Designer Domino Designer R5 is an integrated development environment. It enables developers to rapidly build secure Web applications that incorporate enterprise data and streamline business processes. How does Domino Designer R5 compare? Domino Designer R5 is the premier development client for Domino servers. Here are some features that put Domino Designer R5 ahead of its competition. It supplies an intuitive, open application environment for developers. Domino Designer R5 developers can manage design for multiple applications through reusable templates; competitive applications are "one-off." While supporting the rich Domino application model, Domino Designer R5 is unique in that it also supports the tools and languages that developers use: Java, JavaScript, ActiveX, C++, HTML, FrontPage and NetObjects Fusion. It also provides a rich set of services such as Domino's access control and directory/authentication. It provides easy access to enterprise data and applications. With Domino Designer R5, developers can create applications that extend from back-end systems for multiple types of clients who need to find, manipulate, validate and use data. Domino Designer R5 connects users to relational databases, legacy applications, TP monitors and ERP applications via support for Lotus Domino Enterprise Connection Services (DECS). New tools, such as DECS, enhancements to LotusScript, and Java classes for programmatic access to enterprise sources, are making enterprise integration for Domino easier and more efficient. Lotus is also developing a number of Domino Connectors for access to such ERP systems as SAP, PeopleSoft, JD Edwards and Oracle. With Domino Designer R5 you can architect secure multitier Web applications end-to-end that streamline business processes, integrate with enterprise data and applications, and facilitate collaborative relationships. 3. Notes Client The Notes Client provides the interface that allows a Lotus Notes user to access shared databases to read and send mail. The client user interface is dramatically enhanced in R5.

How Notes R5 stacks up against the competition When compared to its major competitors, Notes R5 shows its competitive edge in several ways:
While competitors scatter protocol support among multiple products, Notes R5 delivers full native support for major Internet and industry standards.

The value of Lotus Domino on S/390

11

By managing multiple mail, collaboration and directory accounts from one place, Notes R5 eliminates the confusing modes and complex configuration settings of competitive products. The single interface that Notes R5 presents works for everything: e-mail, calendaring, news reading and Web browsing. This is an improvement over disparate navigation models. Notes R5 integrates with all the applications already in place on the desktop, including Lotus SmartSuite and Microsoft Office 95 and 97. Outlook 98 currently supports only Office 97. Only Notes R5 has built-in application capabilities with built-in routing and workflow to automate business processes through e-mail, whether the user is connected via a network, on a low-speed connection or disconnected. When synchronizing data, Notes R5 replicates only the changes in documents. Many competitive products send entire documents, wasting time and resources. Notes R5 software can be updated remotely, on command, or programmatically, while the competition makes you visit each desktop or log into a central server for updates. Notes R5 can track a wider range of information sources than typical end-user client software, allowing you to bookmark not only Web pages, but group calendar views, documents, databases and saved searches all in one place for better information and project management.

1.5 New terminologies used in Lotus Notes Release 5


With the advancement in technology, Lotus has introduced some new terms in the latest release, as follows:

Directory Catalog The Directory Catalog is a compressed version of one or multiple Domino Directories that improves the speed of name lookups and name resolution for all organizations. Domino Directory The Public Address Book is now referred to as the Domino Directory. Directory Assistance The Master Address Book is now referred to as the Directory Assistance. Domino Enterprise Connection Services (DECS) Lotus Domino R5 includes DECS for building live links between Domino pages and forms to data from relational databases. Byte-Range Serving Allows users to download files in sections rather than all at once. Transactional Logging Domino now allows for 24x7 online server backups and recovery support -- so you no longer need to shut down Domino servers in order to maintain them. A transactional log provides a sequential record of every operation that occurs (sequential writing on disk is much faster than writing in various places on disk).

12

Lotus Domino for S/390 R5 Installation, Customization and Administration

Logging helps to ensure complete data integrity for updates and enables you to perform incremental database backups.

Online, in-place compaction This means that when you compact a database, the compaction occurs in place, meaning that your server does not require extra disk space. Also, users can continue to work in the database during the compaction. Native support With support for native MIME content and native SMTP routing, Domino now integrates the features that previously required a separate message transfer agent (MTA). The native support means that conversions between Notes format and Internet format are no longer required. Redesigned user registration The redesigned user registration allows you to easily register users from other directories -- whether those directories are from cc:Mail, MS Mail, Exchange, Windows NT, or another LDAP directory. Domino R5 also includes the registration API calls, so you can integrate your own migration tools. When registering users, you can select to migrate people and groups from a foreign directory source.

1.6 Available platforms


The new release of Lotus Domino Server elevates the standard for enterprise messaging, groupware, and Web application development servers. It is available on all Lotus Domino Server platforms. Table 2 is a summary of the various operating systems platforms that support Lotus Notes/Domino Release 5.0.
Table 2. Available platforms for Release 5.0

Platform OS/390 V2R6 or higher UNIX (AIX V 4.3.1 or higher, HP-UX 11.0, Solaris/SPARC 2.6, Solaris/Intel 2.6) OS/2 Warp Server V4.0 Windows 95/98 Windows NT Server 4.0 and Windows NT Workstation 4.0 Macintosh Power PC 7.6, 8.1 OS/400 V4R2

Domino Server R5 Yes Yes

Notes Client R5 No No

Yes, IIIQ99 Yes Yes No Yes

No Yes Yes Yes No

1.7 S/390 is just another server platform


We saw in Table 2 that S/390 runs a Domino server just as any other supported server platform does. The Notes architecture means that the server platform is transparent to the users:

The value of Lotus Domino on S/390

13

Users access a Domino server on S/390 (from a Notes client or from the Web) in exactly the same way that they access any other Domino server. It looks exactly the same, and they cannot tell what the underlying platform is. A Notes administrator can manage the Domino server on S/390 using the Notes Administrative Client from any Notes workstation. Again, this is exactly the same as for any other Domino platform. Note: The only difference is that you cannot start a S/390 Domino server from the Notes Administrative Client. Domino on S/390 uses OS/390 UNIX System Services. OS/390 is branded UNIX 95-compliant. You can access the S/390 server using these interfaces and it looks like any other UNIX platform. Therefore, you can easily introduce S/390 servers alongside other servers in your Notes environment.

1.7.1 S/390 as an application server


You can think of S/390 as a server. S/390 has undergone a major transformation over the past few years. If you are looking for a server platform for an application, you should consider S/390. OS/390 supports the UNIX interfaces. OS/390 has been branded to the UNIX 95 level by the X/Open Company Limited (see http://www.s390.ibm.com/oe/customer.html ). Lotus and IBM used these interfaces to port the UNIX version of the Domino code onto S/390. This enables us to deliver the Domino server on S/390 much faster than if we had rewritten it to the traditional OS/390 interfaces. S/390 can plug directly into a local area network (LAN) with its Open Systems Adapter (OSA) card. S/390 supports intelligent workstations and network computers. S/390 supports the latest technologies such as Web Serving, Lotus Domino, object oriented programming, and Java. S/390 supports the TCP/IP networking protocol. S/390 can run many application packages, including SAP, BAAN, PeopleSoft and Lotus Domino. Some S/390s can sit in a rack-sized enclosure and do not take up much space. This makes them a very cost-effective platform while providing the power you expect from S/390. S/390 is a server that is relevant for today's applications. When you are choosing a server for your applications, S/390 should be one of the options that you consider. When you look at the servers available, you will find that S/390 has some unique characteristics.

1.8 The unique benefits of S/390 as a Domino platform


While S/390 appears to Notes users as just another server, the S/390 server platform provides a lot more function than other servers. We provide here a list of the key differences that you need to be aware of in your planning.

14

Lotus Domino for S/390 R5 Installation, Customization and Administration

S/390, and its operating system OS/390 (previously called MVS), have a long history in the commercial marketplace. As such, they have matured into a powerful server platform that meets the needs of users of commercial systems. Compare that to the UNIX history in the commercial marketplace, and the PC operating systems, which are relatively young. Functions such as clustering (for scalability and availability) and systems management tools that are key issues in commercial systems have been available on S/390 for many years and are more mature than on many other servers. Users of S/390 recognize and value that maturity. To draw a clear picture of the uniqueness of the S/390 server for Domino, we address it under two topics: The value of a large Domino server Other unique benefits of S/390

1.8.1 The value of a large Domino server


So far, many Notes rollouts have used a large number of relatively small servers, because that was the only option available. Organizations that have done that have found that there are a number of disadvantages in that approach. S/390 has the capability to support a large Domino workload. In July 1999 we announced Notes bench results that certified support of 32,000 connected mail users, making it the largest Domino server available. In addition to these test results, consider S/390's track record: IBM has been running a production Domino server on S/390 since November 1996. This supports the largest number of users on any Domino server in production use within IBM, and the largest number of active Notes client users in the world. The S/390 platform is easily capable of supporting many thousands of users. Many of our customers do that today with other applications. We know that the S/390 hardware and software can run production systems with thousands of users because we have been doing it for many years. A S/390 server is able to support large workloads because IBM has invested in many facilities in the processor and software to provide scalability, including: Very efficient use of symmetric multiprocessors (SMPs), even up to 12-engine machines Addressing of 4 terabytes of expanded processor storage along with the 31-bit (2 GB) storage addressing that it has had for many years Efficient techniques for keeping key data in processor memory where it can be accessed quickly A sophisticated job scheduler The removal of bottlenecks Shared access to all disks by all processors Separate, dedicated I/O processors

The value of Lotus Domino on S/390

15

Many servers may claim large capacity numbers. Not many are doing it in practice. Domino for S/390 has earned a certified Notesbench run of 32,000 mail users (see http://www.notesbench.org). So what are the benefits of a large server for Domino? 1.8.1.1 Less administration effort The larger the server, the fewer the number of servers you need to run. Fewer servers mean less administration effort to manage your Notes environment. This is a major issue, since surveys show that more than 80 percent of the cost of a client/server solution is in administering a system. It is also an area of cost that is easily forgotten when you start the project, but which becomes a major focus once you roll out many servers and need to provide good service. Fewer servers mean less work in the following areas: Installing, monitoring and repairing hardware Installing and upgrading operating systems and Domino software Installing and managing Domino servers and the connections between them Monitoring and managing inter-server tasks, such as mail routing and replication If you can host an application, or even a whole domain, on a single server, many design tasks become easier. You do not need database replication to other servers. You do not need mail routing, Public Address Book distribution or network connections. The best way to reduce work is to eliminate it completely. 1.8.1.2 Access to current data When an application is distributed across multiple servers, the various copies of the databases are kept in sync using replication. However, replication is an asynchronous process, which means that, at any point in time, the most current data will not have been propagated to all of the replicas. In the ideal case of a single server for an application, there is no replication and everyone accesses the single up-to-date copy of the data. In an environment with multiple servers, data is more current with few servers than with many. 1.8.1.3 Faster mail routing When mail is sent from a client, it is stored in the server's mail box and then forwarded to the target server by the router task. It takes time for the mail to be routed across the network. While a server can route mail to several servers at the same time, it only opens one connection to each server. Therefore, if a large mail file is being transferred to any server, all other mail destined for the same server must wait until the first transmission finishes. If the mail files for many users are on a single server, mail between them does not need to be routed across the network. Mail is placed directly into the recipients mail file, which is much faster. 1.8.1.4 Less disk space When an application is spread across multiple servers, the design usually involves multiple replicas of each database. These all use disk space. By

16

Lotus Domino for S/390 R5 Installation, Customization and Administration

reducing the number of servers, you reduce the number of replicas. This can save huge amounts of disk space. 1.8.1.5 Less network traffic Regardless of how many servers you have, the amount of client-to-server network traffic will be the same (although with centralized servers that traffic may need to go over a wide area network, while it could go over a LAN if the server is local). If you have multiple servers, you also have inter-server traffic for database replications, mail routing and access to other applications. The more servers you have, the more inter-server traffic you will have. Therefore, by reducing the number of servers you can reduce the total amount of network traffic. 1.8.1.6 Less processor capacity If you run multiple servers, you must install sufficient processor capacity on each server to handle its peak usage. It is very likely that the peak usage of each server will be at a different time and, therefore, at any one time you will have a lot of unused capacity in the overall system. As an extreme example, if you were to place servers around the world to support users in many countries, then at any one time some servers would be busy and others would be idle because it is the middle of the night in that time zone. By consolidating all of the users onto one server, you do not need the total capacity that your smaller servers had, so your server capacity could be much smaller. In practice, you can reduce the total server capacity you need even by consolidating servers in a single location. One S/390 user found that total capacity could be reduced by 22 percent just by consolidating two servers in the same location onto one.

1.8.2 Other unique S/390 benefits


We saw previously that a large server has many benefits for Domino, and S/390 is a large server. However, S/390 has other unique benefits, which we discuss in the following sections. There are good reasons why many of the world's largest banks, insurance companies, government agencies, and other large enterprises use S/390 to deliver applications. A more detailed discussion of this subject is available in Selecting a Server - The Value of S/390, SG24-4812. 1.8.2.1 Multiple applications on one server The S/390 server runs many applications at the same time. Since todays view of a server is a box that runs one application, this is one area where S/390 may be contrary to your expectations of a server platform. The philosophy in the UNIX and PC server marketplace is to run each application on its own server. In a Notes deployment, the recommendation is to split up the functions so that each function runs on a dedicated server. The reason for this is to provide workload isolation, security, availability and performance. The underlying reason is that the operating systems and hardware on these platforms are not able to isolate the effects of multiple workloads on the same server, that is, the failure of one application or function could cause a failure of the whole system, or one application could take more than its fair share of system resources, causing poor performance of other applications.

The value of Lotus Domino on S/390

17

This is contrary to the S/390 philosophy. Since the early 1970s, our customers have told us that they want to run multiple applications on a single server. We therefore built into the hardware and software the functions that you need to do that and still provide excellent workload isolation, security, availability and performance. For example: OS/390 virtually never fails. More than 50 percent of the OS/390 kernel code, and much of the S/390 hardware, is concerned with detecting errors and resolving them while keeping the system running. One customer ran for more than 2,000 days without "rebooting" (re-IPLing). If one application fails, the operating system isolates it to the smallest possible part, cleans it up and allows it to be restarted. Other applications are not affected. OS/390 has a very sophisticated workload manager that ensures that each application gets only its fair share of the resources, according to its needs. These needs may change at different times of the day, and OS/390 will continuously rebalance priorities. OS/390 isolates users and applications from each other. Most users of S/390 servers run many applications on a single server. You should consider this normal for a S/390 server. 1.8.2.2 Running Domino alongside enterprise applications Running Domino alongside other enterprise applications on a S/390 server has many benefits: It further minimizes your administration effort because you have fewer platform types to support. It further reduces the total processor capacity that you need, especially because different applications are likely to have their peak loads at different times. It allows applications to communicate at processor speed, without going across a network connection. A lot of enterprise data is stored on S/390 servers. Many Notes users wish to access that data and the applications that process it. By putting the Notes application on the same physical server, you accomplish the following: Improve performance Improve availability Simplify system management Minimize server and network costs Eliminate the need to take copies of the data onto other servers, which takes time and resources and means that you may be working with back-level data

Even if you wish to support only a small number of Notes users, there are advantages to running the Domino server on a S/390 alongside other applications rather than investing in a separate server with its own support needs. 1.8.2.3 Multiple operating systems on one server S/390 goes a step further and allows you to run up to 15 different operating systems on a single S/390 server. This function is called Processor Resource/Systems Manager (PR/SM), also commonly referred to as Logical 18

Lotus Domino for S/390 R5 Installation, Customization and Administration

Partitioning. PR/SM provides an additional alternative to Domino partitioning -see 11.3, Domino Server partitioning on page 189. PR/SM provides a higher degree of isolation by running separate operating systems, although at a slightly higher cost in terms of system resources used. PR/SM is part of the strategy to minimize the number of servers, and it is used for the following: Hardware consolidation You can run different operating systems or operating environments on a single server. This could be different operating systems, such as VM, OS/390 and TPF, or different versions of OS/390, for example. You can use this to consolidate multiple servers, including Domino servers, onto one physical server without merging the environments. This is a quick way to reduce the number of servers you run. Development and test You can provide a separate development and test environment (and Notes domain) on the same physical server for the upgrading of operating system software, Domino server code, or testing new functions and applications. Workload isolation You may need to keep some workloads separate; for example, if you provide outsourcing services to clients, to provide security between workloads (for example, separating internal and external communications), or if some workloads require extremely high availability. 1.8.2.4 Low costs Many surveys by independent consultants have shown that S/390 is a less costly solution than running many small servers. See, for example: Cost of Messaging: Comparative Study of the S/390 - Lotus Domino Solution , by the International Technology Group Domino for S/390 - The Business Case, by the International Technology Group Selecting a Server - The Value of S/390 , SG24-4812. S/390 allows you to run a small number of large servers and provides you with advanced automation tools. These dramatically reduce the costs you will incur in supporting your environment. Be careful when you estimate the costs for other server solutions. If you do not have experience in running these types of systems, it is very easy to underestimate the costs of hardware, software and support staff to get good availability and performance in those environments. 1.8.2.5 Security and integrity A major concern of commercial and government enterprises is the security and integrity of their data. This concern is magnified when connections to the Internet, or even extended access through an intranet, are considered. OS/390 provides a strong framework for control of data access. Security is controlled by the System Authorization Facility (SAF), which checks all access requests to system resources using an external security manager such as the OS/390 Security Server (formerly known as RACF). OS/390 is committed to

The value of Lotus Domino on S/390

19

maintaining the integrity of your data, whatever happens. IBM announced an integrity guarantee for MVS in 1972, and S/390 is designed to ensure that data integrity is carefully maintained. It is also much easier to provide physical security for a centralized S/390 server than for many distributed servers. 1.8.2.6 Reliability and availability S/390 systems are used in environments where high availability is crucial. S/390 hardware and software have many availability features built in. These include the avoiding or automatic recovering from failures and the ability to apply system maintenance with minimal disruption to system operation. As a result, many S/390 users run a single S/390 server and get excellent system availability. In contrast, many UNIX and PC servers need clustered systems, at additional hardware and software cost, to achieve similar levels of availability. Keep in mind that availability is a key requirement for any application that uses the Web serving function of Domino. The Web culture has caused us to become very impatient consumers of information. If a particular Web site is not available or is responding slowly, the client will shift his/her attention to another site, perhaps that of a competitor. The Web also extends the hours of opening for your enterprise to 24 hours a day since clients can access at any time of the day or night, or may even be located across the world. 1.8.2.7 Growth and flexibility Suppose that you wish to grow your Notes environment by adding new users and applications. We have already seen that growth can mean adding many more servers. It could also mean upgrading servers or splitting users across more servers. Do not underestimate the amount of effort in doing this. It can be a major logistical exercise, especially if the servers are distributed geographically. It will take time and effort to do it, and the effort to manage your new Notes environment will increase significantly. In contrast, upgrading a S/390 server is easy. It can often be done in a few hours, usually with no associated software changes, and the upgrade does not significantly increase the amount of system administration required. The more you grow, the more efficient S/390 becomes. There are many different sizes of S/390 servers, from a server based on a PC (P/390) to a cluster of very large processors in a Parallel Sysplex. When choosing your initial server, keep in mind the size of your eventual implementation and select a server that can be upgraded to meet your future requirements. Consider also a requirement to upgrade the Domino server code, which may require an upgrade to the operating system software. With a single S/390 server you only need to do that once, and as a S/390 user you will have experience with doing operating system upgrades. Contrast that with needing to upgrade the software and Domino code on many servers that may be geographically remote. Your server choice can have a major impact on your future business flexibility. Suppose you connect a Notes application to the Web and the access rate goes up by a factor of 10 or 100. How will you handle that kind of growth? If you cannot handle it quickly, you will significantly impact your customer service.

20

Lotus Domino for S/390 R5 Installation, Customization and Administration

1.8.2.8 Powerful I/O capability and backup speed One of the factors that is often forgotten until it causes problems is the speed at which a server can process data. This may not be a problem during the early stages of a project, but in a production situation it becomes critical. Certain tasks on the system, including replication and taking data backups, require the processing of large amounts of data. If this cannot be done in the available time frame, it can have a major impact on your applications. The S/390 server has a very powerful I/O subsystem. The I/O processing is done by a separate set of dedicated processors within the S/390 server. Therefore S/390 servers can do I/O intensive tasks such as backup and recovery of data much faster than many other server platforms. 1.8.2.9 Data S/390 servers S/390 servers S/390 has the management have the capability to support large amounts of data. There are in production today that access more than one terabyte of data. speed to access that data, and the tools to manage it.

1.8.2.10 Low risk In any project there is a risk of failure. We have seen many client/server projects fail over the past five years, in general because the risks of the project were not accurately assessed and managed. You need to ask what could go wrong, account for it in your initial choices, and manage the risks throughout the project. In many cases, users are deploying large systems that they have no previous experience with. As they go through the project and better understand the capabilities of the various components, they often realize that they need to buy a lot more hardware and software, put in many more support staff, or that the technology is incapable of delivering what they expected. These items should have been identified at the start of the project, risk factors built into the costs for items not clearly understood, and key areas investigated at an early stage. In today's fast-moving marketplace no server solution is going to be risk-free. Different solutions will have different risks associated with them. However, S/390 does have one major advantage: many users have a lot of experience in running large commercial systems on S/390 servers. We know what you need to run a large production system using S/390 servers, in terms of hardware, software and support staff. That has sometimes been to S/390's disadvantage since the costs of a S/390 server are visible and known. However, it is a major advantage when you look at risks. S/390 is a lower risk solution. You are not likely to get many surprises with a S/390 implementation.

The value of Lotus Domino on S/390

21

22

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 2. Notes deployment using S/390 servers


When deploying Notes using a Domino server on S/390, most of the standard Notes considerations apply. However, a Domino server on S/390 introduces some changes because: S/390 is a much larger server than other Domino servers, which allows you to implement your rollout with fewer servers. The S/390 server has some unique capabilities. For example, it is designed to run multiple applications at the same time. Most users do exactly that. This contrasts with most UNIX and PC servers, where each server runs a single application. Implementing Notes using S/390 servers therefore provides some interesting new opportunities, as well as some differences that need to be understood and planned for. In this chapter we discuss the differences that you need to consider when using a S/390 server in your deployment.

2.1 Planning for Notes deployment


This section discusses differences to consider in planning for Notes deployment.

2.1.1 About selecting a pilot application


When looking at a pilot application, keep in mind that Domino can be used to develop and deliver a wide range of applications, not just electronic mail or groupware applications. Consider using Domino to: Integrate new Domino applications with existing applications and data that reside on S/390. There are tools to provide these connections, and these are being ported to S/390. Running Domino applications on the same server as the existing applications and data improves the performance, accessibility and manageability of the total application. Put a new front end on existing applications. You could Web-enable existing systems using Domino as the development and delivery mechanism for the new user interface. Deliver new applications (including Web applications) using the powerful Domino application development environment.

2.1.2 About identifying a workgroup for initial rollout


A S/390 server runs many different applications and is supported by a group of support people. It is important that these people understand the importance of the Domino server to the organization, and that they have some understanding of Notes so that they can provide better support to the Notes administrators. Therefore, consider including key representatives from the S/390 operations and support areas in the initial rollout. They will better understand the impact of some of the things that they control, such as performance and availability, on the Domino environment.

Copyright IBM Corp. 1999

23

2.1.3 About taking an inventory of existing network infrastructure


When looking at your network infrastructure, you need to keep in mind that Domino on S/390 only supports the TCP/IP network protocol. Therefore, you need to provide TCP/IP connectivity on any client or server that communicates with the S/390 server, either directly or through a Local Area Network. OS/390 supports the TCP/IP protocol through the use of eNetwork Communication Server IP. With a S/390 server, you can run a large Domino workload on a single machine. To do that, make sure that you design your network to be capable of handling large volumes of traffic. S/390 designers understand how to do that. Domino administrator who have implemented large Domino servers (or many servers in the same location) will also understand the issues. Domino administrators who currently run distributed servers need to consider the impact of running a lot of traffic to a small number of large servers. Think about: Network bandwidth into the servers The existing network topology to remote sites Current utilization of the network Telecommunication company charges for remote site connections Keep in mind that using a single large server results in less network traffic than using many small ones. See Figure 3.

M any Servers
PC Server PC Server

One Large Server

Server to Server Traffic C lient to Server Traffic

Client to Server Traffic

Figure 3. Network traffic

In each case, the client-to-server traffic is the same (though it probably flows over a longer distance with the single server). With many small servers there is also all of the inter-server traffic, including mail routing, replication, and access to remote data. Network capacity is needed for that traffic, which does not exist at all in the single server implementation. The required network bandwidth should not be based on experience with traditional OS/390 systems. Notes applications are likely to have very different

24

Lotus Domino for S/390 R5 Installation, Customization and Administration

network bandwidth requirements. Base your estimates on Domino experience on other platforms. If remote connections do not have the necessary bandwidth or if telecommunication charges are high, you may prefer to consider remote mail servers to reduce host-bound traffic. Carefully consider the costs of the network against the costs of installing and maintaining remote servers. Alternatively, you could use services provided by Internet Service Providers (ISPs) for remote connections. Note that appropriate security precautions may be required for internal system access.

2.1.4 About assessing hardware and software needs


Before assessing your hardware and software needs, you need to have a good understanding of what a S/390 server can offer. We discuss this in Chapter 1, The value of Lotus Domino on S/390 on page 3. Given its unique capabilities, you may wish to consider a Domino server on S/390 in a number of roles in your Notes deployment:
2.1.4.1 Small Domino server If you just want a small Domino server, run it on a S/390 server along with other applications, thereby avoiding the need for a separate server with its management overhead; and the Domino server can share the S/390 server resources. 2.1.4.2 Large Domino server There are major advantages in deploying a large Domino server on S/390:

If you need additional capacity for growth, you can add additional applications and users to a single Domino server on S/390 (or multiple Domino servers on the same S/390 server if you prefer). Indeed, you could potentially put all your Notes applications on a single S/390 server. S/390 avoids the need to modify the infrastructure to cope with rapid growth. It is much simpler to implement (or grow) a single S/390 server than many servers of another platform type. If you wish to consolidate existing servers, S/390 makes an ideal target system. Now that Domino fully exploits much bigger hardware, many users wish to reduce the number of servers they need to administer as they grow their use of Notes. S/390 is large enough to support consolidation of many servers, thus reducing support costs dramatically.
2.1.4.3 Replication hub If you have multiple servers in a hub and spoke topology, consider using a S/390 as the hub. It provides the scalability and availability that the hub needs. 2.1.4.4 Mail router Similarly, S/390 provides the scalability and availability that you need for a mail router. 2.1.4.5 Access to enterprise data For many current enterprise applications, the data and application code run on a S/390 server. Add a Domino server to the same platform to provide efficient access to that data from Notes clients or from the Web.

Notes deployment using S/390 servers

25

2.1.4.6 Backup server If you need high availability for a Notes application, you may need to consider backup servers using Domino clustering. Consider a S/390 server as a backup server. Normally the server will do very little (just apply database changes), and therefore will use only a small amount of resource on the S/390 server. If the primary server fails, the workload can be picked up on the S/390 server. The OS/390 workload manager can automatically reprioritize the new workload, along with the current workload, based on your requirements.

2.1.5 About preparing for administration and support


Because S/390 servers run multiple applications, management of the server is done by a central group of operators and system programmers. Administration of the S/390 server and operating system is done only by the S/390 support staff, to protect the overall system. Notes administrators do not need to manage the server hardware and software, but they have to work with the S/390 support staff to ensure that they get the environment that Domino needs. Administration of the Notes environment is done by Notes administrators, as for other Domino servers. S/390 support staff can think of Notes as a major subsystem on OS/390, similar to CICS, IMS or DB2, with its own specialist support staff. It is critical to the success of the Notes deployment on S/390 that the two groups of people work together as a team, that they build an overall support plan for Domino on S/390, and that everyone understands the specific roles of each group and how they interface with each other.

2.1.6 About developing administrative processes


On a S/390, some administrative processes will be done by the S/390 server support staff, including: Server capacity planning Server upgrades Disk capacity planning Making additional disk space available to Notes Data backup and restore Disaster recovery Performance management Availability management Operating system changes Installation of new Domino releases You need to develop your Notes administrative processes in conjunction with the S/390 support staff. The S/390 support staff should make sure that they monitor the Domino server closely in the early stages of the implementation. Domino may use system resources differently from other applications that they are familiar with (for example, Domino tends to use more processor memory than applications written for CICS and IMS). They need to monitor Domino to ensure that they are giving it
26
Lotus Domino for S/390 R5 Installation, Customization and Administration

an appropriate amount of server resources. DASD usage, too, can vary from system to system, depending on the amount of mail each user saves and the number of databases created.

2.2 Understanding the Notes environment


In the OS/390 environment, having the system at the correct maintenance level is very important. Every PTF that is listed on the Web site should be applied, whether it seems related or not. Domino uses many different facilities of the system, and has been developed and tested at a certain maintenance level for each system component. A majority of Domino problems have been solved when the proper OS/390 maintenance was applied. Also, the BPX parameter values are very important. If set too low, Domino can run out of UNIX System Services resources. Again, a large portion of "Domino problems" have been solved when the BPX parameters were set to the recommended (not default) values.

2.3 Planning a Notes system


This section describes how to link servers in a Notes system in order to establish a path for replication and mail routing.

2.3.1 About dedicating servers by task


This section of the deployment discusses dedicating Domino servers to specific Notes tasks to simplify administration and improve server performance. As we discussed in 1.8.2.1, Multiple applications on one server on page 17, this is exactly the opposite of what we would recommend on S/390. A S/390 server provides the facilities to run many different tasks on the same server with excellent performance and availability. We recommend that you think of running everything on the smallest possible number of Domino servers on the smallest possible number of S/390 servers. That will give you the most efficient use of the hardware resources and the simplest environment to manage. Only consider splitting work across multiple servers when there are significant benefits to be obtained, such as a need to isolate production and test workloads, or to isolate workloads with very different security requirements. Even then, consider running multiple Domino servers on the same S/390 server using Domino partitioning or S/390 logical partitioning (LPAR).

2.3.2 About connecting Notes servers


By using a large Domino server on S/390 rather than many small servers, you can dramatically reduce the number of servers. This provides for a much simpler set of connections and a much simpler replication strategy.

2.4 Populating Notes with servers and users


A Domino server uses the hierarchical file system (HFS). Sizing and placement of these files (as with any platform) are important for good performance. We recommend that you have a separate HFS file for every major mount point (directory), and that they be spread across your DASD subsystem so the disk

Notes deployment using S/390 servers

27

accesses do not interfere with each other. We also strongly recommend that you allocate large enough files (and extents) so that you wont run out of space unexpectedly, or your Domino system will come to a halt.

2.5 Planning a replication strategy


There are no S/390-specific considerations. However, using S/390 servers allows you to run fewer servers and therefore results in a simpler replication strategy and faster replication.

2.6 Developing a plan for Notes mail


There are no S/390-specific considerations. However, using S/390 servers allows you to run fewer servers and therefore results in a simpler mail routing topology and faster mail delivery.

2.7 Maintaining a Notes system


We saw earlier that some maintenance tasks on a S/390 server are done by the S/390 support staff. They will already have processes for server administration, backup and monitoring. The Notes administrator should work with the S/390 support staff to ensure that appropriate processes are put in place for the Domino server and data.

2.8 Maintaining security in a Notes system


It is important to understand how Domino relates to S/390 security. OS/390 provides an extremely secure environment, based on the System Authorization Facility (SAF), which ensures that any request on the system is authorized by a security manager, such as OS/390 Security Services (RACF). In addition, S/390 servers are generally installed in a secure environment. Therefore, the Notes administrators can be confident of the security of the underlying S/390 server platform. Domino runs under the authorization of the OS/390 security manager; therefore, the Domino server must be associated with a valid user ID on the system that has an appropriate level of system authority.

28

Lotus Domino for S/390 R5 Installation, Customization and Administration

RACF - ALTUSER HEINRJ LNOTES PARAMETERS COMMAND ===>

Delete ALL LNOTES information (NOLNOTES) ===> -- OR --

Enter YES to DELETE

Select only ONE option from the following, then press ENTER Delete Lotus Notes ID Specify new Lotus Notes ID =>
Figure 4. New LNOTES segment in OS/390 Security Server (RACF)

(NOSNAME) ===> (SNAME)

Enter YES to DELETE

RACF now has the new segment LNOTES. This is available for use with the Web connector product.

2.8.1 Notes internal security


Notes provides its own security management for controlling what users are allowed to do on the Domino server. To ensure the best security and integrity for Domino on S/390 we recommend: Do not start the Notes server with superuser authority. Limit superuser access to a small number of support staff. Control access to the Domino HFS datasets. See 4.5, Define user IDs to OS/390 Security Services (RACF) on page 64 for more information. For UNIX System Services security recommendations, see OS/390 UNIX System Services MVS Planning, SC28-1890.

2.9 Planning for optimal performance


To ensure optimal performance of Domino on S/390, you should follow the recommendations for Lotus Domino R5. In addition, on a S/390 server you should: Use the standard S/390 performance monitoring tools and techniques to look for performance issues and resolve them. In particular, you need to ensure that Domino is getting an appropriate level of system resources, including processor cycles, processor storage and multiprogramming level. Use RMF and other reporting tools on a regular basis. Follow the recommendations on OS/390 parameters given in Chapter 15, OS/390 parameter recommendations for Domino on page 311. Read Lotus Domino for S/390 Performance Tuning & Capacity Planning SG24-5149. Make sure that the Domino modules are loaded into Dynamic LPA; see 8.2, Loading the Dynamic LPA modules on page 123.

Notes deployment using S/390 servers

29

Make sure that the DASD volumes that hold the Notes databases are on subsystems that have DASD Fast Write (DFW) and Read Caching enabled. Spread your HFS files across DASD, control units and channels for better performance. Collect SMF type 108 records, available with Domino R5. In R5, you can make some Domino modules non-swappable.

2.10 Extending your Notes system


There are no S/390-specific considerations.

2.11 Using Notes with the Internet


There are no S/390-specific considerations.

2.12 Notes directory structure


This section discusses the way in which Lotus Domino Server data is stored on the S/390 server. It describes the relationship between Domino Server databases, UNIX HFS files managed by DFSMS and OS/390 data sets. It makes suggestions on structuring the hierarchical file system on OS/390.

2.12.1 How Domino data is stored on OS/390


Lotus Domino Server has the following types of data: Executable modules Control files, such as notes.ini Notes databases Templates All of this data is stored in one or more HFSs. For a complete discussion of HFS datasets see Chapter 13, HFS data set management on page 269. Each Notes database, each template, and each executable module is stored in a separate UNIX file. The notes.ini control file, notes databases and templates are all stored in ASCII format, exactly the same as on the other Domino server and Notes client platforms. This allows data transfer to and from all the other Lotus Domino servers and Notes workstation platforms without any data conversion.
Notes:

1. Be sure that you edit the notes.ini file only from the OS/390 environment. This can be done either using the UNIX shell command viascii, or using the OMVS interface command OEDITASCII. 2. If you download to a workstation to edit, make sure you choose an editor that does not insert line feeds (most do). 3. Do not edit the notes.ini file while the server is running, otherwise your change might overwrite any changes that the server is making.

30

Lotus Domino for S/390 R5 Installation, Customization and Administration

2.12.1.1 UNIX Hierarchical File System OS/390 provides a standard UNIX HFS for applications that use the UNIX interfaces. For example, the name of the notes.ini file on OS/390 could be: domino1/notesdata/notes.ini.

You can access the HFS using either: The UNIX shell, entered from rlogin, Telnet or the TSO OMVS command The interactive shell (ISHELL), an ISPF-like interface, using the TSO command ISHELL The data in the HFS is physically stored in one or more HFS data sets.
2.12.1.2 Differences between PC and UNIX file systems If you know PC file systems, you will find the UNIX file system very similar. However, note the following differences:

The slash in path names goes the opposite way. On UNIX it is /. On PCs it is \. In UNIX, file names are case-sensitive. That means that in UNIX you need to type file names in the correct case, or you will not find the file. UNIX has a single root directory, which is /. PCs have a root directory for each disk (such as a:, c:, d:). In UNIX, when you want to add another disk to the file system, you mount another file system into the directory tree at a mount point (directory). Some UNIX commands are the same as PC commands (for example, mkdir to make a directory). Some are different (for example, to display the contents of a directory in UNIX, you use the ls command). We have included a table of the UNIX commands you are likely to need in C.3, UNIX System Services commands on page 404.
2.12.1.3 OS/390 HFS data sets One or more HFS data sets make up the UNIX hierarchical file system. An HFS data set is a standard OS/390 data set, but with a different file organization. It is allocated with DSNTYPE=HFS. OS/390 manages HFS data sets in the same way it manages other types of data sets. We discuss the management of HFS data sets in Chapter 13, HFS data set management on page 269. Only applications using OS/390 UNIX System Services routines can see the file structure within a data set.

Figure 5 on page 32 shows the hierarchical file system on OS/390, made up of HFS data sets.

Notes deployment using S/390 servers

31

Root file system (only one) / HFS data set #1 Dir1 Dir2

M ount point

Dir3 File1

File8

Dir4

M ount point

Dir HFS data set #2


File2 File3 File4

Dir Dir5

HFS data set #3

File5 File6 File7

Figure 5. HFS data sets

Some of the characteristics of HFS data sets are: Each HFS data set can contain one or more files and directories. Each HFS data set is mounted to the file system at a mount point. This allows access to that data through the directory structure. Eventually, all HFS data sets are mounted back to the root directory. The root directory is also contained in an HFS data set. This directory must exist for UNIX System Services to start. There is only one root directory. To update the root directory you must have UNIX superuser access (UID=0). To mount an HFS data set you must have superuser access (UID=0). Each directory must be contained in a single HFS data set. A directory cannot span HFS data sets. However, subdirectories can be in different HFS data sets. An HFS data set cannot be shared between OS/390 systems in Read/Write mode. It is possible to share an HFS between multiple systems if the HFS is mounted Read-Only on all systems; however, we do not recommend this. An HFS data set can have up to 123 extents. For details see 13.2, Space management on page 272. For changes in DFHMS 1.5 see 13.3, DFSMS 1.5 on page 277. We recommend that you use DASD volumes with read and write caching for the Domino HFS data sets. If you are running on DFSMS 1.4 or below, there is a restriction in that you are limited to a single volume per HFS. The HFS cannot span multiple volumes. As of DFSMS 1.5, a single HFS data set can span multiple DASD volumes. For details see 13.3, DFSMS 1.5 on page 277.

2.12.2 Space restriction when running DFSMS 1.4 and earlier


Note: With DFSMS 1.5 you effectively have no restriction on the size of the UNIX directories or notes databases. With a single HFS data set being capable of

32

Lotus Domino for S/390 R5 Installation, Customization and Administration

spanning up to 59 volumes, you could technically (assuming you used 3390-9s) have a 495 GB UNIX directory or Notes database. When using DFSMS 1.4 and ealier, the maximum size of a single HFS (and the maximum size of a single UNIX directory) is limited to the physical size of the DASD volume. When we talk about a single DASD volume, we are referring to the logical volume that OS/390 sees. The most common logical volumes today are: IBM 3390 Model 3, with a size of 2.8 GB IBM 3390 Model 9, with a size of 8.4 GB Most DASD devices today emulate the IBM 3390 Model 3, so for many users not running DFSMS 1.5 the maximum size of a UNIX directory will be 2.8 GB. IBM 3390 Model 9 devices are less common in the marketplace. If you have them, be careful about using them for Notes data, since they have lower performance characteristics than 3390 Model 3s. Some DASD devices can emulate 3390 Model 9, such as the Multiprise Internal DASD. Those devices would give good performance and allow you to have UNIX directories with 8.4 GB of space. In considering this restriction, keep the following in mind: Many of the issues of directory design are common to all Notes implementations. For example, any Notes implementation with thousands of users needs to provide data storage for lots of data. The amount of data is the same on a S/390 server as on any other combination of servers. In fact, the total amount of data may be less on a S/390 server because there is less need to replicate information between multiple servers. While other servers may not have the same limitation, with them you need to plan how you will spread the data across servers. S/390 is easier than that. A S/390 solution can have far fewer servers (perhaps only one) and you need only to decide which directories to put the data in. With DFSMS 1.5 (which is shipped with OS/390 2.7) an HFS data set can span up to 59 volumes. Even if you could put all of your data in a single UNIX directory, and therefore a single HFS data set, you would not do that. We know from our experience with very large IMS and DB2 data bases that there are problems with performance and manageability, such as the time to back them up. In practice we split up very large data bases into multiple data sets to avoid these problems. For Notes databases, there are also design reasons to keep them smaller. Therefore, you will want to split your Notes data up into separate UNIX directories and HFS data sets anyway.

2.12.3 Implications of UNIX directory size


In the following sections, we discuss the implications of the UNIX directory size restriction on: Notes database size Notes directory size Specifically on the notes data directory and the Public Address Book

Notes deployment using S/390 servers

33

2.12.3.1 Notes database size Domino R5 can now support significantly larger databases than previous releases, and although currently certified up to 64 GB, there is no imposed maximum size (with DFSMS 1.5). If you are running DFSMS 1.4 or earlier, if you have 3390-9 format DASD, you will be able to store 8.4 GB databases on S/390. If you only have 3390-3 format DASD, the maximum size Notes database that you can store on S/390 is 2.8 GB. In the past, we have found that:

Most Notes databases are smaller than 4 GB. Once Notes databases become large, they tend to suffer from performance and manageability issues. But each release improves this situation. Where Notes applications expect to have large amounts of data, they will probably be written to support multiple Notes databases. That way, once the amount of data exceeds an HFS data set, the data can spread into additional databases without a need to rewrite the application. For such applications, you would use multiple 2.8 GB databases on S/390, instead of multiple 4 GB databases.
2.12.3.2 Notes directory size The maximum amount of data that can be stored in a single directory when running DFSMS 1.4 or below is 8.4 GB if you have 3390-9 format DASD, and 2.8 GB if you have 3390-3 format DASD. You could have thousands of GBs of Notes data on the S/390 server. You therefore need to think about how you will separate that data into different directories. We discuss this in 2.12.4, Structuring Notes directories on page 34.

With Domino 4.x, when a database was compacted, the server created a replica copy in the same directory and then deleted the old version. Since both versions existed in the same directory for a period of time, you needed to allow for that in your design. With R5, the data is compacted in place.
2.12.3.3 Notesdata directory and Domino directory The Domino directory must be a single Notes database. Release 5 uses the space in the Domino directory more efficiently than R4 did (see 12.2.6, Migrating directory/database links to Domino R5 on page 248). If you have DFSMS V1.5, an HFS data set can expand across multiple volumes.

The Domino directory, mail.box file, dictionaries, and some system-related files must be stored in the notesdata directory. The help databases must be in the help subdirectory of notesdata directory. Notes template files used for server-based design replacement must also be in notesdata. Templates that are not used for manual design replacement or the creation of new databases can be stored in a different directory. The scheduled design task that updates database designs will find them automatically.
Note: If for any reason the router task is unable to deliver mail to other servers, the mail.box file may become very large and exceed its space limit.

2.12.4 Structuring Notes directories


A Lotus Domino Server running on S/390 could have a lot of data. Supporting thousands of users will probably result in many gigabytes of data, both for mail and for other databases. Since you are unlikely to be able to put all of your Notes

34

Lotus Domino for S/390 R5 Installation, Customization and Administration

data in a single directory, you need to think about a directory structure for your Notes databases: How Notes databases will map into directories How directories will map into HFS data sets How HFS data sets will be stored on S/390 DASD volumes We discuss mail first, since that consists of lots of users all with the same space limits. We will then discuss other Notes application databases.
2.12.4.1 Structuring mail subdirectories A Domino server on S/390 can support thousands of users. If these users use Notes mail, it can result in thousands of gigibytes of mail data. The organization of the mail directories is then very important. If you get the original design wrong and need to change it later, it may cause disruption to the users, since they have a pointer to their mail file on the Notes client.

The first question to consider is how much space you will allow for each user's mail database. A Notes mail database can contain rich text such as graphics and video, which take up a lot of space. IBM in the US plans for 100 MB of space per mail user. Lotus Central Europe recently established a 70 MB limit. The space allowed per user on a S/390 server is exactly the same as you would allow on any other platform. You can limit the amount of mail space a user has. From our experience the size of individual mail files is not so much a question of the space needed, but a question of education. If you give users a 30 MB limit, they will learn to cope with it. If you allow 150 MB of space, they will at some time use that. Experience shows that cleaning up even a 30 MB mail file takes a long time. Demand for space always grows, but a value of 50 MB to 60 MB seems adequate at the time of writing. Once you know the maximum size of each mail file, you can then calculate how many mail files you can fit into each directory. Remember that when you are running DFSMS 1.4 or earlier, the maximum size of a directory is 2.8 GB on 3390-3 format DASD and 8.4 GB on 3390-9 format DASD. This limitation is lifted when running DFSMS 1.5. You could take a number of different approaches to this: You could put the calculated number of users' mail files into each directory. Place them into numbered directories, such as mail0001, mail0002, mail0003 and so on, starting at the beginning. If you implement different space limits for different types of users, group users with the same limit together in the same directory and include an indicator of the maximum file size in the directory name. A variation of this is to define Notes database links in a single directory that point to the real databases in other directories (see the database links topic in Lotus Notes Administrator's Guide ). This is simpler from a management viewpoint. All users go to the same directory to find their mail file. Administrators can move mail files between directories without needing to change the Notes clients to point to a different directory. However, this may have performance implications since the mail directory could have thousands of database pointers, and searching it could be slow.

Notes deployment using S/390 servers

35

We present these options to help your planning. We have not done any testing of these different options and therefore are not able to make a recommendation.
2.12.4.2 Structuring application subdirectories You should also think about the directory structure for your other Notes application databases. You can base your structure on: Departmental organization You can organize the directory structure to mirror the organization of the company. Every employee should then be able to find information easily. Databases for more than one organizational unit are stored at higher levels in the directory structure. Workgroup organization The most commonly used structure for organizing Notes subdirectories is based on workgroups. Users belonging to a workgroup can easily find their applications. Functional organization This is similar to a workgroup organization, but requires that users' functions are reflected in groups in the public name and address book. Management requirements It is also worth thinking about a structure that helps the Notes administrators track management activities more easily. For example, you could place databases into directories based on how frequently they need to be backed up, or what performance level they require.

You may choose to use a combination of these approaches. Many companies divide their structure into functional subgroups and then split it up further on a workgroup or departmental level. A user's ability to access a database depends on that database's access control list (ACL) and not on its place in the directory hierarchy. To help users find databases, we recommend that you use directory and database links to point to the actual location of the database in the directory hierarchy. This allows you to move databases between directories (and therefore between HFS datasets and DASD volumes) without affecting users. This will be necessary as space requirements grow.
2.12.4.3 Sample directory structure Figure 6 on page 37 shows an example of a possible directory structure for both mail and applications.

36

Lotus Domino for S/390 R5 Installation, Customization and Administration

/notesdata /mail /mail0001 /mail0002 /mail0003 /mail0004 /sales /NorthAmerica /Europe /UK /France /Germany /Asia /marketing /product1 /product2 /support
Figure 6. Example of a directory structure

2.12.4.4 The notesdata directory Every Domino server has a master directory that contains the key server files, such as notes.ini and the Domino Directory. All the Notes databases for the server are stored in that directory or subdirectories of it. During server setup you set the name of the notesdata directory for that server. The default directory on S/390 is /notesdata.

As you can imagine, the notesdata directory is the most active directory in a Domino environment. Special attention should be given to its size and placement. The Domino Enterprise Server supports partitioning, which allows multiple Domino servers to run on the same OS/390 system. Each Domino server has its own notesdata directory and subdirectories. To differentiate the directories, we recommend that the notesdata directory should contain the Domino server name, as shown in Figure 7.
/server_name/notesdata where: server_name is the Domino server name

Figure 7. Recommended name for the notesdata directory

One advantage of this naming convention is that the notesdata directories are not defined in the root directory. For security reasons, access to the root directory should be restricted. By defining these directories in the /server_name/notesdata directory, Notes administrators can support the Domino environment without having access to the root directory.
2.12.4.5 How directories map into HFS data sets Once you have decided on your directory structure, you need to consider how you will map those directories into HFS data sets. A single directory must be contained in a single HFS data set. Subdirectories can be in the same data set, or can be in different data sets. You decide this by subdirectory, so some subdirectories could be in the same data set as the parent directory and some 37

Notes deployment using S/390 servers

could be in different data sets. Two directories can be in the same HFS data set only if their common parent directory and all directories in between are also in the same data set. It is possible to change the mapping of directories into HFS data sets later without affecting users, since they only use directory names to access the files. However, it will require an interruption to some users while directories are moved to new HFS data sets.
2.12.4.6 How HFS data sets are stored on S/390 DASD volumes Having decided on your HFS data set structure, you can then decide how you want to map the HFS data sets onto DASD volumes. You could take the approach that each volume will hold only one HFS data set that takes up all of the space. Then the administration of the space would be done in the UNIX environment, probably by the Notes administrator. Or you could choose to allocate many HFS data sets on a volume and use standard OS/390 facilities to manage them. You could, for example, put multiple HFS data sets on a DASD volume at first. If you define each HFS data set with secondary extents, it can expand as more space is needed, rather than getting an out-of-space failure.

Using standard OS/390 storage management tools, you can monitor the use of the data sets. When they expand to more than one extent, you can reorganize them. When the DASD volume becomes full, you can move some data sets to other volumes without affecting the Notes structure. This is standard OS/390 storage management; we describe it in Chapter 13, HFS data set management on page 269. You need to decide which approach you will take and do the appropriate monitoring on a regular basis.
2.12.4.7 HFS data set names Based on these considerations, our recommended name for the HFS data sets is shown in Figure 8.
hhhhh.DOMINO.servername.directory where: hhhhh DOMINO servername directory is a suitable OS/390 high level qualifier shows this is a Domino data set is name of the Domino server is the directory name, or PROD for the product code

Figure 8. Recommended name for HFS data sets

Notes:

1. On our system we use OMVS as the high-level qualifier to identify all UNIX System Services data sets on the system. You may find it useful to use different high-level qualifiers for different applications. For example, you may set up an SMS storage group to be owned by a particular application based on a high-level qualifier, such as NOTES. 2. The data sets are specific to a particular Domino server, and therefore we include the Domino server name in the data set name. 3. For manageability we recommend associating the HFS data set name with the HFS directory name. OS/390 data set names can be at most 44 characters in

38

Lotus Domino for S/390 R5 Installation, Customization and Administration

length, so you will have to use short directory names in order to maintain correlation to HFS data set names. Note also that OS/390 data set qualifiers cannot start with a numeric character and each qualifier is limited to 8 characters. 4. We do not include the OS/390 server name, because we could mount the HFS data sets on a different OS/390 system and start the Domino server on that system. 5. We do not include the Domino release level, since we would need to rename the data sets every time we upgrade the software. 6. In the examples in this redbook you will see a number of different HFS data set names that we tried. At one stage we used HFS as the final qualifier to denote an HFS data set. However, this is not required because we can identify HFS data sets from the DSNTYPE of HFS. SMS ACS routines. ISMF and utilities can use the DSNTYPE attribute.

2.12.5 Naming standards


In any Notes deployment it is important to decide on naming standards to make the system manageable. On a S/390 server many of the Notes naming standards are unchanged. Server names and domain names are consistent with other servers. However, there are some specific naming considerations on a S/390 server: A S/390 server typically runs many applications with many data sets and UNIX files. Each OS/390 operating system has only one UNIX hierarchical file system (which may be made up of many individual HFS data sets) that is shared between all UNIX applications on the server. The names of your HFS data sets and UNIX directories must therefore be consistent with those used by other applications. In addition, you will probably want to identify those OS/390 objects as being associated with the Domino server and part of the production workload on the S/390 server. A S/390 server could run many different Domino servers, using Domino partitioning or S/390 logical partitioning. In addition, multiple S/390 servers could share the same DASD, which is possible within a Parallel Sysplex. You could therefore have many Domino servers running in the same S/390 environment. To make this environment manageable, you need to choose the names of the OS/390 objects carefully. We recommend that HFS data set names should identify the Domino server that they belong to, and also perhaps the name of the OS/390 system that they are usually mounted on. Relate OS/390 names to corresponding Notes names wherever possible to make the management of resources easier.
2.12.5.1 Plan for change In designing your naming standard, it is important to think about the effect of changes that will occur:

User data (in particular: names, phone numbers, fax numbers, and reporting structure) changes on a regular basis. If your directory and HFS data set names include the user name, what is the effect of user name changes? What happens when a user moves to a new department?

Notes deployment using S/390 servers

39

New releases of the Notes server code will be installed. If your HFS data sets, Notes Dynamic LPA data set, or HFS directory names include the release number, these will all have to be changed with the upgrade. That would also involve changing all jobs, execs, and procedures that include these data set names. If your HFS data sets, Notes Dynamic LPA data set, or HFS directory names do not include the release number, you will need to consider a naming structure to support your fallback plan in the event of problems with the new release. Additional Domino servers may be added to the same OS/390 system. With the Domino Enterprise Server, partitioning multiple Domino servers can be configured to run in the same OS/390 system. These servers use the same execution libraries but need separate directories for their files. Directory names change, or directories are added. If your HFS data set names match the directory names, changing the directory name should invoke a change to the HFS data set name and any jobs that use it. Making the effort to keep these names in synch will simplify management.

2.13 Domino in a Parallel Sysplex


A Domino server will run in a S/390 Parallel Sysplex environment. If Domino is running in a Parallel Sysplex, you can use Parallel Sysplex facilities to enhance the performance and availability of your Domino server as follows: You can restart on an alternate OS/390 image using Virtual IP Addressing. You can have shared access to operational data. You can exploit channel-to-channel (CTC) connections through a coupling facility. Domino Release 5 does not exploit Parallel Sysplex features such as data sharing and workload balancing. To get high availability and workload balancing in a Parallel Sysplex, you would use Domino clustering as described in 11.4, Domino server clustering on page 200.

2.13.1 Restart on an alternate OS/390 image using Virtual IP Addressing


If the DASD used by the Domino server is connected to multiple OS/390 systems, then if there is an outage of the OS/390 system, the HFS data sets used for Notes could be mounted to a backup system (assuming it is running the same levels of software) and the server could be restarted. This would require: Processor resources to be available on the backup server Similar OS/390 parameter definitions on the backup server Domino modules loaded into Dynamic LPA on the backup server A shared RACF security database Shared DASD accessibility No conflicting HFS mount points An ability to start a Domino server on the backup server Setting up your TCP/IP network to redirect the TCP/IP traffic to the backup server
40
Lotus Domino for S/390 R5 Installation, Customization and Administration

This can be accomplished with gateway systems using Virtual IP Addressing (VIPA). VIPA is a feature of eNetwork Communication Server that enables IP routing to be sent to a backup OS/390 TCP/IP stack in the event of a failure.The purpose of VIPA is to free other hosts from dependence on particular physical network attachments to an OS/390 TCP/IP stack. See "Using VIPA to Backup or Restore an OS/390 TCP/IP Stack" in OS/390 eNetwork Communications Server, IP Configuration, Version 2 Release 6, SC31-8513. Cutover to the backup server would require mounting the HFS data sets on the backup server and then starting a Domino server there. With appropriate automation, the cutover time could be minimized, but users would lose their connection and would need to make a new connection when the backup Domino server is started. However, this approach avoids the Domino clustering overhead of duplicated data on multiple servers (which uses additional DASD) and the cluster replication data transfer.

2.13.2 Shared access to operational data


While Domino databases cannot be shared between OS/390 systems, many other databases can. Many organizations have their operational data and applications on S/390 servers and these applications support data sharing in a Parallel Sysplex. When Domino servers run in a Parallel Sysplex they can therefore access these applications and data directly, without needing to go through another S/390 server. Access to the data will be faster and more reliable.

2.13.3 Exploitation of CTC connections through a coupling facility


If you run multiple Domino servers, you need to provide network connections between them for replication and mail routing. If you implement Domino clustering, Lotus recommends that you use a separate network for the cluster replication traffic to provide good performance. If you have multiple Domino S/390 servers, you can provide the TCP/IP connections between them with: Network connections, such as a Token Ring, Ethernet or ATM Channel-to-channel connections A coupling facility, if the servers are in a Parallel Sysplex If you have a coupling facility, you may wish to use it to provide the connection between servers. It will provide a faster connection than a network connection.
2.13.3.1 Enabling TCP/IP communication through a CTC In our environment, the host-to-host TCP/IP connections were all originally defined to go through a Token Ring. We enabled a channel-to-channel connection between two of our OS/390 systems, SYS67 and SYS63, via the following steps:

1. We set up serial channel-to-channel connectivity between the two systems. The serial channel-to-channel (SCTC) addresses used were 4291 for SYS67 and 5231 for SYS63. 2. Two additional IP addresses were assigned: On SYS67 192.13.135.111 On SYS63 192.13.135.112
Notes deployment using S/390 servers

41

3. The following statements were added to the TCP/IP Profile definitions: On SYS67
DEVICE CTCD4291 LINK CTCL4291 CTC CTC 1 4291 CTCD4291

HOME 192.13.135.111 CTCL4291 GATEWAY ; Network First Hop Link Name Packet Size Subnet Mask 192.13.135.112 = CTCL4291 4096 HOST START CTCD4291

On SYS63
DEVICE CTCD5231 LINK CTCL5231 CTC CTC 0 5231 CTCD5231

HOME 192.13.135.112 CTCL5231 GATEWAY ; Network First Hop Link Name Packet Size Subnet Mask 192.13.135.111 = CTCL5231 4096 HOST START CTCD5231

4. TCP/IP was recycled on both systems. 5. The server connection documents in the Domino servers were edited to use the new IP addresses.

2.14 Migrating a host mail system to Domino on S/390


This section considers migration from a current host mail system to Domino on S/390. Organizations that run a host mail system on S/390 can migrate to the modern Notes architecture while continuing to get the benefits of the S/390 server platform. IBM, Lotus and their business partners have been working with customers for several years on migrations to Notes. They have developed products to help you migrate existing mail and calendar data to Domino and assist during the period of coexistence between the old and new systems. IBM Global Services, Lotus Consulting and business partners also offer a broad range of services to make your migration as smooth as possible.

2.14.1 Migration
Since you may be moving many users from your current system to Notes, it is important that you put together a detailed project plan and team to manage the migration. You need to consider issues such as: The new infrastructure required - servers, network and workstations User education Cutover methodology

42

Lotus Domino for S/390 R5 Installation, Customization and Administration

It is not the purpose of this book to detail all of the considerations. However, we discuss some migration tools that can help you.
2.14.1.1 Migration tools To assist you with migrations from other mail systems to Lotus Notes, Lotus has developed a migration architecture. There are two components to the migration architecture:

An extraction tool that is developed specifically for each source mail system. This tool extracts the data from the current system and places it in a standard file format. The Lotus Migration Engine that reads the standard file and loads the data into the Notes environment. Lotus provides a Domino Migration Engine Toolkit to assist business partners and customers to create a migration tool that meets their specific platform needs. Migration tools support the migration of groups of users at a time, and typically handle: Directory synchronization Inboxes Notelogs and folders Nickname files Personal distribution lists Calendar data We are aware of migration tools that are available or under development for the mail systems; see Table 3. This is not intended to be a complete list. Migration tools are also available for other non-host-based mail systems. For more information see:
http://www.lotus.com/home.nsf/welcome/supermove

Notes Migration Guide (available as a database, doc/migrate.nsf)


Table 3. Host office migration tools

From messaging system OV/MVS

Vendor

Comments

TBS Software Inc.

Batch process Extracts OV/MVS directory, mail, distribution lists, nicknames and calendar information for import into Domino Batch operation with high volume support Use of file transfer rather than the mail gateway Handles directory, mail, distribution lists, nickname lists and calendars Allows organizational units to be migrated separately

OV/VM

IBM/Lotus

MEMO

IBM/Lotus

Notes deployment using S/390 servers

43

From messaging system SYSM EMC2/TAO

Vendor

Comments

CompuSven TBS Software Inc and CompuSven Altis Consulting

DEC All-IN-One

2.14.1.2 OfficeVision support for Lotus Notes Clients IBM provides a migration tool that allows users to migrate to the Lotus Notes Clients, with its graphical user interface, and access their mail and calendar on OfficeVision, which acts as a server. Thus users gain many of the benefits of the Notes interface without needing to migrate their data. You can have Notes clients and 3270-type terminals accessing the same mail server. Users can also use this tool to migrate their own data from OfficeVision to Notes.

OfficeVision Support for Lotus Notes Clients (OVSLNC) supports OV/MVS, OV/VM and OV/400. It supports Lotus Notes Clients Release 4.1 and later, although you must have at least Release 4.5 for calendaring support. Figure 9 on page 45 shows how the support works: Mail from the client is delivered through OfficeVision. Mail is sent to OfficeVision user IDs. Mail is downloaded to the Notes client. OfficeVision notelogs can be downloaded to the Notes client on demand. Nicknames and distribution lists can be downloaded to the Notes client on demand. Calendars on the Notes Clients and on OV/VM are synchronized. Users can interchangeably access calendars and mail using either the graphical user interface of Notes Clients or the non-programmable terminal interface of OV/VM. When users wish to migrate to a Domino server, they change the Notes server documents from OfficeVision to Domino.

44

Lotus Domino for S/390 R5 Installation, Customization and Administration

O ffic e V is io n S u p p o r t f o r L o tu s N o te s C lie n ts

M a il

O ffic e V is io n
OV S u p p o rt

OV In -b a sk e t

N o te s C lie n t OV Support

L o c a l M a il D a ta B a se

O ffic e V is io n n o n p ro g r a m m a b le te r m in a l

Figure 9. OfficeVision support for Lotus Notes Clients

2.14.2 Coexistence
For large organizations, a migration from one mail system to Notes will take a period of time, possibly a year or more. The time scale depends on factors such as the type and complexity of the current mail system, the number of users, and the features that will be migrated. Therefore it is important that the new Notes system be able to coexist with the old one. Users on one system need to be able to communicate with users on the other system for both mail and calendaring functions. The communication mechanism must be able to handle heavy traffic during the major stages of the migration, and be sufficiently durable to support long term usage. IBM and Lotus have developed a number of tools that provide coexistence between a wide variety of messaging systems. With these in place migration to Domino can be performed on whatever schedule you require. We describe these products in the following sections. Many of them are available today, and most of them are being ported to OS/390 at the time of writing.
2.14.2.1 Lotus Domino POP3 Lotus Domino has built-in support for POP3 clients. 2.14.2.2 cc:Mail Message Transfer Agent The Lotus Domino cc:Mail Message Transfer Agent (MTA) provides interoperability between cc:Mail and Notes, transparently exchanging messages and directory information. 2.14.2.3 Lotus Calendar Connector for OfficeVision The Lotus Calendar Connector for OfficeVision allows users on different systems to share free and busy time information and schedule meetings. Domino,

Notes deployment using S/390 servers

45

Organizer'97 and TaP/2 clients can communicate with OV/MVS, OV/VM, PROFS and OV/400 systems.
2.14.2.4 Lotus Messaging Switch (LMS) Lotus Messaging Switch (LMS) is a message transfer switch that links heterogeneous messaging systems. It translates messages between a Notes environment and:

PROFS OfficeVision/MVS, OfficeVision/VM and OfficeVision/400 MEMO SYSM cc:Mail Microsoft Mail All-in-1 VMSmail Novell MHS X.400 Banyan Mail GroupWise Any SMTP-based mail system For more information see: http://www.lotus.com/products/softswitch.nsf
2.14.2.5 Lotus Soft-Switch Central Lotus Soft-Switch Central is an IBM host-based enterprise mail backbone switch, providing connectivity and management to dissimilar electronic mail systems. It runs on OS/390 and VM and provides:

Core gateways for X.400, SMTP, SNADS, PROFS and OfficeVision/VM SNAPI interface for Lotus Notes, cc:Mail, MHS, CA-eMail, MS Mail, mailFax, the Central LMS Connector (CLC) and other environments DIU Assembler/Disassembler (DAD) gateway, DEC All-In-1 and VMSmail, HP Desk Manager, Wang OFFICE, and H&W's SYSM For more information see: http://www.lotus.com/products/softswitch.nsf
2.14.2.6 IBM Mail LAN Gateway/2 (IMLG/2) The IBM Mail LAN Gateway/2 (IMLG/2) enables several popular LAN office electronic mail systems to communicate with other dissimilar LAN and host office electronic mail systems. It runs on OS/2 and provides connectivity support to:

Lotus Notes cc:Mail PROFS OfficeVision/VM OfficeVision/MVS using DISOSS

46

Lotus Domino for S/390 R5 Installation, Customization and Administration

IBM Mail Exchange OfficeVision/400 OfficePath/SNADS NETDATA files produced by the SENDFILE and NOTE commands of VM/CMS EMC2/TAO with the Fisher International SNADS Gateway. For more information see: http://www.lotus.com/products/softswitch.nsf

2.15 More information on deployment


Lotus Domino, The Power To Connect People - Easily, Securely, Reliably Lotus Domino S/390 Performance Tuning & Capacity Planning, SG24-5149 Lotus Notes Administrator's Guide, database links OS/390 eNetwork Communications Server, IP Configuration, Version 2 Release 6, SC31-8513

Notes deployment using S/390 servers

47

48

Lotus Domino for S/390 R5 Installation, Customization and Administration

Part 2. Installing the Domino Server

Copyright IBM Corp. 1999

49

50

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 3. Prerequisites
This part of the book discusses the tasks to install the Lotus Domino server on S/390. This chapter discusses the prerequisites to installing the Domino Server on S/390, including hardware, software and skills.

3.1 Hardware
This section documents the hardware requirements for installing and running the Lotus Domino Server on S/390.

3.1.1 Processor
You must have a S/390 processor that is capable of running IBM OS/390 Version 2 Release 6 or later. This could be a current production system, a logical partition (LPAR), or a standalone processor such as a P/390.

3.1.2 DASD space


Table 4 shows the minimum DASD space that is needed for the initial installation of the Domino server on S/390. In R5, the installation program checks for available space and will not let you proceed if there is not enough. This space is in three HFS data sets that must be on system-managed (SMS) DASD volumes. We recommend that you use DASD fast write caching for these volumes.
Table 4. Minimum disk space requirements

Data Type
Product files Notes control files, databases and templates Notes mail files

HFS Data Set Name


xxxx.PROD xxxx.DATA xxxx.MAIL

Directory Name
/usr/lpp/lotus /notesdata /notesdata/mail

Minimum Disk Space


510 MB (600 CYL) 425 MB (500 CYL) 50 MB (6 CYL)

These data sets are allocated with the supplied job ALOCPROD. The space allocations in the supplied job are larger than the values given in Table 4, since more space will be required once you begin to use the server. The amount of disk space you will use for Notes databases and mail files depends entirely on the size of your planned installation. We recommend that you size those requirements carefully and design your HFS data sets and directory structure accordingly.

3.1.3 Workstation
You need a workstation with a CD-ROM drive from which to do the installation. This must be connected to the S/390 server using TCP/IP. It can be a UNIX workstation or a PC.

3.2 Software
This section documents the software requirements for installing and running the Lotus Domino Server on S/390.

Copyright IBM Corp. 1999

51

3.2.1 OS/390 release level


OS/390 Version 2 Release 6 is the minimum operating system level required to run the Domino R5. This is documented in Lotus Domino for S/390 Install Guide for Servers . With Domino R5, an SMP/E service checker tool is available. This tool utilizes SMP/E to report on any prerequisite PTFs that may be missing from your system.
Note: It is important to note that this does not mean that Domino R5 is SMP/E installable.

You also have the option to review the list of prerequisite PTFs manually by getting the latest report from the Domino/390 Web site. Both the PTF checker and the report are available from:
http://www.s390.ibm.com/products/domino/

OS/390 integrates many former products into a single package, including the base MVS operating system, DFSMS/MVS, UNIX System Services, TCP/IP and TSO. To run the Domino server you must have: The OS/390 C/C++ IBM Open Class Library installed (no license for the C/C++ feature of OS/390 is required) High-level-qualifier.SCLBDLL in the program search order (for example, in the LINKLIST) Java Development Kit (JDK) 1.1.6
Note: Java for OS/390 is an optional product. It is orderable in SMP/E format through your normal IBM software ordering channels. It is also available on the Web at:
http://www.ibm.com/s390/java/

You only need to install JDK 1.1.6 if you will use HTTP, DIIOP or JAVA agents. We recommend that you install it because you may want to use these functions in the future, even if you do not have a requirement to use them now. These OS/390 publications will be helpful to you during installation: OS/390 Planning for Installation, GC28-1726 Program Directory for OS/390 OS/390 UNIX System Services Planning, SC28-1890

Parallel Sysplex The Lotus Domino Server can run in a standalone system or in a Parallel Sysplex. The only consideration is that if you are running in a Parallel Sysplex, we recommend that your HFS data sets be attached to only one system. It is technically possible to mount the HFS data sets as read-only (read/write is not allowed), but it is unlikely that there are many file systems that are opened as read-only. The Lotus Domino Server (R5) does not exploit Parallel Sysplex data sharing.

52

Lotus Domino for S/390 R5 Installation, Customization and Administration

Workload Manager You can run the Lotus Domino Server under either Workload Manager (goal mode) or under compatibility mode (using IEAICSxx/IEAIPSxx). The Lotus Domino Server Release R5 does not explicitly exploit Workload Manager. However, we recommend workload manager as the preferred environment for all OS/390 systems. Installing on a production or test system We expect that most people will install the Lotus Domino Server into a test system. If you prefer, it is possible to install the Lotus Domino Server directly into your production system. The Lotus Domino Server runs under OS/390 UNIX System Services, previously known as OpenEdition. You need to customize UNIX System Services before starting the server installation.
Unlike in previous releases of Domino/390, you must use UNIX Telnet or rlogin to run the interactive installation program. Running the installation program interactively through the TSO OMVS interface is not supported because the program requires the use of a TAB key. For a complete description of how to configure UNIX telnet and rlogin, refer to "Customizing for inetd and rlogin daemons"in OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization, SG24-5178.
Note: It is possible to run the installation script in the background by updating a file and then using that file as input to the installation script. If you choose this method, you do not have to configure UNIX telnet or rlogin.

If your background is in traditional MVS systems programming, the UNIX terminology may seem confusing. OS/390 UNIX System Services uses the UNIX structure and terminology. For those not familiar with UNIX, we provide guidance to help you with the tasks you need to do. Once the server is installed and running, most of the server administration can be done from the Notes administration client. The OS/390 ServerPac Installation Guide that comes with your ServerPac order has a step-by-step procedure for getting UNIX System Services installed and customized. The next chapter will also help you. The following publications are required during the installation: OS/390 UNIX System Services Planning, SC28-1890 OS/390 UNIX System Services User's Guide, SC28-1891 OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization , SG24-5178 OS/390 eNetwork Communications Server: IP Planning and Migration Guide, SC31-8512 Some things to consider: System Managed Storage (SMS) must be activated, and at least one DASD volume must be under SMS control, before you can activate OS/390 UNIX System Services. The UNIX hierarchical file system (HFS) data sets must reside on DASD volumes that are under SMS control. The Domino Server uses HFS data sets. OS/390 UNIX System Services requires a security program such as the OS/390 Security Server (Resource Access Control Facility (RACF)) or an
53

Prerequisites

equivalent. Any program or user requesting UNIX services needs to have a valid User Identification ID (UID) and a valid Group Identification ID (GID) before they can execute. The Domino server runs as one UNIX user, and therefore only requires one RACF user ID. Domino/390 R5 can create SMF 108 records. To enable the generation of these records, include SYS(TYPE(108) in the SMFPRMxx PARMLIB member. Also, the Domino Server userid must have READ access to the BPX.SMF Facility class. OS/390 UNIX Services comes with a POSIX-compliant shell that is analogous to the TSO environment. The shell provides a set of commands and utilities that give the user an efficient way to access files stored in the HFS. OS/390 supplies an ISPF interface to the UNIX shell. With the OS/390 ISPF interface, called the ISHELL, a user or Systems Programmer can use ISPF dialogs instead of shell commands to perform many tasks, especially those related to file systems and files. You can also run shell commands, REXX programs, and C/C++ programs from the ISHELL. If you are used to using ISPF dialogs with other products, you will also feel comfortable using the ISHELL. Refer to OS/390 UNIX System Services User's Guide, SC28-1891, for ISHELL usage tips.

3.2.2 TCP/IP
The Domino Server on OS/390 uses TCP/IP as the network protocol. The minimum level supported is OS/390 eNetwork Communications Server IP V2R6. To run the server, you need to have TCP/IP configured on OS/390, a workstation client configured with TCP/IP, and TCP/IP network connectivity between them. To establish a connection to the network for the Domino Server, both physical and logical connectivity must be established: The physical connection to the S/390 processor can be made using any of the following: The Open Systems Adapter (OSA) feature of the S/390 server A 37x5 communications controller An IBM 3172 Model 3 controller An IBM 2216 Nways Multiaccess Connector Some things to consider: There is no TCP/IP protocol stack imbedded in the UNIX environment to provide AF_INET (address family) socket support. The UNIX environment relies on OS/390 TCP/IP or equivalent to provide a TCP/IP protocol stack that allows UNIX socket programs such as the Domino Server to communicate with socket programs on other hosts (such as PCs) in your network. Before starting the Domino Server installation, you will need to have connectivity between your transport provider (OS/390 TCP/IP) and UNIX System Services. The message associated with a successful connection is:
EZZ4202I OPENEDITION-TCP/IP CONNECTION ESTABLISHED FOR TCPIPMVS

It is issued to the console log when this connectivity is established. For networking installation and customization information, see a listing publications and Web sites in Appendix I, Related publications on page 423.
54

Lotus Domino for S/390 R5 Installation, Customization and Administration

3.2.3 A Lotus Notes workstation client


The S/390 Domino server provides services to Notes clients running on other platforms. S/390 runs the Lotus Domino Server code only. It does not run a Lotus Notes workstation client. Therefore, you need to provide a Notes workstation client on another platform.
Note: The client is not needed during the installation process, but will be used to verify it by logging onto the newly installed server.

TCP/IP client code must be installed on client workstations. For a list of the platforms supported by Lotus Domino Server Release R5 and Notes Release R5, refer to 1.6, Available platforms on page 13.

3.3 Skills
To install and set up the Lotus Domino Server on OS/390, the following skills are required:
OS/390 systems programmer

An OS/390 systems programmer will customize the OS/390 server, which includes performing one or more of the following tasks: Installing OS/390 Customizing OS/390 UNIX System Services and TCP/IP Editing SYS1.PARMLIB Adding modules to Dynamic LPA OS/390 skills are also required for: Customizing SMS Defining RACF user IDs DASD management, including data set placement, data set backup, and DASD space monitoring Loading the install jobs onto the OS/390 system Running the install jobs Starting the server Since the Domino server uses OS/390 UNIX System Services, UNIX skills will be useful. However, we have documented the tasks in sufficient detail so that someone not familiar with UNIX will be able to complete the installation. We have also detailed alternative methods of doing tasks wherever possible, so that you will be able to select the method that best meets the skills available.
TCP/IP Networking Specialist

A TCP/IP networking specialist or networking team will define the TCP/IP network, install the necessary routers, and define the TCP/IP addresses to be used.
Notes Administrator

Prerequisites

55

A Notes administrator will design the Domino environment. He/she will run the server installation and configuration, or provide the parameters for someone else to do these tasks. Once server installation and configuration are complete and the server is running, he will add users and databases and manage the users, databases and servers. He will install and configure the Lotus Notes workstation clients. He will manage the security of the Notes environment and the connectivity between servers and workstations. This requires a high level of skill in the Domino/Notes products, and the person should be chosen and trained appropriately. Few people have all of these skills, so we recommend a team approach when installing the Lotus Domino server.
Note: In writing this redbook, one of our aims was to make it possible for an OS/390-skilled person to install the Lotus Domino Server on OS/390 and get it working. However, an experienced Notes administrator must design the Notes environment and take on the role of administrator in a production environment.

56

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 4. Prepare the OS/390 operating environment


Before you start the installation of the Lotus Domino Server you need to prepare the underlying OS/390 infrastructure. This chapter takes you through the following: The installation and customization of the UNIX environment on OS/390 Setting OS/390 parameters for the Domino Server Defining the RACF user IDs that you will use to run the Domino Server

4.1 Customize the OS/390 UNIX environment


The Domino Server uses OS/390 UNIX System Services, the OS/390 Hierarchical File System (HFS), and TCP/IP. Our experience suggests that once the required infrastructure is in place, the installation of the server is straightforward. However, this infrastructure may not be familiar to you. Therefore, we recommend that you use this chapter as a checklist to ensure that all of the preparation tasks are complete. We refer heavily to OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization , SG24-5178. This book is highly recommended as it contains numerous examples, step-by-step instructions and sample JCL.
Note: Throughout this book we sometimes refer to UNIX System Services as USS. This is not an official IBM acronym, however. UNIX System Services is the current name for what was previously known as OS/390 OpenEdition.

The columns in Table 5 on page 58 and Table 6 on page 60 are defined as follows:
Activity Description Skills

A single phrase describing the installation task. More details about the task. The skills needed by the person doing this task. We use the following abbreviations:
MVS MVSU Storage Security Network Domino

MVS System Programmer MVS System Programmer with some UNIX skills Storage Administrator Security/Systems Programmer Network Systems Programmer Lotus Notes/Domino Administrator

Reference

Reference documentation for each task. The reference to SG24-5178 refers to a section number in OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization , SG24-5178. UNIX SS Planning refers to UNIX System Services Planning, SC28-1890. Check this when the task is complete (yes).

All tasks are required except where noted otherwise.

Copyright IBM Corp. 1999

57

4.1.1 UNIX System Services customization


Table 5 shows some of the steps you need to perform.
Table 5. OS/390 and UNIX System Services installation tasks

Activity
Install OS/390 R6 or later

Description
This is the BCP and includes UNIX System Services. For example, FMIDs would be HBB6606, JBB6608 and HBB6608. For example, OS/390 Security Server (RACF).

Skills
MVS

Reference
Program Directory, ServerPac or SystemPac documentation Program Directory, ServerPac or SystemPac documentation Domino for S/390 Install Guide. See also: http://www1.s390.i bm.com/products/do mino/domptf.html SG24-5178, 3.4 "Configure and Activate SMS"

Prepare the Security Product

MVS

Apply PTFs

As required for Domino for S/390

MVS

Prepare SMS

If SMS is already enabled: - Customize ACS routines for HFS allocations (if not already done) - Activate the updated configuration If SMS is not enabled: - Initialize SMS volumes - Perform base setup of SMS - Set up ACS routines - Activate SMS environment

Storage

Complete the build of the UNIX System Services ROOT filesystem Set up security environment

In order to activate UNIX System Services in full function mode, the ROOT filesystem must be built and populated Set up/update RACF User, Group and Resource profiles for use with UNIX System Services.

MVS

Program Directory, ServerPac or SystemPac documentation SG24-5178, 3.6 "Prepare for UNIX System Services Security". See also the sample RACF security setup for UNIX System Services: SYS1.SAMPLIB(BPX ISEC1)

Security

58

Lotus Domino for S/390 R5 Installation, Customization and Administration

Activity
Customize UNIX System Services PARMLIB members

Description
Update IEASYMxx or IEASYSxx to point to new BPXPRMxx member. Set up BPXPRMxx parmlib member (main UNIX System Services parmlib member) to prepare for full function mode: - Alter parameters for Domino. - Set up TFS, UDS, INET, CINET (if using a multi-stack TCP/IP environment), AUTOMNT. - put /tmp in a TFS. Set up CTIBPXxx parmlib member (for tracing options). Customize VLF for additional RACF usage (for performance improvement). Customize ALLOCxx (re: allocation waits for forked address spaces). Customize IEADMRxx (re: SYSMDUMP) Others: PROGxx, SMFPRMxx. LPALSTxx, ERBRMFxx, IEFSSN(SMS), SCHEDxx, IECIOSxx, IGDSMSxx, IVTPRM00

Skills
MVS

Reference
SG24-5178 3.8, "Customize PARMLIB members"

UNIX SS Planning
Chapter 3

Domino for S/390 Install Guide

IPL

IPL system to start UNIX System Services in full function mode.

MVS

SG24-5178 Chapter 10, "IPL with UNIX System Services in Full-Function Mode" SG24-5178 4.6, "Customizing the OpenMVS ISPF Shell" SG24-5178, 4.9 "Customizing /etc/init.options or /etc/rc" SG24-5178, 4.11 "IPL the system to activate OS/390 UNIX System Services Application Services" SG24-5178, 4.12 "Installation Verification of UNIX System Services" SG24-5178, 4.13 "The terminfo database" SG24-5178, 4.15 "SMP/E install a C compiler" C/C++ Users Guide

Set up ISHELL

Add required data sets to TSO/E logon proc. Add entries on ISPF panels for ISHELL, OEDIT, OBROWSE Customize /etc/init.options. Customize /etc/rc. Customize /etc/profile. This is required to pick up changes in /etc/init.options, /etc/rc, /etc/profile.

MVS

Customize /etc files

MVS

IPL system to activate changes to UNIX System Services

MVS

Verify UNIX System Services installation

Verify shell, batch facilities, ISPF interface.

MVS

Set up TERMINFO database Install C/C++ compiler

Set up entries for various terminal types.

MVS

If you plan to develop or port applications, you will need a compiler. Follow appropriate documentation for compiler.

MVS

Note: This task is optional.

Prepare the OS/390 operating environment

59

Activity
Set up user file systems

Description
Allocate an HFS data set for each UNIX user. Set up automount facility (recommended). Setup $HOME/.profile. Note: This task is optional. Update WLM or IEAICSxx/IEAIPSxx for UNIX System Services tasks. Place HFS data sets on cached disk with DASD Fast Write (DFW). Note: This task is highly recommended.

Skills
MVS and Storage MVS

Reference
SG24-5178 Chapter 5, "Customizing UNIX System Services for general users" SG24-5178 Chapter 6, "Performance Considerations", http://www.s390.ib m.com/oe/bpxa1tun. html Lotus Domino S/390 Performance Tuning & Capacity Planning SG24-5149

UNIX System Services performance tuning

4.1.2 TCP/IP customization


If OS/390 eNetwork Communications Server TCP/IP has already been set up, you may only need to do some minor customization. For a complete description of this process, see OS/390 eNetwork Communication Server V2R7 TCP/IP Implementation Guide Volume 1: Configuration and Routing, SG24-5227.
Table 6. TCP/IP for MVS setup tasks

Activity
Set up an eNetwork Communications Server TCP/IP environment

Description
- Install and configure OS/390 eNetwork Communications Server IP. - Ensure IVTPRMxx parameters are sufficient for Domino. - Customize BPXPRMxx. If BPXPRMxx was updated in 4.1.1, UNIX System Services customization on page 58 with an INET entry, then you will already have done this and an IPL should not be necessary to allow TCP/IP-UNIX connectivity. You may, however, wish to run multiple TCP/IP stacks. You must then consider whether to use CINET instead.

Skills
MVS and Network

Reference
Program Directory, ServerPac or SystemPac documentation eNetwork Communicatoins Server IP Configuration SC31-8513 Domino for S/390 Install Guide

60

Lotus Domino for S/390 R5 Installation, Customization and Administration

Set up inetd, rlogin, Telnet and FTP.

- Set up /etc/inetd.conf and confirm setup in /etc/rc and /etc/services. - Set up JCL PROCs for inetd, ftpd. - Adjust port reservations for Telnet, FTP as required. - Start inetd and ftpd. -Test rlogin, Telnet and FTP.

MVSU

SG24-5178, 8.1.4 "Customizing for inetd and rlogin daemons"

Note: The interactive version of the Domino R5 installation program requires the use of a Telnet or rlogin session. You cannot use the TSO OMVS interface; therefore, this step is mandatory if you wish to run the installation program interactively. You can also run the installation program in the background using a script. If you choose this method, you do not have to set up inetd, rlogin or Telnet. Also, it is possible to transfer files to the host without using FTP.

4.1.2.1 Migration from previous releases of TCP/IP If you are migrating from previous releases of TCP/IP (TCP/IP for MVS or eNetwork Communications Server IP), we strongly recommend that you review the relevant Systems Center Flash: N3192 for OS/390 2.7, W98042 for OS/390 2.6. These flashes are a compendium of user and implementation errors that were encountered by early implementors of OS/390 TCP/IP. Note: The flashes are available through the Internet at:
www.ibm.com/support/techdocs/atscentr.nsf

4.1.2.2 FTP services in OS/390 As of OS/390 V2R5, the eNetwork Communications Server TCP/IP software has a single FTP server. Based on the syntax of the FTP client commands, a file can be transferred to or from either a traditional OS/390 data set or to an HFS.

The syntax for FTPD is: For an HFS data set: put file.extension /usr/lpp/lotus/file.extension. The file will be placed in the /usr/lpp/lotus directory. For an MVS data set: put filename.extension notesdata.test. The file will be placed in userid.notesdata.test. We found that sometimes we got end-of-line characters when FTPing to an MVS data set, which destroys the formatting of the file. The solution was to type cd 'mvs data set name (high level qualifier)' before issuing the put command. Also, make sure that the MVS data set LRECL (record length) is wide enough to support the file, otherwise the file will be truncated. In that case you need to preallocate an MVS data set with a longer record length before FTPing the file.
4.1.2.3 Telnet or rlogin requirements You must use UNIX telnet or rlogin to run the interactive version of the Domino R5 installation program. The TSO OMVS interface is not supported because it does not provide support for the TAB key, which is used extensively during the installation. To configure UNIX telnet or rlogin, refer to 8.1.4, "Customizing for inetd

Prepare the OS/390 operating environment

61

and rlogin daemons" in OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization, SG24-5178.
Note: You can also run the install program in the background using a script file. The decision whether to use the interactive or script version of the install program is up to the installer. We tested both methods. The script version may be more desirable because the input script file can be saved, edited and reused when installing additional servers. Be sure to assign a different RACF user ID for each server to run under.

4.2 Set OS/390 parameters for the Domino Server


Once you have installed the OS/390 and UNIX environments, there are specific customization steps required for Domino. See Domino for S/390 Install Guide for the latest information.
Note: For hints and tips on errors you might encounter while setting up Domino R5, see Appendix A, Troubleshooting and hints and tips on page 385.
Key Hint

We strongly recommend that you set the parameters exactly as specified in Domino for S/390 Install Guide. One of the biggest causes of problems during installation is that the recommendations were not followed. If some of the parameters are not set correctly, or all PTFs are not applied, the Domino Server may not start, and it may be difficult to diagnose the problem. You may save yourself a lot of time while installing the Domino Server for the first time by following the recommendations exactly. Once you have the server running, you can then go back and change parameters to other settings if needed. If you wish to understand the reasons for the parameter settings, we provide an explanation of how the Domino Server interfaces to OS/390 in Chapter 15, OS/390 parameter recommendations for Domino on page 311. Before changing any of the recommended values, use that chapter to help you understand what the implications may be.

4.2.1 System resources


If you will run Domino under OS/390 Workload Manager (also known as goal mode), make sure that it has an appropriate service definition. If you will run Domino using the OS/390 SRM tuning members, SYS1.PARMLIB(IEAIPSxx) and SYS1.PARMLIB(IEAICSxx), you should check your parameters to make sure that Domino will get enough resources. In particular: Domino uses more processor storage than many other applications, so make sure that the domain settings will allow it sufficient storage. Domino uses multiple address spaces, so make sure that the multiprogramming level (MPL) is not constrained. Allow at least 10 to start with, and see Chapter 15, OS/390 parameter recommendations for Domino on page 311.

62

Lotus Domino for S/390 R5 Installation, Customization and Administration

4.3 Make Domino Server tasks non-swappable


If you use RACF, you may improve performance by making some Domino Server tasks non-swappable. A new notes.ini variable called NONSWAP_SERVER_TASKS is available with Domino R5. Use of this notes.ini variable is intended to provide better performance for the server tasks that are specified in the notes.ini file. Making certain server tasks non-swappable allows them to perform better; also, the executables can be shared across Notes partitions. We currently recommend that router, replica, update, updall and server be designated as non-swappable. These have been tested in non-swap mode. In order to make a given Domino executable non-swappable, perform the following steps: RACF-permit the user who starts the server to the BPX.STOR.SWAP facility class. Put the executable and all the DLLs it references into an APF-authorized data set. At a minimum, this will require that the Libnotes DLL be included in an APF-authorized data set because all Domino executables reference Libnotes.
Note: One special consideration for Libnotes is that its size requires that it be placed in Dynamic LPA. Failure to put all DLLs referenced by the executable into an APF-authorized library will result in a DLL load failure. This will happen any time an APF-authorized executable tries to load a DLL that is not authorized.

To ensure that the modules reside in an APF-authorized data set, they must be placed in one of the following locations: Have a steplib in UNIX System Services that points to an APF-authorized data set (we strongly discourage this option). LNKLST and have the data set APF-authorized. Dynamic LPA (recommended). Turn on the sticky bits for the executable and all DLLs referenced. List all the executables to be marked non-swappable in the NONSWAP_SERVER_TASKS notes.ini variable or in the Notes_NONSWAP_SERVER_TASKS OS/390 environment variable (this should be placed in the Domino Server user IDs .profile file).
Note: You can use either the notes.ini variable NONSWAP_SERVER_TASKS, or the UNIX environment variable Notes_NONSWAP_SERVER_TASKS to set the tasks you want to make non-swappable. You should choose either one or the other. If you set both the notes.ini variable and the UNIX environment variable, the notes.ini variable will always take precedence.

The executables must all reside in the Domino install directory /usr/lpp/lotus/notes/latest/os390. All executable names should be separated by commas (for example: Notes_NONSWAP_SERVER_TASKS=router,replica).

Prepare the OS/390 operating environment

63

4.4 How to remove non-swappability for a task


Note: Note that the first step will disable swappability, but it may be desirable to perform all steps based on what the user wishes to accomplish.

Remove the name of the server tasks from the notes.ini variable NONSWAP_SERVER_TASKS or the UNIX environment variable Notes_NONSWAP_SERVER_TASKS, and restart the server (if using telnet or rlogin to restart the server, first logout then login). This is the minimum required to return an executable to a swappable state. Turn off the sticky bits for the executable and all associated DLLs. Failing to do so for all required parts could result in a DLL load failure because of authorization problems. Again, Libnotes is a special consideration. It must retain the sticky bit as long as any executable is marked non-swappable, since it is used by all Domino Servers and server tasks. Either remove the executable and all DLLs from the APF-authorized data set, or remove the data set from the APF parmlib member. This has implications for LPA in the case where these parts are being fetched from Dynamic LPA. Be careful not to remove a part from Dynamic LPA mistakenly when trying to remove APF authorization. Remove RACF permission to BPX.STOR.SWAP for the user starting the server. This step is probably the least necessary, since having the permission and not using it won't cause any problems. Note that performing this step without any of the others will cause the Domino code to issue non-swap failure messages.

4.5 Define user IDs to OS/390 Security Services (RACF)


The Domino Server provides its own high level of security so that it is not dependent on the security features of the platform on which it is running. We describe those features in Chapter 18, Security on page 371. The Domino Server does not use OS/390 Security Services (RACF) to provide its user security functions. However, as with all applications running on OS/390, the Domino Server is subject to the security constraints of OS/390 Security Services. In order to be able to install and run the Domino Server, it must have appropriate RACF authority within OS/390. In this chapter we consider the OS/390 security considerations: OS/390 UNIX security HFS file authorization Authorization of the user who will install Domino Server Authorization of the Domino Server when it runs Defining a user to RACF with UNIX authority

4.5.1 OS/390 UNIX security


In the OS/390 UNIX environment, as in other UNIX systems, every user on the system needs to be identified. For each user we define:

64

Lotus Domino for S/390 R5 Installation, Customization and Administration

User name Password (stored in encrypted form) User identifier (UID) Group identification numbers (GID) User's full name User's home directory File name of the shell program The UID is a number between 0 and 2147483647. If two users are assigned the same UID, UNIX System Services views them as the same user, even if they have different user names and passwords. Therefore, two users with the same UID could read and write over each other's files and thus kill each other's processes. You therefore need to be careful how you allocate UIDs. The OS/390 UNIX environment, as other UNIX systems, has the concept of groups. By using groups you can connect together many users who need to access a set of common files and directories. OS/390 UNIX Services uses the same concept of user accounts as other UNIX systems, but it stores the information in a segment (the OMVS segment) of a user profile in the RACF database. UNIX users are defined and managed with RACF commands.

4.5.2 HFS file authorization


The security information for each file in the OS/390 UNIX Hierarchical File System (HFS) is stored with the file. If we list the files in an HFS directory using the command ls -al, we will see information similar to that in Figure 10.

ls -al total 83152 -rw-r--r-drwx------rw-------rw-r--r--rw-r--r--rw-------rw-r--r-drwxr-xr-x -rw-r--r--rw-------rw-r--r--

1 2 1 1 1 1 1 2 1 1 1

MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6 MACFAD6

SYS1 SYS1 SYS1 SYS1 SYS1 SYS1 SYS1 SYS1 SYS1 SYS1 SYS1

144384 0 212992 1934848 98304 1687552 3602 0 748032 48 927744

Jul Jul Jul Jul Jul Jul Jul Jul Jul Jul Jul

21 18 21 21 21 21 21 14 21 21 21

01:01 11:54 14:58 01:01 01:00 14:57 14:58 09:54 01:00 14:58 01:01

log.ntf mail mail.box mail50.ntf mailbox.ntf names.nsf notes.ini noteslog perweb50.ntf pid.nbf pubnames.ntf

Figure 10. HFS file permission bits

The last field is the file name. The field MACFAD6 is the owner of the file and SYS1 is the default group to which MACFAD6 belongs. These are as defined in RACF, shown in Figure 11 on page 66. The first field is the file's permission bits. They define the access levels that people have to the file: Characters 2 to 4 define the access that the file owner has:
r

means that read access is allowed

Prepare the OS/390 operating environment

65

w x

means that write access is allowed means that execute access is allowed

Characters 5 to 7 define the access that anyone in the file owner's group has, in the same way as for the file owner. Characters 8 to 10 define the access that all other users have, in the same way as for the file owner. In Figure 12 on page 67, the file perweb50.ntf can only be written by the owner, but everyone on the system can read it.

USER=MACFAD6 NAME=MACFAD6/BRIAN MACFAD OWNER=HAIMO CREATED=97.154 DEFAULT-GROUP=SYS1 PASSDATE=97.188 PASS-INTERVAL=180 ATTRIBUTES=SPECIAL OPERATIONS GRPACC REVOKE DATE=NONE RESUME DATE=NONE LAST-ACCESS=97.202/14:42:39 CLASS AUTHORIZATIONS=NONE NO-INSTALLATION-DATA NO-MODEL-NAME LOGON ALLOWED (DAYS) (TIME) --------------------------------------------ANYDAY ANYTIME GROUP=SYS1 AUTH=JOIN CONNECT-OWNER=HAIMO CONNECT-DATE=97.1 CONNECTS= 321 UACC=ALTER LAST-CONNECT=97.202/14:42:39 CONNECT ATTRIBUTES=NONE REVOKE DATE=NONE RESUME DATE=NONE SECURITY-LEVEL=NONE SPECIFIED CATEGORY-AUTHORIZATION NONE SPECIFIED SECURITY-LABEL=NONE SPECIFIED OMVS INFORMATION ---------------UID= 0000000000 HOME= /u PROGRAM= /bin/sh
Figure 11. Output of a RACF LISTUSER command

4.5.3 Authorization of the user who will install Domino Server


The user ID that is used to install the Domino Server on OS/390 must be defined to RACF with a valid OMVS segment (a valid UID and GID) and must have a UID of 0 (superuser) to be able to mount the HFS data sets; see Figure 11. The user may either be defined with a permanent UID of 0 or be permitted read access to the BPX.SUPERUSER RACF FACILITY class, thus enabling the use of the su command.

4.5.4 Authorization of the Domino Server when it runs


The Domino Server runs as a user on OS/390. The user ID is the one that is used to start the server. This user ID must be defined to RACF with a valid OMVS segment (a valid UID and a valid GID). The user ID must have authority to access all of the Domino Server files on the HFS, including: The servers notes data directory All the files under the notes data directory The notes.ini file
66

Lotus Domino for S/390 R5 Installation, Customization and Administration

The /usr/lpp/lotus directory All the files in the /usr/lpp/lotus directory Write access to /tmp Read access to the BPX.STOR.SWAP RACF FACILITY class (if the installation has a requirement to run the server non-swappable). Read access to the BPX.SMF RACF FACILITY class (if you want the Domino Server to create SMF 108 records). Note: You will also need to update the SMFPRMxx PARMLIB member to include SYS(TYPE(108). We recommend that you do not run the Domino Server from a user ID with a UID of 0. The server runs agents on behalf of users, and it is possible that a user could therefore run an agent with superuser authority. You can change the owning user ID and group ID for a file by using the UNIX command chown. For example:
chown -Rf domino1:omvsgrp /domino1/notesdata

4.5.5 Defining a user to RACF with UNIX authority


This section shows how to define a RACF user ID with UNIX authority. The user IDs for installing and running the server both need UNIX System Services authorization. You can run a batch job to accomplish this or use ISPF. We show some of the ISPF screen panels that you may see. We define the user ID DOMINO1. When defining the user ID, you need to add OMVS information by placing an s as shown in Figure 12.
RACF - ADD USER DOMINO1 COMMAND ===> To ADD the following information, enter any character: _ _ _ _ _ _ CLASS AUTHORITY INSTALLATION DATA GROUP AUTHORITY SECURITY LEVEL or CATEGORIES SECURITY LABEL LOGON RESTRICTIONS

_ NATIONAL LANGUAGES _ _ _ _ _ S _ _ _ DFP PARAMETERS TSO PARAMETERS OPERPARM PARAMETERS CICS PARAMETERS WORK ATTRIBUTES OMVS PARAMETERS NETVIEW PARAMETERS DCE PARAMETERS OVM PARAMETERS

Figure 12. Adding OMVS parameters

6. You enter a user identifier as shown in Figure 13 on page 68. This is the UNIX UID. The user ID that installs the server must have a UID of 0 in order to be able to update the root directory. The user ID that runs the server should not have a UID of 0, to ensure that nothing running in the Domino Server can get

Prepare the OS/390 operating environment

67

superuser authority. The number you specify will depend on your installation. In the example shown in Figure 13, we give the user a UID of 2004.

RACF - ADD USER DOMINO1 1 of 3 OMVS PARAMETERS COMMAND ===>

Enter User Identifier (UID) below, then press ENTER: USER IDENTIFIER ===> 2004 0 - 2147483647

Figure 13. Setting the UNIX UID

7. You enter an initial directory path name for this user, as shown in Figure 14. This is the directory the user will be placed in when he first logs on. It is known as the HOME path.
Note: This directory must exist for the server to use UNIX services. Create this directory (from a superuser) using the command mkdir /u/domino1 (this assumes the /u directory exists). You should then change ownership of the directory to the Domino Server with the command:
chown -Rf domino1:omvsgrp /u/domino1

RACF - ADD USER DOMINO1 2 of 3 OMVS PARAMETERS COMMAND ===>

Enter Initial Directory Path Name (HOME), then press ENTER:

=> /u/domino1 => => => =>

Figure 14. Setting the user's initial directory

8. Enter a program path name for this user, as shown in Figure 15 on page 69. This should always be /bin/sh - the shell program.

68

Lotus Domino for S/390 R5 Installation, Customization and Administration

RACF - ADD USER DOMINO1 3 of 3 OMVS PARAMETERS COMMAND ===>

Enter Program Path Name (PROGRAM), then press ENTER:

=> /bin/sh => => => =>

Figure 15. Setting the program path name

If we now display the RACF information for this user, we will see Figure 16. Remember to request that the OMVS information be displayed.

USER=DOMINO1 NAME=DOMINO SERVER OWNER=OHKUBO CREATED=97.134 DEFAULT-GROUP=OMVSGRP PASSDATE=97.134 PASS-INTERVAL=180 ATTRIBUTES=NONE REVOKE DATE=NONE RESUME DATE=NONE LAST-ACCESS=97.134/09:49:16 CLASS AUTHORIZATIONS=NONE NO-INSTALLATION-DATA NO-MODEL-NAME LOGON ALLOWED (DAYS) (TIME) --------------------------------------------ANYDAY ANYTIME GROUP=OMVSGRP AUTH=USE CONNECT-OWNER=OHKUBO CONNECT-DATE=97.134 CONNECTS= 08 UACC=NONE LAST-CONNECT=97.134/09:49:16 CONNECT ATTRIBUTES=NONE REVOKE DATE=NONE RESUME DATE=NONE SECURITY-LEVEL=NONE SPECIFIED CATEGORY-AUTHORIZATION NONE SPECIFIED SECURITY-LABEL=NONE SPECIFIED OMVS INFORMATION ---------------UID= 0000002004 HOME= /u/domino1 PROGRAM= /bin/sh
Figure 16. Displaying a RACF user ID

Prepare the OS/390 operating environment

69

70

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 5. Prepare to install the Domino Server


As stated in the Domino for S/390 Install Guide, the Domino R5 install process differs from previous installs. Do not install the product without following the instructions in the Domino for S/390 Install Guide .
Note: If you are upgrading from an older level of the Domino Server, refer to Chapter 12, Upgrading the Domino Server on page 231 before continuing with this chapter.

Once you have completed customization of OS/390, you are ready to install the Domino Server. As discussed in 3.2.1, OS/390 release level on page 52, in Domino R5 a prerequisite SMP/E service checker tool has been added. This tool utilizes SMP/E to report any prerequisite PTFs that may be missing from your system.
Note: It is important to note that although an SMP/E prerequisite PTF checker program is now supported, this does not mean that Domino R5 is SMP/E installable.

You also have the option to review the list of prerequisite PTFs manually by getting the latest report from the Domino/390 Web site. Both the PTF checker and the report are available from:
http://www.s390.ibm.com/products/domino/

Make sure that you have installed all the required PTFs. Unlike previous releases of Domino, where there was a single setup program, R5 introduces a new method of installation. We have broken this down into three distinct stages. This chapter discusses the first stage of the installation of the Domino Server on the S/390 server. These tasks will typically be done by an OS/390 system programmer and others familiar with OS/390. The second stage of the installation process will be discussed in Chapter 6, Installing a Domino Server on page 85. The third and final stage of the installation process is discussed in Chapter 8, Preparing Dynamic LPA on page 119.

5.1 Task checklist


Table 7 shows the tasks we cover in this chapter. You can check them off as you complete them.
Table 7. Domino Server installation tasks

Task
Collect the information you will need Review the documentation

Check When Completed

Copyright IBM Corp. 1999

71

Task
Upload the installation files to an OS/390 PDS data set Allocate HFS data sets and Dynamic LPA PDSE (ALOCPROD) Modify BPXPRMxx to mount the Domino HFS data sets at IPL time (MDYFBPXP) Load the server code into the HFS Untar the server code

Check When Completed

5.2 Collect the information you will need


To install the Domino Server on OS/390, you need to know some information about your system. You may use Table 8 to record it.
Table 8. OS/390 System Information

Description
Active IEASYSxx member(s) Active COMMNDxx member(s) Active BPXPRMxx member(s) RACF user ID for installing the server RACF user IDs/groups for running the servers Storage Class for HFS data sets VOLSER for HFS data sets VOLSER for Dynamic LPA data set OS/390 TCP/IP host name UNIX System Services TCP/IP port number for Telnet

See note
1 1 1 2 3 4 5 5 6

Value

Notes:

1. Document here which members of SYS1.PARMLIB you will use after installing the Domino Server. These may be the same as the ones you are currently using, or they may be new members that you will set up. 2. To install the Domino Server, you need a RACF user ID that can update SYS1.PARMLIB. The user ID also needs to be able to add new directories to the root HFS directory, which requires a UNIX superuser with a UID of 0. See 4.5, Define user IDs to OS/390 Security Services (RACF) on page 64 for how to set up such a user ID.
Note: This should not be the same user ID as that used to start the Domino Server.

3. The Lotus Domino Server runs with a RACF user ID. We recommend that this user ID not have a UID of 0. The user ID needs to be able to access the HFS data sets that are used by the server. Record the RACF user and RACF group

72

Lotus Domino for S/390 R5 Installation, Customization and Administration

for this user ID. See 4.5, Define user IDs to OS/390 Security Services (RACF) on page 64.
Note: If you are installing multiple servers (partitioned Domino Servers), then we recommend that you give each server an individual user ID and UID number. The user IDs may or may not belong to the same RACF group depending on whether or not you wish to further limit a servers access to another servers files.

4. HFS data sets must be system-managed by SMS. Record here the SMS storage class that you will use to allocate these data sets. Make sure that there is sufficient DASD space available in the storage group that will be used. 5. You can specify a specific volser for the HFS data sets and dynamic LPA data set if you wish. SMS may or may not override your selection, depending on installation definitions for guaranteed space. 6. Record the TCP/IP host name of your OS/390 server. Note: If you are running on a system with multiple TCP/IP stacks, you will need to choose just one of the host names. You need to ensure that the chosen TCP/IP stack has access to UNIX System Services (see 3.2.2, TCP/IP on page 54 for more details). If you will Telnet into UNIX System Services to start the server, then you need to know the UNIX System Services TCP/IP port number for Telnet. You can locate it by using the ISPF command ISHELL to look at the HFS file (/etc/services). Look for the line with otelnet and record the number next to it (such as 2023), which designates the port number. If you do not find this line, you should add a line such as: otelnet 2023/tcp. Any line that starts with a semicolon (;) is a comment line.

5.3 Review the documentation


Lotus Domino 5.0 is distributed on a CD-ROM, which contains: Two JCL and two PARMLIB files to help you install the product. A UNIX tar file (similar to a PC zip file) that contains all of the server code.
Note: The tar file name is different when installing one of the non-English language versions of Domino. Instead of S3905000.TAR, the file name will be S3905000_xxxxxxxx.tar, where xxxxxxxx will be French, Spanish etc.

A README.TXT file that contains the latest installation information. Two Notes databases that contain installation and release information. The file Apps/Nvagents/R5/os390/nva50.tar, which contains the Domino Management Agents for the S/390 product image. The first task is to review the documentation provided on the CD-ROM, as it will be more recent than this document. Look at the following files:
README.TXT READMES.NSF

This contains the latest information on the contents of the CD-ROM, including documentation updates and restrictions.

Domino S/390 5.0 Release Notes. This database includes the section Things you need to know, which you should read carefully for the release you are installing.

Prepare to install the Domino Server

73

SRVS390.NSF

Domino S/390 5.0 Install Guide. Read all of this database, which includes information on setting up your OS/390 system and installing Domino for S/390.

To read the two Notes databases, copy them to the \notes\data directory (or a subdirectory of it) on a Notes client and then open them. Alternatively, you could upload them in binary to an existing Domino Server and access them from there.
Note: Also check the Domino for S/390 home page on the World Wide Web for the latest information, at URL:
http://www.s390.ibm.com/products/domino

5.4 Upload the installation files to OS/390


In this step we upload the JCL, PARMLIB and tar files to the S/390 server.
Note: Prior to OS/390 V2R5 (with eNetwork Communications Server V2R5), there were two independent FTP servers available on the OS/390 platform. One FTP server was used for file transfer of UNIX HFS files. The other FTP server was for traditional MVS data sets. There is now a single FTP server that handles both types of data.

We recommend that you upload the tar file directly into the Hierarchical File System (HFS). If you wish to do this, then: Do not upload the tar file in this step. Instead, refer to 5.6, Load the server code into the HFS on page 82, which explains how to upload the tar file at the appropriate time. In this section we describe two ways to upload the files from the CD-ROM to traditional OS/390 data sets: Using FTP Using a PC 3270 emulation program tool such as IND$FILE (Send/Receive). Choose the method you are most familiar with. However, FTP will transfer data faster than IND$FILE.

5.4.1 Allocate two OS/390 data sets


Use TSO to allocate two OS/390 data sets to receive the data from the CD-ROM: Allocate a partitioned data set (PDS) to store the JCL and PARMLIB files. Give it a record format of FB and a record length of 80 bytes. One megabyte of space and 5 directory blocks should be sufficient. In our examples, this data set has the name SIMONWIL.DOM500.JCL. If you will upload the tar file into an OS/390 data set, allocate a sequential file with a record format of VB, a record length of 255 bytes, a block size of 23476 and space of at least 140 MB. In our examples this data set has the name SIMONWIL.S3905000.TAR.

5.4.2 Upload the files using FTP


The four files can be uploaded from your workstation to OS/390 using FTP.

74

Lotus Domino for S/390 R5 Installation, Customization and Administration

After placing the CD-ROM in your CD-ROM drive, type the commands in Figure 17 on page 76 on your workstation from a command prompt.
Note: FTP commands and files are case-sensitive. Check the file names on the CD carefully if you are using a UNIX workstation. Note: If you want to have the two Notes documentation databases on the server, you can upload them now. The file names are:

READMES.NSF SRVS390.NSF

Prepare to install the Domino Server

75

*** For PC *** e: <= switch to CD-ROM drive *** For UNIX workstation (the syntax may be different on your UNIX) *** /usr/sbin/mount -r -v cdrfs /dev/devname cdrom <= Mount CD-ROM on device 'devname' at mount point 'cdrom' cd /cdrom/unix <= Switch to CD-ROM directory 'cdrom' is the mount point 'unix' is the CD path

*** For both types of workstation ***

dir

<= Check contents of the CD ROM

The volume label in drive E is CAPICD_R1. The Volume Serial Number is 2367:000A. Directory of E:\ . .. ALOCPROD MDFYBPXP MDFYPROG PUTINLPA README READMES S3905000 SRVS390 <DIR> 09-15-98 1:59p <DIR> 09-15-98 1:59p 500 11,120 09-15-98 12:39p 500 2,320 09-15-98 12:39p 500 2,080 09-15-98 12:39p 500 14,000 09-15-98 12:39p TXT 3,136 09-15-98 12:39p NSF 2,220,952 09-15-98 12:40p TAR 62,531,300 09-15-98 1:24p NSF 640,811 09-15-98 1:27p 8 file(s) 65,425,719 bytes . .. ALOCPROD.500 MDFYBPXP.500 MDFYPROG.500 PUTINLPA.500 README.TXT READMES.NSF S3905000.TAR SRVS390.NSF

FTP wtsc54

<= wtsc54 is the TCP name of our OS/390 server You can use a TCP/IP address instead <= A valid MVS user ID. No special authority is required. <= For the MVS user ID <= You should see this prompt <= switch to binary mode 'SIMONWIL.DOM500.JCL(ALOCPROD)' 'SIMONWIL.DOM500.JCL(MDFYBPXP)' 'SIMONWIL.DOM500.JCL(MDFYPROG)' 'SIMONWIL.DOM500.JCL(PUTINLPA)'

<userid>

<password> FTP> binary put put put put ALOCPROD.500 MDFYBPXP.500 MDFYPROG.500 PUTINLPA.500

put S3905000.TAR 'SIMONWIL.S3905000.TAR' bye < disconnect from FTP

Figure 17. Commands to FTP the installation files to the OS/390 server

76

Lotus Domino for S/390 R5 Installation, Customization and Administration

5.4.3 Upload the files using IND$FILE (Send/Receive)


The files can be uploaded from your PC to OS/390 using the PC file transfer program IND$FILE (also known as Send/Receive). This program sends PC files to MVS data sets through the TSO interface. The steps are: 1. Place the CD-ROM in your CD-ROM drive. 2. Send the two JCL files and the two PARMLIB files to OS/390 as binary files. Put them into the partitioned data set you allocated earlier. 3. Send the tar file to OS/390 as a binary file. Send it to the sequential data set you allocated earlier.
Note: The send command is much slower than FTP. On our system, send took approximately 30 minutes to upload the tar file, while FTP took less than five minutes. However, you will only upload the tar file once for each new release, so this should not be a problem.

5.4.4 Check the files


Check that the JCL data set (SIMONWIL.DOM500.JCL in our example) contains these four members, and that they are readable: ALOCPROD MDFYBPXP MDFYPROG PUTINLPA
Note: If the files are unreadable or the lines appear wrapped, make sure you uploaded the files in binary mode.

5.4.5 Allocate HFS data sets (ALOCPROD)


You now run the ALOCPROD JCL to allocate three HFS data sets, create three directories in the hierarchical file system, and do a temporary mount of the HFS data sets to these directories. ALOCPROD also allocates a partitioned data set extended (PDSE) data set that we will use for loading modules into the dynamic link pack area (DLPA). These data sets and directory names are shown in Table 9.
Table 9. Data sets created by ALOCPROD

Default MVS Data Set Name


NOTES.PROD.HFS NOTES.DATA.HFS NOTES.MAIL.HFS SYS2.LOTUS.LPAPDSE

HFS Mount Point


/usr/lpp/lotus /notesdata /notesdata/mail

Data Set Contents


Product directories Data directories Mail directories Dynamic LPA data set (PDSE)

Minimum Size
510 MB 425 MB 50 MB 85 MB

Figure 18 on page 78 and Figure 19 on page 79 show the ALOCPROD job shipped with the Domino R5 server. After these figures, we have included some notes on running the job.

Prepare to install the Domino Server

77

//ALOCPROD JOB <JOB CARD PARAMETERS> //********************************************************************* //* * //* This JCL will allocate install PDSE, and HFS data sets for * //* product DOMINO SERVER for S/390 Release 5.0 * //* * //* This JOB must be run from a USERID that has a UID(0). * //* It will set appropriate directories for HFS files. * //* * //* You must set CAPS OFF for this JCL member * //* * //* CAUTION: THIS IS NEITHER A JCL PROCEDURE NOR A COMPLETE JOB. * //* Before using this job step, you will have to make the following * //* modifications: * //* * //* 1) CHANGE THE JOB CARD TO MEET YOUR SYSTEM REQUIREMENTS * //* 2) CHANGE hhh TO THE DOMINO HFS DATA SET HIGH LEVEL QUALIFIER * //* ("NOTES" IS THE DEFAULT.) * //* CHANGE IN BOTH STEPS "ALOCATE" AND "MOUNTHFS" * //* IF YOU CHOOSE TO USE A MIDDLE LEVEL QUALIFIER, YOU SHOULD * //* CHANGE hhh TO "NOTES.MMM". * //* 3) CHANGE fff TO THE DOMINO DYNAMIC LPA PDS/E DATA SET HIGH LEVEL* //* QUALIFIER ("SYS2" IS THE DEFAULT) * //* IF YOU CHOOSE TO USE A MIDDLE LEVEL QUALIFIER, YOU SHOULD * //* CHANGE fff TO "SYS2.MMM". * //* 4) CHANGE sss TO THE SMS STORAGE CLASS USED FOR NOTES * //* ("NOTES" IS THE DEFAULT) * //* 5) CHANGE THE VOLSER'S TO MEET YOUR SYSTEM REQUIREMENTS * //* CHANGE ttttt1 TO THE VOLSER FOR THE HFS DATA SETS (TVOL1) * //* CHANGE ttttt2 TO THE VOLSER FOR the DYNAMIC LPA PDS/E (TVOL2) * //* DATA SET * //* 6) CHANGE THE VALUE OF fdisp TO THE APPROPRIATE FINAL DISPOSITION* //* OF THE DATASET ("CATLG" IS THE DEFAULT) ON THE EXEC STEPS. * //* 7) CHANGE THREE MOUNT COMMANDS' FILESYSTEM OPTION TO MATCH HFS * //* DATA SETS DEFINED IN JOB STEP ALLOCATE. * //* NOTE: DO NOT CHANGE THE MOUNT COMMANDS' MOUNTPOINT OPTION. * //* * //* NOTES: * //* * //* 1. THIS JOB SHOULD COMPLETE WITH A RETURN CODE 0. * //* * //* 2. PDS/E AND HFS DATA SETS MUST RESIDE ON SMS MANAGED VOLUMES. * //* * //* 3. YOU SHOULD MONITOR THE /notesdata DIRECTORY DURING PRODUCTION * //* USE. * //* * //* 4. YOU WILL NEED TO UPDATE SYSn.PARMLIB(BPXPRMxx) MEMBER FOR * //* A PERMANENT MOUNTS. * //********************************************************************* //* //*********************************************************** //* ALLOCATE TARGET LIBRARIES * //*********************************************************** //* //DOMINO PROC DSNPREF='NOTES', * NOTES DS HLQ // DLPAPREF='SYS2', * DYN LPA DS HLQ // NOTESTO='NOTES', * STORAGE CLASS // TVOL1='HVOL01', * HFS VOL // TVOL2='LVOL01', * PDSE VOL // DSP='CATLG' * DISP

Figure 18. ALOCPROD JCL supplied with Domino R5 (screen 1 of 4)

78

Lotus Domino for S/390 R5 Installation, Customization and Administration

//* //DOMALOC EXEC PGM=IEFBR14 //* //NOTEPROD DD DSN=&DSNPREF..PROD.HFS,VOL=SER=&TVOL1, // DCB=(DSORG=PO),UNIT=SYSALLDA, // STORCLAS=&NOTESTO,DSNTYPE=HFS, // DISP=(NEW,&DSP,DELETE), // SPACE=(CYL,(600,50)) //* //NOTEDATA DD DSN=&DSNPREF..DATA.HFS,VOL=SER=&TVOL1, // DCB=(DSORG=PO),UNIT=SYSALLDA, // STORCLAS=&NOTESTO,DSNTYPE=HFS, // DISP=(NEW,&DSP,DELETE), // SPACE=(CYL,(500,1)) //* //MAIL0001 DD DSN=&DSNPREF..MAIL.HFS,VOL=SER=&TVOL1, // DCB=(DSORG=PO),UNIT=SYSALLDA, // STORCLAS=&NOTESTO,DSNTYPE=HFS, // DISP=(NEW,&DSP,DELETE), // SPACE=(CYL,(500,1)) //* //NOTEDLPA DD DSN=&DLPAPREF..LOTUS.LPAPDSE, // DISP=(NEW,&DSP,DELETE),UNIT=SYSALLDA, // DCB=(DSORG=PO,RECFM=U,LRECL=0,BLKSIZE=4096), // SPACE=(CYL,(65,1)),VOL=SER=&TVOL2, // STORCLAS=&NOTESTO,DSNTYPE=LIBRARY //* //EALLOC PEND //* //*********************************************************** //* JOB STEP: ALLOCATE * ///ALOCATE EXEC DOMINO, // DSNPREF=hhh, * NOTES IS THE DEFAULT // DLPAPREF=fff, * SYS2 IS THE DEFAULT // NOTESTO=sss, * NOTES IS THE DEFAULT // TVOL1=ttttt1, * NO DEFAULT; VOLUME1 FOR HFS // TVOL2=ttttt2, * NO DEFAULT; VOLUME2 FOR LPA PDSE // DSP=fdisp * CATLG IS THE DEFAULT //***************************************************** //* JOB STEP: MOUNTHFS * //***************************************************** //MOUNTHFS EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * MKDIR '/usr/lpp/lotus' MODE(7,5,5) MOUNT FILESYSTEM('hhh.PROD.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/usr/lpp/lotus') bpxbatch SH chmod 755 /usr/lpp/lotus MKDIR '/notesdata' MODE(7,5,5) MOUNT FILESYSTEM('hhh.DATA.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/notesdata') bpxbatch SH chmod 755 /notesdata MKDIR '/notesdata/mail' MODE(7,5,5) MOUNT FILESYSTEM('hhh.MAIL.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/notesdata/mail') bpxbatch SH chmod 755 /notesdata/mail /*
Figure 19. ALOCPROD JCL supplied with Domino R5 (screen 2 of 4)

Prepare to install the Domino Server

79

Notes:

1. See Table 8 on page 72 for the values that you may use to change the job to match your installation. 2. This job requires a user ID with OS/390 UNIX superuser authority (UID=0) because it creates a new file system off the root directory. 3. You need to modify the jobcard for your installation. 4. If you are running in a Parallel Sysplex, add a JOBPARM card such as /*JOBPARM SYSAFF=SC67 to route the job to the system where you want the HFS data sets mounted. That is the system where you will install the Notes server. HFS files can only be mounted to one system at a time. They cannot be shared between OS/390 systems. 5. If you are running OS/390 V2R6 with DFSMS 1.4, the HFS data sets cannot span DASD volumes. Therefore, as the amount of data grows, your directory structure may need to change. Consider this in your initial data set naming. Multi-volume HFS support is available with DFSMS 1.5, with a single data set being able to span up to 59 volumes. 6. DSNPREF is the high level qualifier used for the Notes HFS data sets. You may wish to change this to match your installations standards. Note that if you do so, you must also change the data set names on the mount commands later in the job. We provide recommendations for data set names in 2.12.4.7, HFS data set names on page 38. 7. DLPAPREF is the high-level qualifier used for a PDSE that will be used to store the Domino Server modules that will be included in dynamic LPA. 8. NOTESTO must be set to a valid SMS Storage Class on your system. HFS data sets must be system-managed. 9. TVOL1 is the volume specification for the HFS data sets. It can be used to place the data sets on specific SMS-managed volumes if you are authorized to do that. Otherwise it will be ignored. We recommend that you place the HFS data sets on cached DASD for good performance. 10.TVOL2 is the volume specification for the Dynamic LPA PDSE data set. Since PDSEs reside on SMS-managed volumes, TVOL2 will be ignored unless you are authorized to place data sets on specific volumes with the guaranteed space attribute. 11.Store the MKDIR commands in a separate file for future reference. See 13.1.2, Creating a mount point on page 269. 12.Check the space allocations for the HFS data sets carefully. For a production system you may need much more space, so plan for the likely growth. 13.You can change the directory names if you wish. 14.This job mounts the HFS data sets. However, these mounts are lost if you re-IPL. The next step makes the mounts automatic at IPL time. 15.If you get an error in the second step of the job, the error codes are listed in OS/390 UNIX System Services Messages and Codes, SC28-1908.

80

Lotus Domino for S/390 R5 Installation, Customization and Administration

5.5 Use MDFYBPXP to mount the HFS data sets at IPL time
When you re-IPL the system, the mounts you did in the ALOCPROD job will be lost. You need to make sure that the mount commands are issued every time the system is re-IPLed. The Domino S/390 5.0 Install Guide directs you to copy the mount statements from the MDFYBPXP file into SYS1.PARMLIB(BPXPRMxx). The mount statements will then be processed at IPL time. The MDFYBPXP file shipped with the Domino R5 server is shown in Figure 20 on page 81. You need to ensure that the data set and directory names match those you used when you ran ALOCPROD.

/********************************************************************/ /* */ /* Sample MOUNT commands that go into SYS1.PARMLIB(BPXPRMxx) */ /* For product DOMINO SERVER for S/390 Release 5.0 */ /* */ /* CAUTION: THIS IS NEITHER A JCL PROCEDURE NOR A COMPLETE JOB. */ /* Before using this sample, you will have to make the following */ /* modifications: */ /* */ /* 1. CHANGE "hhh" TO THE DOMINO HFS DATA SET HIGH LEVEL QUALIFIER */ /* ("NOTES" IS THE DEFAULT.) */ /* IF YOU CHOOSE TO USE A MIDDLE LEVEL QUALIFIER, YOU SHOULD */ /* CHANGE "hhh" TO "NOTES.MMM". */ /* THE HFS DATA SETS MUST MATCH THE NAMES PREVIOUSLY ALLOCATED */ /* VIA THE SAMPLE JCL ALLOPROD. */ /* */ /* 2. INTEGRATE THESE 3 MOUNT COMMANDS TO SYS1.PARMLIB(BPXPRMxx) */ /* */ /********************************************************************/ MOUNT FILESYSTEM('hhh.PROD.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/usr/lpp/lotus') MOUNT FILESYSTEM('hhh.DATA.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/notesdata') MOUNT FILESYSTEM('hhh.MAIL.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/notesdata/mail')

Figure 20. MDFYBPXP JCL supplied with Domino R5

If you are running in a Parallel Sysplex, this is not the best method. Each HFS data set can only be mounted on one system (mounting the same HFS data set on multiple systems in read/write mode is not supported). You would therefore have to use a different BPXPRMxx member for each OS/390 system (which is something you may wish to avoid, for simpler management). On our system, we issued the mount commands from a procedure in SYS1.PROCLIB instead. For the way we implemented this, see 13.1.3, Mounting the HFS data sets on page 270.

Prepare to install the Domino Server

81

5.6 Load the server code into the HFS


This step will load the server code tar file into the OS/390 UNIX HFS. You should do this step if you chose to upload the tar file to a sequential data set in 5.4, Upload the installation files to OS/390 on page 74.
Note: We recommend that you use the HFS directory name /usr/lpp/lotus when installing the server code. If you install the code in a different directory, you will need to modify later instructions and shell scripts.

5.6.1 Copy the tar file into HFS


If you have already uploaded the tar file to an OS/390 data set, then copy the file into the HFS as shown in Figure 21. Start from a TSO prompt and press the Enter key after each command.

omvs <enter>

<= To enter the UNIX System Services UNIX environment

cd /usr/lpp/lotus tso oput 'userid.S3905000.TAR' <enter> <= MVS data set name '/usr/lpp/lotus/S3905000.TAR' binary <= Path name. Note the binary option
Figure 21. Copying the tar file into HFS

You can use the command exit to exit from OMVS; however, you will need OMVS in the next step.

5.6.2 FTP the tar file into HFS


If you did not upload the tar file to an OS/390 data set, then now is the time to upload it from the CD-ROM into the HFS using FTP. This method requires that the FTP server that is part of eNetwork Communications Server IP V2R6 (or later) has been customized and is running. Use the commands in Figure 22 on page 83. Make sure that you perform the transfer in binary mode.

82

Lotus Domino for S/390 R5 Installation, Customization and Administration

*** For PC *** e: <= switch to CD-ROM drive *** For UNIX workstation (the syntax may be different on your UNIX) *** /usr/sbin/mount -r -v cdrfs /dev/devname cdrom <= Mount CD-ROM on device 'devname' at mount point 'cdrom' cd /cdrom/unix <= Switch to CD-ROM directory 'cdrom' is the mount point 'unix' is the CD path

*** For both types of workstation ***

dir

<= Check contents of the CD ROM

The volume label in drive E is CAPICD_R1. The Volume Serial Number is 2367:000A. Directory of E:\ . .. ALOCPROD MDFYBPXP MDFYPROG PUTINLPA README READMES S3905000 SRVS390 <DIR> 09-15-98 1:59p <DIR> 09-15-98 1:59p 500 11,120 09-15-98 12:39p 500 2,320 09-15-98 12:39p 500 2,080 09-15-98 12:39p 500 14,000 09-15-98 12:39p TXT 3,136 09-15-98 12:39p NSF 2,220,952 09-15-98 12:40p TAR 62,531,300 09-15-98 1:24p NSF 640,811 09-15-98 1:27p 8 file(s) 65,425,719 bytes . .. ALOCPROD.500 MDFYBPXP.500 MDFYPROG.500 PUTINLPA.500 README.TXT READMES.NSF S3905000.TAR SRVS390.NSF

FTP wtsc54

<= wtsc54 is the TCP name of our OS/390 server You can use a TCP/IP address instead <= A valid MVS user ID. No special authority is required. <= For the MVS user ID <= You should see this prompt <= switch to binary mode

<userid>

<password> FTP> binary

put S3905000.TAR /usr/lpp/lotus/S3905000.TAR bye < disconnect from FTP

Figure 22. Uploading the tar file into the HFS

5.7 Untar the server code


Now that the tar file is in the HFS, you need to untar it to put the product code into the proper files and directories. First you need to log on to the OS/390 UNIX environment. You can do that in one of two ways:

Prepare to install the Domino Server

83

You can use a TSO screen. At a TSO READY prompt or ISPF option 6 (ISPF Command Shell), type OMVS to enter the UNIX System Services shell. The screen may go into input mode a number of times (the word INPUT will appear in the bottom right corner). Press PF10 to refresh the screen. You can rlogin or Telnet into UNIX System Services, using the TCP/IP hostname or IP address (include the port number if the service is not listening on its well-known port). After logging in, issue the commands in Figure 23, pressing the Enter key after each one.

cd /usr/lpp/lotus tar -xvozf S3905000.TAR


Figure 23. Untar the tar file

<= Go to directory with tar file <= Untar the file

After you successfully untar the file, you can delete it and thereby save 140 MB of space in the HFS. The files take over 400 MB of space when you untar them. The untar will take several minutes (depending on the size of your machine and its workload).
Note: In earlier Domino releases, you would run a job at this point to put the modules into the LPA library. With R5, you can do that step later. All modules are now loaded into the dynamic LPA, which we cover in Chapter 8, Preparing Dynamic LPA on page 119.

84

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 6. Installing a Domino Server


Note: Use this chapter in conjunction with the regular product documentation, which is more up-to-date.

In previous releases of Domino for S/390, a single installation program, os390setup, was run to install and configure the Domino Server. With Domino R5 this has changed: the installation and configuration are now two separate steps. The installation step uses a program called install, much like os390setup. It can be run interactively through the UNIX shell or in the background using an editable shell script as input. The configuration step is done using Dominos HTTP server and a Web browser. This chapter describes how to run the Domino Server installation program. Chapter 7, Configuring a Domino Server on page 101 describes the configuration steps. These tasks will typically be done by a Notes administrator with some help from an OS/390 systems programmer. You can run the installation program either interactively or using a script that you first modify with an editor. When you run the install program interactively, you are prompted for all the installation settings necessary to install the Domino Server.
Note: The install program includes online help, which you can access by typing h on any screen.

The process of building a Domino Server on S/390 is the same as on any other platform. However, the way in which we run that process is different from most platforms, with the exception of UNIX. Most non-UNIX server platforms also run the Notes client. To run server installation on those platforms, you start the Notes client, which then detects that server installation has not been run and guides you through the required parameters using a graphical user interface. S/390 does not have a Notes client, so we run server installation by executing a UNIX shell script called install. This script can be run interactively or in the background. Configuration of the Domino Server is then done through a Web browser. The screens displayed on the browser are very similar to those displayed on a Notes client.
Note: If you encounter errors when starting your system, check Appendix A, Troubleshooting and hints and tips on page 385.

6.1 NLS considerations


Before running the installation program, the UNIX language environment variable must be set to C (LANG=C) and then exported. The installation program can only be run in this locale. If you are going to run in a different locale, after the installation program completes, run the DomLANG script (/usr/lpp/lotus/bin/tools/DomLANG). DomLANG must be run from a UID=0 user.

Copyright IBM Corp. 1999

85

For example: DomLANG Ja_JP IBM-939 sets the locale for Japanese. You must then reset the language environment variable to the desired locale. For example: export LANG=Ja_JP. See Domino S/390 5.0 Install Guide and Domino S/390 5.0 Release Notes for more information about National Language Support (NLS).

6.2 Task Checklist


Table 10 shows the tasks that we cover in this chapter. You can check them off as you complete them.
Table 10. Domino Server installation and configuration tasks

Task
Document server installation information Register the server in the domains Domino Directory (do this only if you are creating an additional server in an existing domain); refer to 16.2.4, Registering a Domino Server on page 348. Run the installation program Document server configuration information Run the configuration program Download important files

Check When Completed

6.3 Description of Domino Server installation and configuration


This section discusses some terms that you need to know to run the installation and configuration programs. This section also describes what the server installation and configuration programs do, and explains the differences between setting up a first and an additional server.

6.3.1 Domino Server terms


To understand more about the information you need for the installation and configuration programs, familiarize yourself with the following Domino terms:
Domino Server ID Each Domino Server has a unique name that is maintained in its own ID file. If you are creating the first server in a new domain, Domino creates the server ID automatically during the server configuration program. If you are creating an additional server in an existing domain, then you will supply this ID file as part of the configuration program. Notes user ID Each Notes user has a unique name that is maintained in its own ID file. Domino creates the user ID automatically when you register new users. Certifier ID An organization has an organization certifier ID that is stored in a file named cert.id. This certifier automatically certifies (authorizes) the first server's ID and the administrator's ID. When you register new users or servers, you use the 86

Lotus Domino for S/390 R5 Installation, Customization and Administration

certifier ID to give access to the organizations resources. You also use the organization certifier ID when you create organizational unit certifiers for a hierarchical naming scheme. Domino creates the organization certifier ID automatically during the first server configuration using the name you specify and an optional password. You can only add a country code if your countrys clearinghouse for X.500 names has approved your organizations certifier ID. Doing this minimizes the chance that another organization has the same name as yours. A multinational organization requires only one certifier ID, even if a country code is specified; it is not necessary to have separate certifier IDs for each country in which Domino is deployed.
Domain A domain is a group of Domino Servers that share the same Domino Directory. Domino Directory Each domain has a Domino Directory. The Domino Directory is the control and administration center for Domino Servers in the domain. It contains a Server document for each server and a Person document for each user. In addition, you can create Group documents to establish relationships among servers and users for mailing and security purposes, and create Connection documents to schedule replication and mail routing among servers.

For more information, see Administering the Domino System .

6.3.2 Domino Server installation program


The server installation program install asks whether you want to install a Domino Mail Server, Application Server or Enterprise Server. The installation program: 1. Installs the Domino program files, usually to directory /usr/lpp/lotus. 2. Copies the databases and templates into the notes data directory that you have specified. 3. Creates the Notes configuration file notes.ini.
Note: If you rerun the install program after you have completed the entire installation process (after running the PUTINLPA job discussed in Chapter 8, Preparing Dynamic LPA on page 119), you will rebuild /usr/lpp/lotus, thereby overwriting its current contents (including permission bits). Since the PUTINLPA job sets the sticky bits on for the server executable modules, these sticky bits will effectively be turned off by rerunning the install program. Our recommendation is: if you rerun the install program, rerun the entire three-part installation process (installation, configuration, put in LPA).

6.3.3 Domino Server configuration program


The server configuration asks different questions, depending on whether you are creating: The first server in the domain An additional server in an existing domain

Installing a Domino Server

87

6.3.3.1 First server in a domain If you are creating the first Domino Server in a new domain, the domain will be created on the server being set up and an organization certifier ID file and the Domino Directory will be created. Note: Only choose this option when you are setting up Domino for the first time in your organization or when you are creating a new domain.

For a first server, the configuration program does the following: Creates a new domain for the Domino Servers. Enables the appropriate network ports. Creates the Domino Directory for the domain. The configuration program uses the PUBNAMES.NTF template to create the Domino Directory in the same directory as the installers specified Notes data directory and is given the default name names.nsf. Creates a certifier ID for your organization. The server configuration program saves the certifier ID in the specified Notes data directory, and gives it the default name cert.id. Creates a Certifier document in the Domino Directory. This document describes the certifier ID. Creates a server ID for the new server. The configuration program creates the server ID in the specified /notesdata directory and gives it the default name server.id. Certifies the server ID with the organization certifier ID. Creates a Server document in the Domino Directory. This document describes this server based on information that you specify during configuration. Creates a Person document in the Domino Directory for the Domino administrator specified during configuration. Creates a user ID and a password for the Domino administrator and attaches them as a file named UserId to the administrators Person document in the Domino Directory. Certifies the administrators user ID with the organization certifier ID. Adds the administrators name and the servers name as managers in the access control list (ACL) of the Domino Directory. Creates a mail directory in the Domino data directory and a mail file in that directory for the Domino administrator.
6.3.3.2 Additional server in an existing domain If you are creating an additional server in an already existing domain, information such as the Domino Directory (Public Address Book) and certifier ID file will be used from an existing server in the domain.

For the configuration of an additional server, the tasks are somewhat different: 1. First you must register the new server in the Domino Directory of the domain that you are adding it to. This is described in 16.2.4, Registering a Domino Server on page 348. This step will be done by a Notes administrator.

88

Lotus Domino for S/390 R5 Installation, Customization and Administration

2. Run the configuration program. The information that you provide to the configuration program is similar to that for a first server, but there are differences. For the configuration of an additional server in an existing domain, the configuration program does the following: Enables the appropriate network ports. Connects to the registration server and checks if the server is registered. Creates a replica copy of the Domino Directory in the specified Notes data directory and gives it the name names.nsf. Creates a mail directory in the data directory and a mail file for the Domino administrator.

6.4 Server installation information


This section documents the information that you will need to run the installation program. You will find it helpful to document your environment before running the installation program. Table 11 lists the information requested by the install program.
Table 11. Information required to run the install program

Information Requested by install Program


Setup type Pathname for the Domino program files RACF user ID for Notes data directory RACF group ID for Notes data directory Run partitioned servers? Number of data directories Pathname for data directories

See Note
1 2 3 3 4 5 6

Your Value

Notes:

1. You can choose whether to install a Domino Mail Server, Domino Application Server or Domino Enterprise Server. See 1.4, Lotus Domino R5 family of servers and clients on page 10 for more details on which server type you should choose. 2. Create a directory in an OS/390 UNIX HFS for the Domino Server program files. The default directory is /usr/lpp/lotus, which is created by the ALOCPROD job. 3. Document the owning RACF user ID and its associated RACF group name for the Notes data directory. You must use the user ID and group name that will run the Domino Server, as listed in Table 11. The user ID and group name are set up by the RACF security administrator.
Note: If you are installing multiple servers, all files will be owned by the single user ID. After the installation and configuration steps have been completed, it

Installing a Domino Server

89

is recommended that you perform a chown command on the individual Notes data directories to change the ownership as required. 4. You can run more than one Domino Server on a single computer. This feature is called Domino Partitioned Servers and requires separate Notes data directories for each Domino Server. You should decide whether or not you wish to run more than one copy of the server on the same OS/390 image. 5. If you are going to run multiple Domino Servers, you need to specify the number of data directories (there is a one-to-one relationship between data directory and Domino Server). 6. With multiple servers, you need to give each server a pathname for the data directory. We used the convention of /server_name/notesdata.

6.5 Running the installation program


You should have the information gathered in 6.4, Server installation information on page 89 available before you start the install program. The installation program can be run either interactively or in the background with a script that you edit. We will first discuss the interactive version, and then examine the script method of installation. Use the following procedure to start and run the Domino for S/390 install program interactively: 1. Login to the OS/390 UNIX environment with a RACF user ID that has UID=0. You must login using rlogin or Telnet.
Note: Running install from the OMVS shell is not supported. The program will not start or the screen may lock up in input mode from time to time. See 4.1.2.3, Telnet or rlogin requirements on page 61 for details.

2. Type: /usr/lpp/lotus/os390/install 3. You will now be prompted for the information needed to install the server, as identified in Table 11 on page 89.

6.5.1 Interactive installation


1. The first screen you will see is Figure 24 on page 91. Press Tab to continue.

90

Lotus Domino for S/390 R5 Installation, Customization and Administration

=============================================================================== Domino Server Installation ===============================================================================

Welcome to the Domino Server Install Program.

Type h for help on how to use this program. Press TAB to begin the installation.

------------------------------------------------------------------------------Type h for help Type e to exit installation Press TAB to continue to the next screen. ------------------------------------------------------------------------------Figure 24. Installation introduction screen

2. In order to proceed with the installation you must first read and accept the Lotus Domino/Notes Software Agreement.

=============================================================================== Domino Server Installation ===============================================================================

In order to proceed with the installation of the Domino Server, you must read and agree with the terms and conditions of the Lotus Domino/Notes Software Agreement. Press TAB to read the Lotus Domino/Notes Software Agreement.

------------------------------------------------------------------------------Type e to exit the Install program. Press ESC to return to the previous screen Press TAB to continue to the next screen. ------------------------------------------------------------------------------Figure 25. Introduction to License Agreement

Figure 26 on page 92 is the first screen of the license agreement. Figure 27 on page 92 shows the final screen of the License Agreement.

Installing a Domino Server

91

.
=============================================================================== Domino Server Installation =============================================================================== IF YOU DO NOT AGREE WITH THESE TERMS AND CONDITIONS, DO NOT INSTALL THE SOFTWARE AND RETURN THIS ENTIRE PACKAGE WITHIN 30 DAYS OF SALE WITH YOUR RECEIPT FOR A FULL REFUND. 1. USE You (an entity or a person) may use the following Lotus software products (individually and collectively, the Software), in the quantity purchased, if you meet the following conditions. In addition you may make one (1) archival copy of the Software. (a) Lotus Notes for Collaboration You must acquire one copy of the Software for each unique Notes User ID that is issued. The Software may also be installed on a home and/or laptop computer, but only the authorized user may access the Software. You are not required to acquire additional copies of the Software when you create Lotus Notes IDs for scheduling applications such as Lotus Organizer. Your license to the Software includes a Domino Per User Client Access License (CAL) and access to all Notes mail templates, but it does not include access to design and administration features. Please refer to the Installation Guide accompanying the Software for other information regarding its use.
Figure 26. First screen of License Agreement

For Canadian customers: Should you have any questions concerning this Agreement or Lotus software use policies, write to Customer Service, Lotus Development Canada Limited, P.O. Box 679, Scarborough, Ontario M1K 5C5, or call 1-800-465-6887. For Latin American customers: Should you have any questions concerning this Agreement or Lotus software use policies, call or write your local sales office. For customers in all other countries: Please call or write your local Lotus sales office. Press the Escape key to go back to the previous screen or Press the Tab key to continue...
Figure 27. Final screen of License Agreement

=============================================================================== Domino Server Installation ===============================================================================

You may proceed with the installation only if you agree to the terms and conditions of the Lotus Domino/Notes Software Agreement.

------------------------------------------------------------------------------Type e to exit the Install program. Press ESC to return to the previous screen. Press the Spacebar to change the setting until you get the one you want. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------>>> Do you agree to the terms of the license agreement ? [Yes]
Figure 28. Select Yes to agree to the terms of the License Agreement

92

Lotus Domino for S/390 R5 Installation, Customization and Administration

3. Select the type of server you wish to install. The options are Domino Mail Server, Domino Application Server and Domino Enterprise Server. In our example we chose to install the Domino Enterprise Server. See 1.4, Lotus Domino R5 family of servers and clients on page 10 for a description of each server type.

=============================================================================== Domino Server Installation ===============================================================================

Select the type of installation you want.

------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press the Spacebar to change the setting until you get the one you want. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------>>> Select Setup type : [Domino Enterprise Server ]
Figure 29. Choose which type of server you want to install

4. Figure 30 requests that you give a directory path for the installation of the Domino Server code. The installation program ALOCPROD (see 5.4.5, Allocate HFS data sets (ALOCPROD) on page 77) uses /usr/lpp/lotus, so we use this in our examples.

=============================================================================== Domino Server Installation ===============================================================================

The program directory is the path where the Install program installs the Domino program files. The Install program automatically adds "lotus" to the path.

------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press ENTER to edit a setting. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------Current program directory setting : /usr/lpp/lotus
Figure 30. Set the directory path for Domino Server code

5. After the screen shown in Figure 31 on page 94 you will be prompted for the RACF user ID and RACF group of the user that will own the installed Domino files. Typically this should be the Domino Server user ID. Note that in installations where multiple servers are installed (details follow), the script is limited to giving ownership of all Notes data directories to a single user. You may need to use the UNIX chown command to change ownership of some of the notes data directories.
Installing a Domino Server

93

=============================================================================== Domino Server Installation ===============================================================================

You will now be prompted for information on how to install one or more Domino Data Directories. Please note that the UNIX user and group names asked for will own all of the data directories specified. The system will own the program files.

------------------------------------------------------------------------------Type e to exit the Install program. Press ESC to return to the previous screen Press TAB to continue to the next screen. ------------------------------------------------------------------------------Figure 31. Introduction screen to setting up Domino Data Directories

6. Figure 32 on page 94 asks whether you wish to run more than one Domino Server on the same OS/390 image (an image is another term for instance of an operating system). Running multiple copies of Domino on the same system is known as Domino partitioning. In our example we have chosen to run multiple servers on a single OS/390 image.

=============================================================================== Domino Server Installation ===============================================================================

You can run more than one Domino Server on a single computer at a time. This feature is called Domino Partitioned Servers, and requires separate Data Directories for each Domino Server to be run.

------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press the Spacebar to change the setting until you get the one you want. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------>>> Do you want to run more than one Domino Server on this computer ? [No ]
Figure 32. Single or partitioned server

7. Figure 33 on page 95 asks for the number of data directories you wish to create. Each Domino Server requires its own data directory. In our example we wish to create 3 servers so we select 3 data directories.

94

Lotus Domino for S/390 R5 Installation, Customization and Administration

. =============================================================================== Domino Server Installation ===============================================================================

Each Domino Partitioned Server requires its own data directory. How many Domino Partitioned Server data directories would you like to install ?

------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press ENTER to edit a setting. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------Number of data directories current setting : 3
Figure 33. Specify the number of data directories you wish to create

8. Figure 34 on page 95 asks you to enter the name of the notes data directory you wish to create. We have chosen the convention of /server_name/notesdata . You may wish to create your own naming convention. You will be prompted for a pathname for as many servers as youve specified you want to run.

=============================================================================== Domino Server Installation ===============================================================================

Enter the pathname for data directory 1 of 3.

------------------------------------------------------------------------------Press ENTER to retain the current setting or Type a new setting and press ENTER. ------------------------------------------------------------------------------Current path : /notesdata New path : /domino1/notesdata

Figure 34. Specify the pathname for the notes data directory

9. Figure 35 on page 96 asks you to enter a valid RACF user ID to become the owner of this Domino Server. The user ID must have a valid OMVS segment (with a non-zero UID) and be connected to a RACF group that has a valid OMVS Group ID (GID).

Installing a Domino Server

95

=============================================================================== Domino Server Installation ===============================================================================

Please enter the Domino UNIX user to own the data directory: /domino1/notesdata NOTE for the 4.x upgrade installer: Domino UNIX user name/account name you specify here must be the same as the existing 4.x installed data files for proper working of Domino.

------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press ENTER to edit a setting. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------Current UNIX user setting : domino1
Figure 35. Enter a RACF userid to own the Domino data files

10.Figure 36 asks you to enter the RACF group name that the RACF user ID in the previous screen is connected to. This RACF group must have a valid GID.

=============================================================================== Domino Server Installation =============================================================================== Please enter the Domino UNIX group to own the data directory: /domino1/notesdata This UNIX user for this directory must be a member of this group. NOTE for the 4.x upgrade installer: Domino UNIX group/account group you specify here must be the same as the existing 4.x installed data files for proper working of Domino. ------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press ENTER to edit a setting. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------Current UNIX group setting : oedomino
Figure 36. Enter the RACF group that the userid is connected to

11.Continue installing each server. Figure 37 on page 97 tells you that the tailoring of the Install program is completed. The next screen will show you the settings that you have selected. Review them before starting the installation.

96

Lotus Domino for S/390 R5 Installation, Customization and Administration

=============================================================================== Domino Server Installation ===============================================================================

Your configuration of the Install program is complete. By continuing, the Install program will first allow you to review your configuration settings before beginning the installation.

------------------------------------------------------------------------------Type e to exit the Install program. Press ESC to return to the previous screen Press TAB to continue to the next screen. ----------------------------------------------------------------------------Figure 37. Configuration of the Install program is now complete

12.You can now review the settings that youve made during the running of the install program. If you are satisfied with the settings, press Tab to begin the installation process. The installation process will take several minutes, depending on the size of your machine, system load and the number of Domino Servers you are building.

=============================================================================== Domino Server Installation =============================================================================== Installation settings: Installation type : Domino Enterprise Server

Program directory : /usr/lpp/lotus Data directories : /domino1/notesdata UNIX user : domino1 UNIX group : oedomino /domino2/notesdata domino2 oedomino domino3/notesdata domino3 oedomino Press the Escape key to re-configure the settings or Press the Tab key to perform the installation...
Figure 38. Review the settings you have made before continuing

13.Once the installation has completed, you will see the following screen:

Installing a Domino Server

97

=============================================================================== Domino Server Installation =============================================================================== Installation settings: Installation type Program directory Data directories : Domino Enterprise Server : /usr/lpp/lotus : /domino1/notesdata /domino2/notesdata /domino3/notesdata : domino1 : oedomino

UNIX user name UNIX group name

Validating... Installing... The installation completed successfully. Please be sure to login as the appropriate UNIX user before running Domino - Do not run as root.
Figure 39. Completion of the install program.

6.5.2 Running the install program using the script


Intead of running the installation interactively, as we have shown, you might decide to edit the supplied installation script and let it run in batch. This has advantages if you will be performing the install more than once, for instance if you will install multiple servers. Here are the steps to use the script 1. Login to the OS/390 UNIX environment with the RACF user ID used for the installation. This must have a UID=0. You can login using rlogin, UNIX Telnet or the TSO OMVS interface.
Note: When running the install program using the script file, you are not prompted interactively for information. Therefore, you can use the TSO OMVS interface if you choose this method of server installation.

2. Switch to the directory that contains the install program and the script. Assuming you have not changed the recommended settings, the directory will be /usr/lpp/lotus/os390/. 3. Make a copy of the script file (os390_script.dat). For example:
cp os390_script.dat itso_install_script.dat

4. Using OEDIT or vi, edit the copied script file. For a comprehensive description of each parameter in the script, refer to the comments in the script file. 5. After you have finished making changes to the script file, invoke the install program with the script file as a parameter. For example:
/usr/lpp/lotus/os390/install -script itso_install_script.dat

The installation process will take several minutes, depending on the size of your machine, system load and the number of Domino Servers you are building. 6. After the install program has finished, you will be presented with a screen like Figure 40 on page 99.

98

Lotus Domino for S/390 R5 Installation, Customization and Administration

Lotus Notes for UNIX Install Program -----------------------------------Thu Jun 10 12:18:46 EDT 1999 Batch mode script file is: /usr/lpp/lotus/os390/sew_script.dat

Installation settings: Installation type Program directory Data directory UNIX user name UNIX group name : Domino Enterprise Server : : : : /usr/lpp/lotus /domb/notesdata domb oedomino

Validating... Installing... The installation completed successfully. Please be sure to login as the appropriate UNIX user before running Domino - Do not run as root.

Figure 40. Completed install program (script mode)

This completes the installation of your Domino Server. Continue with the following activities.

6.6 Verifying path statements


Before continuing with the configuration process, you must ensure that a number of path environment variables are set correctly for the Domino Server user ID you specified during the running of the install program. To set environment variables for a UNIX user you must edit the .profile file that is in the HOME directory. To verify that .profile exists, go to the users home directory (check the HOME parameter in the OMVS segment if you are unsure of which directory that is). Type ls -al to check whether .profile exists. If it does not, you will need to create one using an editor such as vi or OEDIT. For more information on .profile, see OS/390 UNIX System Services Users Guide, SC28-1891. The PATH and LIBPATH environment variables must contain the location of the native_threads subdirectory of the Java Development Kit (JDK). The CLASSPATH environment variable must include the classes.zip subdirectory.

PATH=$PATH:/usr/lpp/Java/J1.1/lib/mvs/native_threads:/usr/lpp/lotus/bin:/usr/lpp/lotus/bin/tools: LIBPATH=$LIBPATH:/usr/lpp/Java/J1.1/lib/mvs/native_threads CLASSPATH=$CLASSPATH:/usr/lpp/Java/J1.1/lib/classes.zip export PATH LIBPATH CLASSPATH export Notes_SHARED_DPOOLSIZE=8388608


Figure 41. Sample .profile

Installing a Domino Server

99

Note: The path statements are installation dependent. The Java path is necessary only if you require Java support (however, most systems do).

After completing this step, you are ready to configure the new Domino Servers using the Domino HTTP server task and a Web browser.

100

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 7. Configuring a Domino Server


This chapter describes the steps you will need to configure a server. You will find it helpful to document your environment before running the configuration program. Table 12 shows the information requested by the configuration program if you are configuring the first server in a new domain. For the notes, see 7.1, Setting up the first Domino Server in a domain on page 102.
Table 12. Information for the first server in a new domain

Information requested by configuration program for first Domino Server


Screen 1 of 4 (Create a new Domino Server)
Is this the first or additional Domino server ?

See note

Your value

First

Screen 2 of 4 (Server audience)


Additional Services Web Browsers Internet Mail Packages Internet Directory Services News Readers Enterprise Connection Services 2 3 4 5 6 7

Screen 3 of 4 (Administration settings)


Domain Name Certifier Name Certifier Country Code Certifier ID Certifier Password Server Name Servers Hostname Server ID Administrators First Name Administrators Middle Initial Administrators Last Name Administrators ID Administrators Password Local Time Zone 8 9 10 11 12 13 14 15 16 16 16 17 18 19

Copyright IBM Corp. 1999

101

Information requested by configuration program for first Domino Server


Daylight Savings

See note
19

Your value

Screen 4 of 4 (Network and communications settings)


Ports Serial Port Modem 20 21 22

7.1 Setting up the first Domino Server in a domain


Here are the notes for Table 12 on page 101. 1. Is this server the first Domino Server in the domain, or is it an additional server in an already existing domain? Refer to Lotus Notes Administrator's Guide for detailed information. If this will be the first Domino Server in a new domain, then you should select First Domino Server. 2. This option allows you to select additional services to be started during Domino Server startup. These include Calendar Connector, Schedule Manager, Event Manager and Statistics. 3. This option enables your Domino Server to be accessible by Web browsers. 4. To enable your Domino Server to host mailboxes for Internet mail packages and to send and receive mail from the Internet, select IMAP, POP3 or SMTP. 5. Decide whether or not you require Internet Directory Services (LDAP) support. 6. This option enables Domino to send and receive messages from Internet newsgroups, and to be accessible by Internet news reader progams. 7. Enterprise Connection Services (DECS) provides Domino with the capability to access non-Notes data. 8. Domino Servers and Notes clients are grouped into domains. These domains are the basis for the design of a Lotus Notes environment. A domain is a group of servers using the same Public Address Book. Specify the domain name that you wish to use. 9. Select a name for the certifier. We have selected the same name as the Domain name. 10.The Certifier Country Code is optional. We have decided not to use a Certifier Country Code in our examples. 11.For the first server youll need to create a Certifier ID file. It will be called CERT.ID and the configuration program will put it into your Notes data directory. 12.The password for the Certifier ID is used when certifying new users into the Notes domain. The minimum password length is eight characters. We recommend using a password of at least 13 characters. A phrase is more secure than a password, and may be easier to remember. For more information, see the Lotus Notes Administrator's Guide .

102

Lotus Domino for S/390 R5 Installation, Customization and Administration

13.The name of the server being set up.


Note: The server's full name is a combination of the Server Name and the Organization Name, separated by a slash. For example, domino1/itso is the full server name used in our environment.

14.The servers TCP/IP host name. It is recommended that you use the convention: server_name.your_organization_domain_name. You do not necessarily have to use the OS/390 TCP/IP stacks host name. If you choose to use a different name, you may need to update your Domain Name Server (DNS) definitions with the new Domino Server host name. 15.Allow configuration to create a new server ID file, which will be called SERVER.ID and will be placed by the configuration program into your Notes data directory. 16.For the name of the Notes administrator, you would normally use a name such as: Notes Administrator. It is the name of an administrative function rather than a specific individual. Once the server is running, you would then add specific users with administrative authority. 17.Allow the configuration program to create a new administrator ID file, which will be called USER.ID and will be stored by the configuration program in the Name and Address Book. 18.The minimum password length is eight characters. We recommend using a password of at least 13 characters. A phrase is more secure than a password, and may be easier to remember. For more information, see the Lotus Notes Administrator's Guide. 19.Determine the time zone to be used and whether daylight saving time should be used. 20.In the OS/390 environment, the only protocol that is supported is TCP/IP. The Net Address field should match the servers host name as discussed in point 14 above. 21.The Serial Port option is not applicable to the Domino/390 Server; it should be set to -None-. 22.The Modem option is not applicable to the Domino/390 Server. There is no "None" option, so this can be left on any setting. After completing these tables, you have all the information needed for installing and configuring the server.

Configuring a Domino Server

103

Table 13 shows the information requested by the configuration program if you are installing an additional server in an existing domain. For the notes, see 7.2, Setting up additional Domino Servers on page 104.
Table 13. Information for an additional server in an existing domain

Information requested by configuration program for additional servers


Page 1 of 4 (Create a new Domino Server)
Is this the first or additional Domino Server?

See note

Your value

Additional

Page 2 of 4 (Server audience)


Additional Services Web Browsers Internet Mail Packages Internet Directory Services News Readers Enterprise Connection Services 2 3 4 5 6 7

Page 3 of 4 (Administration settings)


Server Name Servers Hostname Server ID Server Password Domain Address Book Location Local Time Zone Daylight Savings 8 9 10 10 11 12 12

Page 4 of 4 (Network and communications settings)


Ports Serial Port Modem 13 14 15

7.2 Setting up additional Domino Servers


Notes:

1. Is this server the first Domino Server in the domain, or is it an additional server in an already existing domain? Refer to Lotus Notes Administrator's Guide for detailed information. If this will be an additional server in an already existing domain, then you should select Additional Domino Server.

104

Lotus Domino for S/390 R5 Installation, Customization and Administration

2. This option allows you to select additional services to be started during Domino Server startup. These include Calendar Connector, Schedule Manager, Event Manager and Statistics.
Note: if you do not select these additional services, they can still be started manually. By adding them into notes.ini (in the ServerTasks section), they can be started automatically.

3. This option enables your Domino Server to be accessible by Web browsers. 4. To enable your Domino Server to host mailboxes for Internet mail packages and to send and receive mail from the Internet, select IMAP, POP3 or SMTP. 5. Decide whether or not you require Internet Directory Services (LDAP) support. 6. This option enables Domino to send and receive messages from Internet newsgroups, and to be accessible by Internet news reader progams. 7. Enterprise Connection Services (DECS) provides Domino with the capability to access non-Notes data. 8. The name of the server being set up.
Note: The server's full name is a combination of the server name and the domain name, separated by a slash. For example, domino1/itso is the full server name used in our environment.

9. The Servers TCP/IP host name. We recommend that you use the convention: server_name.your_organization_domain_name. You do not necessarily have to use the OS/390 TCP/IP stacks host name. If you choose to use a different name, you may need to update your Domain Name Server (DNS) definitions with the new Domino Server host name. 10.The server ID can be retrieved either from the Name and Address Book or it can be supplied in a file. If it is supplied in a file, then you must enter the file name, including the full path name. The file must exist in a OS/390 UNIX system services HFS.
Note: We recommend that you get the server ID from a file and not from the NAB. If you store the ID file in the NAB you must also give it a password. By giving it a password, you will need to enter this password every time you start the Domino Server.

11.Domain Address Book Location (NAB). Specify the server name where the server ID file can be retrieved. Although there are options for connectivity through both the Network (TCP/IP) or a serial port, only TCP/IP connectivity is supported in Domino/390.
Note: As stated in point 10 above, we recommend that you get the server ID from a file and not from the NAB.

12.Determine the time zone to be used and whether daylight saving time should be used. 13.In the OS/390 environment, the only protocol that is supported is TCP/IP. The Net Address field should match the Servers Hostname as discussed in point 9 above. 14.The Serial Port option is not applicable to the Domino/390 server; it should be set to -None-. 15.The Modem option is not applicable to the Domino/390 server. There is no "None" option so this can be left on any setting.

Configuring a Domino Server

105

After completing this table, you have all the information needed for configuring an additional Domino Server.

7.3 Running the server configuration program


After you have successfully run the install program, verified the paths, and documented the information youll require during configuration, you are now ready to run the server configuration program. To run server configuration you must start the Domino Servers HTTP server task and then use a Web browser to perform the configuration.
Hint

If the server configuration process does not complete successfully, there may be system resources that are not cleaned up. Use the ipcs command to view them and the ipcrm command to clean them up; see 9.6.3, Cleaning up the server resources manually on page 159. 1. Login to the OS/390 UNIX environment with the RACF user ID you specified as the owner of the Domino server during the install phase. This user ID should not have a UID of zero. You can login using rlogin or Telnet; OMVS will not work.
Note: If the httpsetup process does not work when you log on as the owning (non-zero) user ID, you can use the original install ID (with UID 0). But you should open an incident with the Support Center since this is a problem that needs to be fixed. And always start the server in production with the non-zero user ID that you defined.

2. Change to the Notes data directory that you specified during the install phase. In our example, we used /domino1/notesdata. From the UNIX shell command prompt enter the following command to start the HTTP server:
/usr/lpp/lotus/bin/http httpsetup

Note: The httpsetup program must be run from the Notes data directory for each server being configured. If three Notes data directories were populated during the install phase (in our example: /domino1/notesdata, /domino2/notesdata, /domino3/notesdata), then httpsetup must be run three times. When running httpsetup for each Notes data directory ensure that you logon as the owner of each specific Notes data directory before running httpsetup.

3. After you have started the HTTP server with the httpsetup parameter, you will be prompted to use a Web browser to connect to the HTTP server (see Figure 42). We recommend that you use Netscape Navigator R4 (or newer) or Internet Explorer R4 (or newer). Connect using the port specified. For example, if the server is domino1.ibm.com (IP address 9.12.15.103) and the port specified was 8081, you enter the following in the Web browsers URL (Uniform Resource Locator) field:
http://domino1.ibm.com:8081

or
http://9.12.15.103:8081

106

Lotus Domino for S/390 R5 Installation, Customization and Administration

DOMINO1 @ SC67:/domino1/notesdata>/usr/lpp/lotus/bin/http httpsetup 06/08/99 01:04:00 PM Created new log file as /domino1/notesdata/log.nsf 06/08/99 01:04:00 PM ***************************************** * Lotus Domino Server Setup * * To setup this server, please connect * * your Web browser to port 8081 * * Example: http://this.server.com:8081 * *************************************** 06/08/99 01:04:08 PM HTTP Web Server started
Figure 42. Output after the HTTP task has been started

4. After connecting to the HTTP server using a Web browser, you can now configure the new server.
Note: It is possible to quit the configuration process at any time and return later with your settings preserved. To do this, press Save & Quit at the top right of the screen.

5. The first decision you have to make in connecting to the configuration program is whether to create a new Domino Server in a new domain or to create an additional Domino Server in an existing domain. If you wish to create an additional server in an existing domain, you must first register the new server using an existing server in that domain. For more information on registering an additional Domino Server, refer to 16.2.4, Registering a Domino Server on page 348.

Figure 43. Create a new Domino Server

Configuring a Domino Server

107

6. Whether you chose First Domino Server or Additional Domino Server in Figure 43, you will be served a Server Audience screen like the one in Figure 44 on page 109. The configuration database lists server tasks that are automatically configured on the Domino Server in the Standard Services section. You cannot modify this section because these tasks are essential for the server to function. For more information about the choices you make, see Quick Help on the right side of the screen. In the Additional Services section, if you want to use calendar and scheduling features on this server, select Calendar Connector to install the Calendar Connector server task that enables Domino to use the Domino Directory to look up free time information for a user on another server. In the Additional Services section, if you want to use event monitoring on this server, select Event Manager to install the Event server task that creates the Statistics & Events database (EVENTS4.NSF) that enables Domino to report server errors and alarms, such as communications and replication issues. In the Additional Services section, if you want to use calendar and scheduling features on this server, select Schedule Manager to install the Schedule Manager server task that creates the Free Time database (BUSYTIME.NSF) that enables Domino to perform free time lookups for users on this server. In the Additional Services section, if you want to use event monitoring on this server, select Statistics to install the Report task to enable Domino to collect statistics about server activities such as mail, available disk space, and memory usage. In the Web Browers section, if you want browsers such as Microsoft Internet Explorer and Netscape Navigator to access data on the server, select HTTP to install the HyperText Transfer Protocol (HTTP) server task. In the Web Browsers section, if you want Domino to handle client IIOP requests, select IIOP to install the Domino Object Request Broker (ORB), which allows Domino objects to respond to IIOP requests. In the Web Browsers section, if you select HTTP, choose the primary activity for clients connecting to this Domino Server over HTTP. - If the primary activity for Web clients is using mail, select Web Mail. - If the primary activity for Web clients is using applications such as discussion databases or ordering applications, select Web Applications. - If Web clients will use both mail and applications on this server, select Both Mail and Applications. - If you wish to set the HTTP settings for this server manually, select Advanced (Custom Settings). This selection sets the Domino HTTP settings for optimal performance for the activities Web clients will perform on the server. In the Internet Mail Packages section, if you want mail clients using Internet Message Access Protocol (IMAP) to access mail on the server, select IMAP to install the IMAP server task. In the Internet Mail Packages section, if you want mail clients using Post Office Protocol 3 (POP3) to access mail on the server, select POP3 to install the POP3 server task.

108

Lotus Domino for S/390 R5 Installation, Customization and Administration

In the Internet Directory Services section, if you want clients using Lightweight Directory Access Protocol (LDAP) to access directory information on the server, select LDAP to install the LDAP server task. In the News Readers section, if you want news readers using Network News Transfer Protocol (NNTP) to access news groups and discussions on the server, select NNTP to install the NNTP server task. In the Enterprise Connection Services section, if you want to access data stored outside a Domino database, such as in a relational database or enterprise resource planning system, click the arrow and select DECS to install Domino Enterprise Connection Services.

Figure 44. Server Audience

7. Once you have made your selections on the Server Audience screen (see Figure 44), press the right arrow button. If this is the first server in a new domain, you will be presented with a screen like that in Figure 45 on page 110. If you are configuring an additional server in an existing domain, then skip to Step 12 below.

Configuring a Domino Server

109

Note: You can return to a previous screen to change its settings by clicking the left arrow at the top right of the screen. The numbers at the top left of the screen indicate which of the four configuration screens you are in.

Figure 45. Administration settings screen for first server

8. You can change the default server settings. For help on what the terms mean, click the blue labels (for example, Server Name) and hold down the mouse button to read the Help. For more information about the choices you make, see Quick Help on the right side of the screen. In the Organization Identity section, do all of the following: Enter a domain name. This is the name of the Domino domain to which the server will belong and creates a domain to which you can add other servers. Enter a certifier name. This is the name of the certifier used to stamp Notes ID files so that you can authenticate their identity. Enter a country code for your certifier (optional)
110
Lotus Domino for S/390 R5 Installation, Customization and Administration

Select whether to create a new certifier ID or use an existing one. If your organization does not yet have a certifier ID, create a new one. If you select to use an existing certifier ID, enter the file name for the certifier ID you want to use. Enter a certifier password. The password must be at least 8 characters. Lotus recommends using mixed-case passwords of at least 13 characters. If you are performing Advanced Configuration and select to use an existing certifier ID, you do not need to specify a password. For more information on domains, certifiers, and passwords, see Administering the Domino System . In the New Server Identity section, do all of the following: Enter a server name; for example, Domino1. This is the name of the new Domino Server. Users and other servers access the server using this name. Enter a server hostname; this is the name used by TCPIP to locate the server. Select whether to create a new server ID or use an existing one. If your organization does not yet have a Domino Server ID for this server, create a new one. If you select to use an existing Domino Server ID, enter its password and file name. In the Administrator's Identity section, do all of the following: Enter a first name, middle initial (M.I.), and last name for the server administrator. Select whether to create an administrator ID or use an existing one. If your organization does not yet have an ID for the server administrator, create one. Enter the password for the administrator's ID. The password must be at least 8 characters. Lotus recommends using a mixed-case password of at least 13 characters. If you select to use an existing administrator ID, you must specify the file name of that ID. 9. Select the local time zone and daylight savings settings that are appropriate to your location. 10.If you have been configuring a new Domino Server in a new domain, skip to step 13. 11.When configuring an additional server in an existing domain, youll see a screen like Figure 46 on page 112. For this step to work you must have already registered the new server using another server in the domain. See 16.2.4, Registering a Domino Server on page 348 for information on how to register additional servers. The server ID file for the new server must be available. The server ID file should be stored in the OS/390 UNIX HFS (it could have been stored there using FTP or another method).
Note: We recommend that you get the server ID from a file and not from the NAB. If you store the ID file in the NAB you must also give it a password. By

Configuring a Domino Server

111

giving it a password you will need to enter this password every time you start the Domino Server. In the New Server Identity section, do all of the following: Enter a fully qualified name for the server -- for example, domino2/itso -in the Server Name field. Enter a server hostname; this is the name used by TCPIP to locate the server. Select Server Id in a File and then enter the location of the file for the Server ID. Note: This file must reside in an OS/390 UNIX System Services HFS. In the Domain Address Book Location section, enter the name of an existing Domino Server from which the new server can obtain the Domino Directory (NAB) for the domain.

Figure 46. Administration settings screen for additional server

Press the right arrow button to continue to the next screen, which is Network and Communications Settings (see Figure 47 on page 113).

112

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 47. Network and communications settings

12.In the Network and Communications Settings section, do any or all of the following: In the Network Options section, select whether to use all available ports or to select ports. If you choose to select ports, do the following for each port: Choose a protocol by clicking the down arrow and selecting a protocol. (Note: Only TCP/IP is supported with Domino/390.) Enter a network address. Click the down arrow and select to enable or disable the port. 13.No input is required in the Communications Port Options section because S/390 uses TCP/IP. 14.Verify that the server settings are correct and click Finish . 15.Domino now begins building the new server. See Figure 48 on page 114 for an example of what you would see on the UNIX shell session at the completion of the build.

Configuring a Domino Server

113

DOMINO1 @ SC67:/domino1/notesdata>/usr/lpp/lotus/bin/http httpsetup 06/08/99 01:04:00 PM Created new log file as /domino1/notesdata/log.nsf 06/08/99 01:04:00 PM ***************************************** * Lotus Domino Server Setup * * To setup this server, please connect * * your Web browser to port 8081 * * Example: http://this.server.com:8081 * *************************************** 06/08/99 01:04:08 PM HTTP Web Server started 06/08/99 01:06:49 PM Addin: Agent message box: Domino Setup is initializing. Please wait... 06/08/99 01:06:49 PM Addin: Agent message box: Domino Setup is gathering Port information... 06/08/99 01:36:29 PM Setting default information in preferences file... 06/08/99 01:36:30 06/08/99 01:36:30 computation... 06/08/99 01:36:31 06/08/99 01:36:31 PM Begin registering /Itso... PM Creating ID for /Itso. This requires 1-3 minutes of PM Begin certifying /Itso... PM Certifying /Itso

06/08/99 01:36:31 PM Done certifying /Itso... 06/08/99 01:36:32 PM /Itso successfully registered. 06/08/99 01:36:32 PM Creating ID for Notes Admin/Itso. This requires 1-3 minutes of computation... 06/08/99 01:36:33 PM Begin certifying Notes Admin/Itso... 06/08/99 01:36:33 PM Certifying Notes Admin/Itso 06/08/99 01:36:33 06/08/99 01:36:34 06/08/99 01:37:08 06/08/99 01:37:09 06/08/99 01:37:10 06/08/99 01:37:10 06/08/99 01:37:11 of computation... 06/08/99 01:37:13 06/08/99 01:37:13 06/08/99 06/08/99 06/08/99 06/08/99 06/08/99 06/08/99 06/08/99 06/08/99 01:37:14 01:37:14 01:37:18 01:37:19 01:37:19 01:37:50 01:37:51 01:38:06 PM PM PM PM PM PM PM Done certifying Notes Admin/Itso... Creating your address book Begin registering /O=Itso... Adding /O=Itso to the Name and Address Book... /O=Itso successfully registered. Begin registering Domino1... Creating ID for Domino1/Itso. This requires 1-3 minutes

PM Begin certifying Domino1/Itso... PM Certifying Domino1/Itso PM PM PM PM PM PM PM PM Done certifying Domino1/Itso... Adding Domino1/Itso to the Name and Address Book... Domino1/Itso successfully registered. Begin registering Notes Admin... Creating mail file for Notes Admin/Itso... Adding Notes Admin/Itso to the Name and Address Book... Notes Admin/Itso successfully registered. Updating network settings

Figure 48. UNIX Shell session output at completion of configuration

16., When the build is complete, a congratulations screen is presented (see Figure 49 on page 115). The configuration program prompts you to write down the server ID password, certifier ID password, and administrator's ID password. Keep these passwords secure.

114

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 49. Final screen of httpsetup

17.There is an Exit button on the Congratulations window on the browser. Exit will cause the HTTP Server task to shut down on the server. The final message you should see in the UNIX shell when the HTTP server task is shut down is:
mm/dd/yy hh:mm:ss nM HTTP Web Server shutdown

You have now completed the configuration process. You can now start the server (see Chapter 9, Start, stop and monitor the server on page 127).
Note: As mentioned in step 3, the httpsetup program must be run from the Notes data directory for each server being configured. For example, if three Notes data directories were populated during the install phase (in our example: /domino1/notesdata, /domino2/notesdata, /domino3/notesdata ), then httpsetup must be run three times. When running httpsetup for each Notes data directory, ensure that you logon as the owner of the specific Notes data directory before running httpsetup.

7.4 Rerunning the setup process


You may wish to rerun the server setup process because you wish to recreate all of the server files. The outcome will be the creation of a new server and the replacement of all the files from the previous server. 1) Go to the relevant Notes data directory. 2) Copy any files you wish to keep from the data directory to another directory. 3) Delete all the files in the Notes data directory and all subdirectories under it. For example:
115

Configuring a Domino Server

cd /notesdata rm -Rf * rm .* 4) Run the install program, then run the configuration program (http httpsetup).
Note: If you rerun the install program after you have completed the entire installation process, you will rebuild /usr/lpp/lotus, thereby overwriting its current contents (including permission bits). Since the PUTINLPA job discussed in Chapter 8, Preparing Dynamic LPA on page 119 sets the sticky bits on for the server executable modules, these sticky bits will effectively be turned off by rerunning the install program. Our recommendation is that if you rerun the install program, rerun the entire three-part installation process.

7.5 Downloading important files


You should now download the following files to your workstation:
user.id cert.id server.id notes.ini

Administrator's ID file Organization certifier ID file Server's ID file Domino Server's initialization parameters

With the exception of the user.id file, which is stored as an attachment in the Name and Address Book, the other files can be downloaded to a workstation using a file transfer method such as FTP. You should do this because: You need the user.id file to be able to connect to the server from a Lotus Notes workstation. You need the cert.id file to be able to perform administrative activities for the server, such as user registration and cross-certification. You also need to secure this file from unauthorized access. You need backup copies of these files. If you should lose the only copies, you may lose access to data on this server. We recommend that you rename these files so that you know which server they apply to. Otherwise you may not know which files apply to which server, and you run the risk of overwriting some files. Include the server or domain name in the name of the file on your workstation. It is also a good approach to store the files for each server or domain in a separate directory.
Caution

To avoid corrupting these files: Download them with the binary option. Do not replace a user.id file that is in use. Beware of overwriting a file with the same standard name. You also need to make sure that these files are backed up on a regular basis to include any changes. We discuss this in Chapter 14, Data backup on page 283

116

Lotus Domino for S/390 R5 Installation, Customization and Administration

7.5.1 Using FTP


To download the files from the S/390 server to your workstation using FTP, issue the commands in Figure 50 on page 117 from a command prompt on the workstation:
Note: We create a separate directory c:\notes\data\wtsc53 on the workstation for these files so that we do not overwrite any other files with the same names. Note that wtsc53 is the name of the server whose files we are downloading. You probably already have a user.id file in directory c:\notes\data on your workstation and so you must be careful not to overwrite it.

md c:\notes\data\wtsc53 cd c:\notes\data\wtsc53 FTP wtsc53 userid password cd /notesdata binary get cert.id get server.id get notes.ini bye

<= <= <= <=

Make directory for files on workstation Directory for files on workstation wtsc53 is the TCP/IP name MVS user ID with HFS access

<= Directory of files on OS/390 <= Download in binary

Figure 50. Download files using FTP

7.5.2 Using send/receive


You can use any other send/receive program by copying the files to standard OS/390 sequential data sets first and then downloading those files. Note that both the copy and the download must be in binary. To do this: 1. Log on to TSO. 2. Type ISHELL to go into the OS/390 UNIX shell. 3. Change to directory /notesdata. 4. Use the C command to copy these files to OS/390 data sets. Use the binary option to do the copy. 5. Then download the files to your workstation using receive or FTP. Make sure you use the binary option.

7.5.3 Recovering a lost or corrupted file


To recover a lost or corrupted file, you just reverse the preceding procedures, using the FTP put command rather than get, and send rather than receive. You need to close down the Domino Server before you replace the notes.ini file.

7.5.4 Detaching the user.ID file from the Name and Address Book
The configuration process of Domino R5 does not store the Notes administrators ID file (user.ID) in the Notes data directory. Instead, the file is stored as an attachment in the Notes administrators Person Document in the Name and Address Book (NAB). For a user to logon to the server as the Notes administrator, they will first need to have a copy of the user.ID file on their workstation.

Configuring a Domino Server

117

Since the user.ID file is stored as an attachment in the NAB, we cannot use FTP to download it to a workstation. We must instead access the NAB and detach the file. Follow these steps to download the user.ID file to a workstation: 1. Start the Domino Server (see Chapter 9, Start, stop and monitor the server on page 127 for more details). 2. Ensure that the HTTP task is running. If it is not, type load http from a Domino console interface.
Note: If the HTTP server does not start because another Web server is listening (and has effectively reserved) TCP/IP port 80, refer to A.11, Gaining access to the USER.ID file after configuration on page 389.

3. Use a Web browser to connect to the appropriate TCP/IP hostname or address. For example: http://domino1.ibm.com 4. Once you have confirmed that you can connect to the HTTP server, add names.nsf to the URL field. For example:
http://domino1.ibm.com/names.nsf

You will now be prompted for a username and password. When you ran setup, an admin user ID and password was supplied as part of that process (for example, Joe Smith with a password of enter). At the login prompt, enter the Notes short name (first initial of given name, then surname, for example, jsmith). Then enter the password. 5. You should now have access to the Name and Address Book. Select People, then select the Notes administrator name that you defined during the configuration process. 6. Double-click on the user.ID attachment file. Your Web browser should automatically prompt you to save the file to your PC. 7. Before using the ID file with your Notes client, ensure that it has been stored as User.ID and not (as happens in some browsers) as User.ID.html. If the latter, you can use an MS-DOS window to rename it:
cd \notes\data rename user.id.html user.id

8. Start the Notes client software. When prompted, supply the location of the User.ID file
Note: The process of saving the administrators ID as outlined previously causes a minor security exposure in that, while the HTTP task is running, anyone with access to the network can download the ID file. However, only the installer should know the ID files password. We therefore recommend that you adhere to Lotus recommendations for password naming. The minimum password length is eight characters. We recommend using a password of at least 13 characters. A phrase is more secure than a password, and may be easier to remember. For more information, see the Lotus Notes Administrator's Guide.

7.6 What to do next


You should now be ready to start the final stage of the installation process: preparing the executable modules so that you can start the Domino Server. Refer to Chapter 8, Preparing Dynamic LPA on page 119.
118
Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 8. Preparing Dynamic LPA


Once you have completed the installation steps as described in the previous several chapters, you are now ready to complete the third and final part of the Domino installation process: putting the Domino modules into the dynamic link pack area. The job PUTINLPA is provided for copying the Domino Server executables into the PDSE data set that was created by the ALOCPROD job. You need to place the Domino Server modules into the LPA so that they are not loaded into every server address space that is created. This saves a lot of storage and also improves performance.
Note: You must follow these steps so that the new code is placed into your running system. Otherwise, old and new code may be mixed, causing problems.

8.1 Putting Domino modules into Dynamic LPA


With Lotus Domino R5 we put all the server DLLs into dynamic LPA. The reason for this is that the size of the executables that make up Domino has changed significantly since Domino 4.6.x. The libnotes module alone is approximately 22 MB. The maximum size module that can be loaded into LPA is 16 MB. Therefore, it was decided to place all modules into Dynamic LPA, where the 16 MB limit does not apply. In addition, this satisfies a UNIX System Services requirement that any authorized DLL (for example, libnotes) must call only authorized DLLs, so these DLLs are also stored in the DLPA. Figure 51 on page 120 shows the PUTINLPA job shipped with the Lotus Domino R5 CD-ROM. Notes about this job are shown below the figure.

Copyright IBM Corp. 1999

119

//PUTINLPA JOB <JOB CARD PARAMETERS > //********************************************************************* //* * //* This JCL will relink product executables into pre-allocated PDS/E* //* data set and turn on sticky bits . * //* Product: DOMINO SERVER for S/390 Release 5.0 * //* * //* This JOB must be run from a USERID that has a UID(0). * //* * //* CAUTION: THIS IS NEITHER A JCL PROCEDURE NOR A COMPLETE JOB. * //* Before using this job step, you will have to make the following * //* modifications: * //* * //* 1) CHANGE THE JOB CARD TO MEET YOUR SYSTEM REQUIREMENTS * //* 2) CHANGE fff TO THE DOMINO DYNAMIC LPA PDS/E HIGH LEVEL * //* QUALIFIER ("SYS2" IS THE DEFAULT) * //* IF YOU CHOOSE TO USE A MIDDLE LEVEL QUALIFIER, YOU SHOULD * //* CHANGE fff TO "SYS2.MMM". * //* THE PDS/E NAME MUST MATCH THE NAME PREVIOUSLY ALLOCATED VIA * //* THE SAMPLE JCL ALOCPROD JOB. * //* * //* NOTES: * //* * //* 1. THIS JOB SHOULD COMPLETE WITH A RETURN CODE 0. * //* * //********************************************************************* //* //********************************************************************* //* JOB STEP: LINKLIBN //********************************************************************* //* //LINKLIBN EXEC PGM=IEWL,REGION=0M, // PARM='LIST,XREF,LET,RENT,REUS,AMODE=31,RMODE=ANY,CASE=MIXED' //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,10)) //SYSPRINT DD SYSOUT=* //SYSTERM DD SYSOUT=* //SYSDEFSD DD DUMMY //SYSLMOD DD DSN=fff.LOTUS.LPAPDSE,DISP=OLD //SYSLIN DD * INCLUDE '/usr/lpp/lotus/notes/latest/os390/libnotes' ENTRY CEESTART NAME LIBNOTES(R) INCLUDE '/usr/lpp/lotus/notes/latest/os390/ftgtr' ENTRY CEESTART NAME FTGTR(R) INCLUDE '/usr/lpp/lotus/notes/latest/os390/decsext' ENTRY CEESTART NAME DECSEXT(R) //* //********************************************************************* //* JOB STEP: STICKY //********************************************************************* //* //STICKY EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * bpxbatch SH chmod o+t /usr/lpp/lotus/notes/latest/os390/libnotes bpxbatch SH chmod o+t /usr/lpp/lotus/notes/latest/os390/ftgtr bpxbatch SH chmod o+t /usr/lpp/lotus/notes/latest/os390/decsext /*
Figure 51. PUTINLPA job supplied with CD

120

Lotus Domino for S/390 R5 Installation, Customization and Administration

Notes:

1. This job requires a valid MVS user ID with access to the data sets being used. 2. You need to modify the jobcard for your installation. 3. If you are running in a Parallel Sysplex, add a JOBPARM card such as /*JOBPARM SYSAFF=SC67 to route the job to the system where the HFS data sets are mounted. 4. Ensure the data set name in the SYSLMOD DD statement of the first job step LINKLIBN is the same as was used in the ALOCPROD job to create the Dynamic LPA PDSE data set. 5. The first job step link-edits the listed modules from the HFS into the dynamic LPA data set. 6. The second job step turns on the sticky bit for the modules that have been placed in the Dynamic LPA data set. This means that these modules will be accessed from Dynamic LPA if they are there, rather than being loaded from the HFS into every address space. This saves memory and greatly improves performance. After running this job, check that the executables in the HFS do indeed have the sticky bit set on. To do this, logon to the OS/390 UNIX environment using OMVS, rlogin, or Telnet. Then issue the commands in Figure 52.

cd /usr/lpp/lotus/notes/latest/os390 ls -l
Figure 52. Check the sticky bit

<= change directory

You will see the results in Figure 53.

total 185392 drwxr-xr-x drwxr-xr-x -rwxr-xr-x . . -rwxr-xr-x -rwxr-xr-t -rwxr-xr-x . . -rwxr-xr-x -rwxr-xr-t -rwxr-xr-x . . -rwxr-xr-x -rwxr-xr-t -rwxr-xr-x . . -rwxr-xr-x -rwxr-xr-x

4 STC 3 STC 1 STC

OEDOMINO OEDOMINO OEDOMINO

0 Jun 11 13:32 . 0 Jun 8 11:58 .. 1756 Jun 7 15:14 DomLANG

1 STC 1 STC 1 STC

OEDOMINO 303104 Jun 3 20:48 decs OEDOMINO 188416 Jun 3 20:48 decsext OEDOMINO 65536 Jun 4 01:28 design

1 STC 1 STC 1 STC

OEDOMINO 69632 Jun 4 01:29 fixup OEDOMINO 1519616 Jun 4 01:31 ftgtr OEDOMINO 528384 Jun 4 01:39 ftp

1 STC 1 STC 1 STC

OEDOMINO 143360 Jun 4 01:43 libirtf OEDOMINO 33091584 Jun 7 18:05 libnotes OEDOMINO 1726080 Jun 4 19:19 libnotes.x

1 STC 1 STC

OEDOMINO 561152 Jun 4 01:44 wmsgtrc OEDOMINO 69632 Jun 4 01:50 xpcdmn

Figure 53. Output of the ls -l command

Preparing Dynamic LPA

121

A t is displayed in the last position of the authorization values if the sticky bit is turned on. Check that it is on for the modules listed in the job. If it is not on, issue the chmod command shown in the job to turn the sticky bit on. For example:
chmod o+t /usr/lpp/lotus/notes/latest/os390/libnotes

If you wish to be absolutely sure that the modules are not being loaded from the HFS (and thus causing performance degradation), you could rename those modules (or copy them to another location). Then add dummy modules with those names, also with the sticky bit on. If they are loaded from the HFS rather than accessed from LPA, you would get an error message since the module would be unusable.

8.1.1 Change PARMLIB to load Dynamic LPA modules at IPL


Modify SYS1.PARMLIB to load the executables from the Dynamic LPA data set at IPL time. 1. Copy the MDFYPROG file shipped with the Lotus Domino R5 server (shown in Figure 54) into a PROGxx member in SYS1.PARMLIB. This can be a new member, or an existing member that is used for modules loaded into Dynamic LPA.

/********************************************************************/ /* */ /* Sample PROG command for placing LIBNOTES dll into DYNAMIC LPA */ /* For product DOMINO SERVER for S/390 Release 5.0 */ /* */ /* CAUTION: THIS IS NEITHER A JCL PROCEDURE NOR A COMPLETE JOB. */ /* Before using this sample, you will have to make the following */ /* modifications: */ /* */ /* 1. Change "fff" to the DOMINO PDS/E high level qualifier */ /* ("SYS2" is the default.) */ /* If you choose to use a middle level qualifier, you should */ /* change "fff" to "SYS2.MMM". */ /* The PDS/E name must match the name previously allocated */ /* via the sample JCL ALLOPROD. */ /* */ /* 2. Add this statement to 'SYS1.PARMLIB(PROGxx)' */ /* This "PROGxx" member can not be pointed to by IEASYSxx */ /* directly. Add a COM='SET PROG=xx' STATEMENT IN COMMNDxx. */ /* */ /********************************************************************/ LPA ADD DSNAME(fff.LOTUS.LPAPDSE) MODNAME(LIBNOTES) LPA ADD DSNAME(fff.LOTUS.LPAPDSE) MODNAME(FTGTR) LPA ADD DSNAME(fff.LOTUS.LPAPDSE) MODNAME(DECSEXT)
Figure 54. MDFYPROG supplied with Domino R5

Check that the PDSE data set name specified in PROGxx is consistent with the PDSE data set name previously allocated by the ALOCPROD job.
Note: This must not be a member that is pointed to by a PROG= statement in IEASYSxx. If it is, you will get an error message when you IPL the system. When the PROG= statements are processed, it will try to load the modules from the PDSE data set. However, access to PDSE data sets requires the SMS address space to be started. SMS is not started at that point in the IPL and there will be an error.

122

Lotus Domino for S/390 R5 Installation, Customization and Administration

2. To load the module from the PDSE data set into Dynamic LPA, add the following entry to the SYS1.PARMLIB(COMMNDxx) member you are using: COM='SET PROG=xx' Make sure that this entry is before any commands that start the Domino Server. The COMMNDxx member you are using is pointed to in SYS1.PARMLIB(IEASYSxx) with the CMD= parameter.

8.2 Loading the Dynamic LPA modules


With the assumption that you have not previously run any version of Domino code on your system it is possible to dynamically load the Domino modules into the Dynamic LPA. You will then be able to start the Domino Server.
Note: This potentially means that you can install Domino without the need of an IPL. However, in practice you will probably have had to install some prerequisite PTFs or made changes to BPXPRMxx, so it is unlikely that you will be able to install Domino without at least one IPL.

To load the modules into DLPA you must use an authorized user ID or get your operations staff to issue the following command: SET PROG=xx where xx refers to the PROGxx member of PARMLIB you have created or updated to include the contents of the MDFYPROG file.

Note

If you encounter the message


CSV555I LPA ADD FUNCTION WAS NOT SUCCESSFUL. CSAMIN THRESHOLD EXCEEDED

when the SET PROG=xx is issued, you must review your CSAMIN value in your PARMLIBs PROGxx and your CSA value in IEASYSxx. Due to the size of the libnotes module (approximately 25 MB) you must ensure that you have a large enough CSA defined. In our test environment we set the following values: CSAMIN: 100K,100K CSA: 2048,64M

8.2.1 Considerations when upgrading from previous releases


If you were running a 4.x release of Domino before installing Domino R5, you must remove all 4.x modules from the LPA and DLPA before continuing. To remove the 4.x LPA modules, you must remove the appropriate Domino library name from the LPALSTxx PARMLIB member. To remove the 4.x DLPA modules, you should remove any definitions that you may have previously made in the PROGxx PARMLIB member. Perform an IPL with CLPA (Clear Link Pack Area). After the IPL is complete, you should no longer have any Domino 4.x modules loaded.

Preparing Dynamic LPA

123

If you did not have any Domino 4.x modules loaded into LPA but had loaded the libnotes module into DLPA, you can remove this module by typing the command in Figure 55 from an authorized users SDSF screen or operators console. If this scenario applies to your installation you can now perform the SET PROG=xx command to load the R5 modules without the need to IPL your system.

SETPROG LPA,DELETE,MODNAME=LIBNOTES,FORCE=YES

Figure 55. Remove the libnotes module from Dynamic LPA

8.3 Start the server and verify that it is working


You should now check whether the server is working by starting it and connecting to it from a Lotus Notes workstation client. If you do not have a Notes workstation client available, then you will need to install one. Detailed information on the hardware and software requirements and the installation steps are included in Lotus Notes Install Guide for Workstations. Once you have the Notes workstation installed, do the following: 1. Start the server as described in Chapter 9, Start, stop and monitor the server on page 127. 2. If your Domino Server name is not the same as the TCP/IP name of the S/390 server, you will need to add the Domino Server name to the Domain Name Server (DNS) so that a Notes client can find it. Alternatively, you can define a connection document on your Notes client (you should view this as a short term solution until you get the DNS updated): Open your Address Book on Local. Select the view Server/Connections. Click Add Connection . Set: Connection type to LAN Server name to your Domino Server name (such as wtsc53) Use LAN port to TCP/IP In Advanced, set the destination server address to the IP name or address of the OS/390 server (such as wtsc53.itso.ibm.com or 9.12.14.223)

Click Save, then Close. 3. Switch user ID: Click File->Tools-> Switch Id. Select the user.id file for the new server. You will be prompted for the password. 4. Open a database on the server: Choose File-> Database ->Open. Select or type in the server name, for example wtsc53. Click Open .

124

Lotus Domino for S/390 R5 Installation, Customization and Administration

Select a database, for example the domain's Public Address Book. Click Open . The database will be opened and an icon will be placed on your Notes desktop. 5. If the database opens successfully, then the server is working. 6. Also issue the show users command on the Domino Server console and you should see the administrator's name with the database opened.

Preparing Dynamic LPA

125

126

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 9. Start, stop and monitor the server


This chapter describes how to operate the Lotus Domino Server on OS/390, including: Different ways to operate the server Starting the server Stopping the server Monitoring the status of the server What to do if the server does not start or stop

9.1 Ways to operate the server


The Domino Server on S/390 can be operated from a number of different consoles, including: From a Domino Administration Client From a Web browser using the Web Administrator From a workstation using rlogin or Telnet From a TSO screen using OMVS (not supported by Domino R4.6 and 5.0) From the OS/390 console using a product called DOMCON We describe these in this section and make some recommendations.

9.1.1 Domino Administrator Client


Lotus Domino Release 5 provides a special client for administration tasks called the Administrator Client. The Administrator Client must be selected during setup of your Notes Client or can be installed separately (16.1, Installing the Lotus Domino Administrator client on page 325). You can start it in different ways: From a standard Notes workstation client by selecting File->Tools ->Server Administration From your workstation startup menu by selecting Start->Lotus Folder->Lotus Domino Administrator From the bookmarks bar on the left side of your Notes client To be able to use the administrator functions, ensure you are using an ID that has administrator rights to the server. If not, detach the authorized user ID file from the name and address book or download it with ftp (if it exists as a file in an HFS) to the data directory of your Notes client (e.g., c:\lotus\notes\data). Then switch to that ID by selecting File->Tools->Switch ID in your Notes client. This facility is the main interface for any Domino-related administration task (see 16.2, Using the Domino Administrator on page 341 for further information). It also enables you to perform Domino Server commands and monitor the server from your workstation. You can close the server down, but (with Domino S/390) you cannot start a server. Domino administrators will already be familiar with this facility, as it is common to all Domino Server platforms. The server console log is

Copyright IBM Corp. 1999

127

written to the log.nsf database on the server, so a Notes workstation user can read it.

9.1.2 Web browser using the Domino Web Administrator


Lotus Domino R 4.6 introduced a function to administer a Domino Server using a Web browser. In Release 5 some functions were added. See 16.5, Domino R5 Web Administrator on page 352 for additional information about the Web Administrator.

9.1.3 Workstation using rlogin or Telnet


You can operate the server from a workstation that logs in to UNIX System Services using rlogin or Telnet. This UNIX workstation or PC user has a standard TCP/IP interface. It starts the server as on any other UNIX platform that runs the Domino server. It continues to have a console function after the server is started, and can be used to monitor the server, issue server commands and shut down the server. If this workstation loses its TCP/IP connection to the Domino server or the Telnet/rlogin session is closed, the server continues to run. Therefore, Notes clients can continue to access the server. You cannot reconnect the server console directly, but there are some means for operating the server and check its log even when the Telnet console has been lost: With the cconsole utility (available with Domino R5 for UNIX platforms) With the concom command Nevertheless, you can still manage the Domino Server from the Domino Administrator client. The IBM product DOMCON also provides a function to issue Domino Server commands from an rlogin, Telnet or OMVS session.
Note: This workstation has a high level of authority as far as the Domino Server is concerned. It can shut the server down and it can change server parameters. Therefore, you should ensure that the workstation is secured from unauthorized access.

9.1.4 TSO screen using OMVS


It is possible to operate the server from a TSO OMVS session, although not supported or recommended for anything other than limited testing.
Note: Lotus Domino for S/390 Release 5 does not support starting the server from OMVS. This is not a good way of running the server anyway, since it requires you to keep pressing the Refresh key to refresh the server console. You must make sure that your TSO region size is large enough--we used 100 MB.

If this method is used, the TSO users log in to UNIX System Services by issuing the command OMVS. They then have a standard UNIX workstation interface similar to the workstation using rlogin or Telnet. If a TSO user gets disconnected, the Domino Server continues to run and Notes clients can continue to access the server.

128

Lotus Domino for S/390 R5 Installation, Customization and Administration

9.1.5 IOS/390 operator console: DOMCON


In a S/390 environment, the ideal method is to operate the Domino Server from the OS/390 operator console. The OS/390 console already provides functions to switch to an alternate console if a console becomes disconnected, and it is typically secured from unauthorized access. In addition, the OS/390 console provides: The ability to start the Domino server automatically at IPL time Support to manage multiple Domino partitioned servers from the same console Remote access using SDSF, with appropriate controls Interfaces to automation systems that can start and stop the server automatically and respond to error situations IBM has written code to start, stop and operate the Domino Server from the OS/390 operator console. This code is packaged under the name DOMCON and became available in 1998. Since its release, the package has had its functionality improved due to large customer acceptance and use. The newest release is DOMCON V3. It is available for download from an IBM Web site. The URL is:
http://www.s390.ibm.com/products/domino/domcon/dmcnmain.html

The DOMCON package provides: An automated and synchronized way to start the Domino for S/390 Server with other resources at system IPL time Management of all Domino partitioned servers on the OS/390 image from the same console Remote access with SDSF/console functions with appropriate controls The ability for operations to send server commands to the Domino for S/390 Server from the console Operations with the capability of performing an orderly shutdown of the Domino for S/390 Server during OS/390 shutdown An interface to automation systems that can start, stop, or send commands to the server in response to error situations Synchronized S/390 resource utilization Signal the Domino for S/390 Server to start replications at the completion of Batch processing (may be variable on end-of-month/week). RACF protected data set to store Domino passwords (server.id) and the ability to automatically feed them into the server's input stream at startup (automated startups with secure server.id files) An interface from UNIX System Services to send commands to your Domino Servers and see the responses RACF Surrogate authority is used to control which users can access which servers. The DOMCON package was built to be a nonintrusive monitor of your Domino for S/390 Server. This means that at any point in time, you can start your Domino

Start, stop and monitor the server

129

for S/390 Server without DOMCON . There are no changes to make and you will have "removed" this package from the startup sequence of this server.
Note: This package in its current form is provided on an as-is basis. IBM does not imply nor does it provide any warranty, service, or formal support for this package.

You will, however, find a very useful discussion database bundled with the DOMCON package available from the Internet, which addresses many of the common problems users encounter with the package. The discussion database is read-only in that you can only submit requests or comments to it through your IBM representative. We successfully tested the DOMCON package during our residency project and found that it is helpful in a Domino operation environment although it is still not an officially supported product. We did consider how DOMCON could work with NetView to automate recovery from a Domino error, and we have documented those ideas in Appendix F, The ps shell command for threads on page 415.

9.1.6 Recommendations
Based on the previously mentioned options, we recommend: For testing, use whichever console you prefer. Keep in mind that the OMVS sessions can cause problems. A Domino administrator will most probably use the Domino R5 Administrator client to monitor and operate the server. Once you are running production work, start the server from the OS/390 operator console using DOMCON. You can issue Domino Server commands from the OS/390 console or from your OS/390 USS environment, but we think that will happen infrequently because Domino administrators will use the Domino Administrator client. If you run into problems, start Domino from a Telnet or rlogin session for problem determination.

9.2 Starting the server


In this section we show how to start the server using an rlogin or Telnet session following the instructions of the install guide.
Note: The server should be started from a Telnet or rlogin session. Do not start the server from the TSO OMVS shell. Many customers have been using the DOMCON package available through the Web. This package is not yet officially supported. Therefore, we recommend that if you encounter any problems, diagnose these problems while starting the server from a Telnet session.

9.2.1 Checklist before you start the server


Before you start the server, you should check to see that the environment is ready. You may not always need to do this. However, if the server does not start, you may need to come back to this step to work out what is wrong.

130

Lotus Domino for S/390 R5 Installation, Customization and Administration

9.2.1.1 Domino Server user ID The userid that is used to start the server must be defined to the OS/390 Security Server (RACF) or equivalent security product with a valid OMVS segment. This userid must be authorized to access all Domino files on the HFS, but should not have superuser authority. The userid that is used to start the server also must have write authority to the /tmp directory. Note: Starting the server from a superuser ID (UID=0) exposes your system to security violations.

This userid will be the same one you defined for the server during the installation process. If you are not sure what the userid (UID) and group (GID) security settings are for that userid, you can check RACF or issue the id command from the UNIX shell as shown in Figure 56.

D1ANDRE @ SC67:/tmp>id domino1 uid=5001(DOMINO1) gid=2000(OEDOMINO) D1ANDRE @ SC67:/tmp>


Figure 56. Display user ID information in OS/390 USS

9.2.1.2 Check that the HFS files are mounted If you followed the instructions in 5.5, Use MDFYBPXP to mount the HFS data sets at IPL time on page 81, all file systems that are necessary for the server startup should be mounted and defined in the BPXPRMxx parmlib member:

Domino code file system Domino data file system Domino mail file system To display the current mounts, issue the MVS console command D OMVS,F. Sample output is shown in Figure 57.

D OMVS,F BPXO041I 13.58.17 DISPLAY OMVS 382 OMVS 000F ACTIVE OMVS=(53) TYPENAME DEVICE ----------STATUS----------- Q HFS 8 ACTIVE NAME=OMVS.SC53.NOTES.LOTUS.MAIL.HFS PATH=/notesdata/mail HFS 7 ACTIVE NAME=OMVS.SC53.NOTES.LOTUS.V4501.DATA.HFS PATH=/notesdata HFS 6 ACTIVE NAME=OMVS.SC53.NOTES.LOTUS.V4501.PROD.HFS PATH=/usr/lpp/lotus HFS 5 ACTIVE
Figure 57. Checking whether HFS data sets are mounted

You can also issue the command df -k in the OS/390 USS environment to check which file systems are mounted and how much space is available (see Figure 58). The -k option shows the space in kilobyte units.

Start, stop and monitor the server

131

D1ANDRE @ SC67:/domino1/notesdata> df -k /domino2/notesdata (OMVS.SC67.DOMINO5.DOMINO2.DATA.HFS)128040/360000 4294966505 /domino1/notesdata (OMVS.SC67.DOMINO5.DOMINO1.DATA.HFS)50000/360000 4294966432 /domino1/notesdata/mail (OMVS.SC67.DOMINO5.DOMINO1.MAIL.HFS)10000/10000 42949664 /u/domcon (OMVS.SC67.DOMCON22.HFS) 248/86400 4294967082 Available /usr/lpp/lotus (OMVS.SC67.DOMINO5.PROD.HFS)156152/504000 4294966912 Available /usr/lpp/java (OMVS.SC67.JAVA116.OS390R6.HFS)5256/166320 4294966672 Availabl /web/suf (OMVS.SC67.WEB.SUF) 17648/18000 4294967258 Available /var (OMVS.SC67.VAR) 35552/36000 4294967234 Available /u (OMVS.SC67.USERS) 75092/81360 4294966988 Available /etc (OMVS.SC67.ETC) 3824/7200 4294966998 Available / (OMVS.OS390R6.SC67.O36RF1.ROOT)24520/460800 4294958396 Availabl D1ANDRE @ SC67:/domino1/notesdata>
Figure 58. Display mounted file systems from the OS/390 USS shell

If the HFS data sets needed by your Domino system are not mounted, then run a job (or start a procedure) such as the one shown in Figure 59 to mount the file systems you need.

//LOTUS01A JOB(XIS9,POK),OHKUBO,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A /*JOBPARM SYSAFF=SC67 //IKJEFT01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * MOUNT FILESYSTEM('OMVS.SC67.DOMINO5.PROD.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/usr/lpp/lotus') MOUNT FILESYSTEM('OMVS.SC67.DOMINO5.DATA.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/domino1/notesdata') MOUNT FILESYSTEM('OMVS.SC67.DOMINO1.MAIL.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/domino1/notesdata/mail') /*
Figure 59. Job to mount HFS data sets

If you want to mount the file systems from the OS/390 UNIX environment, IBM provides a REXX script /samples/mountx. See Figure 60 for how to call the script. To use this function you have to be a superuser (UID 0).
Note: We recommend that you copy the script /samples/mountx into your bin directory so that it is available in the standard program search path.

D1ANDRE @ SC67:/>/samples/mountx /usr/lpp/lotus 'OMVS.SC67.DDOMINO5.PROD.HFS' OMVS.SC67.DOMINOR5.PROD.HFS is now mounted at /usr/lpp/lotus D1ANDRE @ SC67:/>
Figure 60. Mounting a file system from the OS/390 UNIX shell

The OMVS ISHELL provides an ISPF interface to manage hierarchical file systems (see Figure 61). This also requires superuser authority.

132

Lotus Domino for S/390 R5 Installation, Customization and Administration

This is screen.. . . . . . . . . . . . . . . . . . . . . . . File Directory Special_file Tools File_systems Options Setup Help ------------------------------------- _____________________ -------------OpenMVS I | 1. Mount table... | | 2. New... | Enter a pathname and do one of these: | 3. Mount(O)... | ______________________ - Press Enter. - Select an action bar choice. - Specify an action code or command on the command line. Return to this panel to work with a different pathname. More: /u/d1andre ________________________________________________________________ ________________________________________________________________ ________________________________________________________________ +

Command ===> ______________________________________________________________ F1=Help F3=Exit F5=Retrieve F6=Keyshelp F7=Backward F8=Forward


Figure 61. HFS handling from the ISHELL

9.2.2 Logon with the server user ID


The server runs from a UNIX user ID that is logged on to OS/390 UNIX System Services. You therefore need to logon using the server user ID. You can do this from a terminal using rlogin or Telnet or TSO. Please keep in mind that operating the server from a TSO OMVS session is not supported.
Note: The server user ID has specific security recommendations. It should not have superuser authority (UID=0). It needs to have authority to access the Domino Server HFS data sets.

You can also logon with your own user ID and then switch to the server user ID using the command su <server_id>. Then you must have all necessary environment variables set in your own .profile. For setting up the new shell, the su command does not read the .profile of the user you switch to. Our recommendation is to directly logon with the user ID of the Domino Server that will be started.
9.2.2.1 Logon using TSO and OMVS (not recommended) To run the server from a TSO screen, logon to TSO using the server user ID. Then enter the TSO command OMVS. You will see the standard UNIX shell shown in Figure 62 on page 134.

Start, stop and monitor the server

133

IBM Licensed Material - Property of IBM 5645-001 (C) Copyright IBM Corp. 1993, 1997 (C) Copyright Mortice Kern Systems, Inc., 1985, 1996. (C) Copyright Software Development Group, University of Waterloo, 1989. All Rights Reserved. U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or Disclosure restricted by GSA-ADP schedule contract with IBM Corp. IBM is a registered trademark of the IBM Corp. # -- -- --- -- - - - - - - - - - - - - - - - Improve performance by preventing the propagation of TSO/E or ISPF STEPLIBs -- -- --- -- - - - - - - - - - - - - - - - -

===> ESC=

1=Help 7=BackScr

2=SubCmd 8=Scroll

INPUT 3=HlpRetrn 4=Top 5=Bottom 6=TSO 9=NextSess 10=Refresh 11=FwdRetr 12=Retrieve

Figure 62. Using the OMVS shell

9.2.2.2 Logon using rlogin or Telnet You can logon to the OS/390 UNIX shell from a UNIX workstation or PC using the rlogin or Telnet commands. Before doing this you must have the inetd daemon running in UNIX System Services. A typical login command sequence is shown in Figure 63 on page 134

If you have only one TCP/IP stack running, you probably will have to specify the port number with the telnet command. When your inetd daemon listens on port 5032 for Telnet requests, the command looks like the following:
telnet wtsc67oe 5032 >telnet wtsc67oe.itso.ibm.com EZYTE27I login: domino1 EZYTE28I domino1 Password:xxxxxx (C) Copyright Software Development Group, University of Waterloo, 1989. All Rights Reserved. U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or Disclosure restricted by GSA-ADP schedule contract with IBM Corp. IBM is a registered trademark of the IBM Corp. - -- -- --- -- - - - - - - - - - - - - - - - - Improve performance by preventing the propagation - of TSO/E or ISPF STEPLIBs - -- -- --- -- - - - - - - - - - - - - - - - DOMINO1 @ SC67:/u/domino1>
Figure 63. Login using Telnet

9.2.3 Starting the server


To start the server, type the commands:
134
Lotus Domino for S/390 R5 Installation, Customization and Administration

DOMINO1 @ SC67:/u/domino1> DOMINO1 @ SC67:/u/domino1>cd /domino1/notesdata DOMINO1 @ SC67:/domino1/notesdata>/usr/lpp/lotus/bin/server


Figure 64. Commands to start the Domino Server

Replace /domino1/notesdata with the notesdata directory name for the server you wish to start. Because we had multiple servers running, we chose the following naming convention for the notesdata directories: /server_name/notesdata. You should see output on the server screen that looks similar to Figure 65 on page 135.
Note: The list of server task messages is different when starting an R4 server. However, look for the message Database Server Started, which still shows that the server has started successfully.

DOMINO1 @ SC67:/>cd /domino1/notesdata DOMINO1 @ SC67:/domino1/notesdata>/usr/lpp/bin/server Lotus Domino (r) Server, Build 5.0a.03 (Intl), 3 June 1999 Copyright (c) 1985-1999, Lotus Development Corporation, All Rights Reserved Performing consistency check on log.nsf... 06/12/99 05:47:08 PM Begin scan of databases to be consistency checked 06/12/99 05:47:12 PM End scan of databases: 27 found 06/12/99 05:47:13 PM Region size is 1967108096 (< 2G) 06/12/99 05:47:17 PM Mail Router started for domain ITSO 06/12/99 05:47:17 PM Router: Internet SMTP host domino1 in domain itso.ibm.com 06/12/99 05:47:21 PM Database Replicator started 06/12/99 05:47:26 PM Index update process started 06/12/99 05:47:32 PM Agent Manager started 06/12/99 05:47:37 PM Domino1/Itso is the Administration Server of the Domino Directory. 06/12/99 05:47:37 PM JVM: Java Virtual Machine initialized. 06/12/99 05:47:37 PM AMgr: Executive '1' started 06/12/99 05:47:37 PM Administration Process started 06/12/99 05:47:42 PM Calendar Connector started 06/12/99 05:47:47 PM Schedule Manager started 06/12/99 05:47:47 PM SchedMgr: Validating Schedule Database 06/12/99 05:47:49 PM SchedMgr: Done validating Schedule Database 06/12/99 05:47:52 PM Event Dispatcher started 06/12/99 05:47:53 PM Releasing unused storage in database statrep.nsf... 06/12/99 06/12/99 06/12/99 06/12/99 06/12/99 06/12/99 > 05:47:57 05:48:07 05:48:13 05:48:13 05:48:13 05:48:17 PM PM PM PM PM PM Stats agent started Maps Extractor started Maps Extractor: Building Maps profile Maps Extractor: Maps profile built OK SMTP Server: Started Database Server started

Figure 65. Console display as R5 server starts

When you see the message Database Server started, the server is running. You can now connect to the server from a Lotus Notes Client. To display the status of the server, see 9.5, Monitoring the status of the server on page 148.

Start, stop and monitor the server

135

If nothing happens when you issue the server command, or if you get a failure, you need to clean up the server processes and semaphores before you try again. See 9.6, What to do if the server does not start or stop on page 155. You cannot start a Domino Server twice with the same user ID. That will result in the message shown in Figure 66.

DOMINO1 @ SC67:/domino1/notesdata>/usr/lpp/lotus/bin/server Server exiting: The Notes Data Directory is in use by another Notes program (possibly on another computer). You must first shut down all Notes programs (for example, the Admin istration program) that share this Data Directory. DOMINO1 @ SC67:/domino1/notesdata>
Figure 66. Error when starting a server twice

9.3 Starting the server in the background using rc.notes


Using Telnet or rlogin starts the server in the foreground, which means your Telnet or rlogin session will become the server console. If you lose this session due to some abnormal occurrence, you lose the Domino Server console. Then your server log can only be viewed with the Domino R5 Administrator client or by opening the noteslog database (log.nsf) with a Notes client. For that reason, a shell script called rc.notes is provided to start the Domino Server in the background and redirect the standard input and output to files. You find the script in the directory /usr/lpp/lotus/notes/latest/os390, with a symbolic link to it in /usr/lpp/lotus/bin/tools. The rc.notes script makes it possible to automate the start of the Domino Server by including it into the UNIX initialization script /etc/rc. Running rc.notes this way would imply that it is executed with UID 0 and not with the user ID of the Domino Server. To circumvent this problem it is possible to create a started procedure using the BPXBATCH utility to start rc.notes. The correct user ID would be provided through a RACF-started class profile. Before you can use rc.notes it has to be customized to fit your installation.

9.3.1 Customization for rc.notes


To customize rc.notes you should understand how Domino handles standard input and standard output. When you start the Domino Server from a Telnet session, standard input will be the keyboard of your workstation and standard output the display of your workstation. To run your server in the background, which means without a direct terminal connection, standard input and output can be redirected to files (see Figure 67 on page 137). Therefore, to use this concept you have to perform the following steps: Logon to the OS/390 UNIX environment. Create a directory named noteslog. Create a file named notes.input for standard input. Create a file named notes.log for standard output (the servers log).

136

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 68 on page 137 shows an example of how to create the necessary files. The names are based on the configuration used during the writing of this redbook. The files were created by a user with UID 0. The owner of the files must be changed to the user ID of the Domino Server. Otherwise, the server would not have the authority to write to the notes.log file. If you use the user ID of the Domino Server for these steps, you will not have to change the owner.

Workstation
/notesdata/noteslog

rlogin/ telnet

standard output

standard input

Domino Server

notes.log notes.input

Figure 67. Domino standard input and output

D1ANDRE @ SC67:/>cd /domino3/notesdata D1ANDRE @ SC67:/domino3/notesdata>mkdir noteslog D1ANDRE @ SC67:/domino3/notesdata>cd noteslog D1ANDRE @ SC67:/domino3/notesdata/noteslog>touch notes.input D1ANDRE @ SC67:/domino3/notesdata/noteslog>touch notes.log D1ANDRE @ SC67:/domino3/notesdata/noteslog>ls -al total 56 drwxr-xr-x 2 STC OEDOMINO 0 Jun 14 20:14 . drwxr-xr-x 6 DOMINO3 OEDOMINO 0 Jun 14 20:13 .. -rw-r--r-- 1 DOMINO3 OEDOMINO 0 Jun 14 20:14 notes.input -rw-r--r-- 1 DOMINO3 OEDOMINO 0 Jun 14 20:14 notes.log D1ANDRE @ SC67:/domino3/notesdata/noteslog>cd /domino3/notesdata D1ANDRE @ SC67:/domino3/notesdata>chown -R DOMINO3:OEDOMINO noteslog
Figure 68. Creating the files for rc.notes

The rc.notes script will establish the redirection of standard input and output for the Domino Server. It has to be customized to reflect the names used for the directory and the input and output file (see Figure 68). In our test environment we had to change the NOTESDATAD variable (see Figure 69 on page 138) as we ran multiple Domino Servers on a single system.
Note: Make sure that the file notes.input has proper permission bits. By appending the string quit (server command to shut down the server) to this file using ISHELL or a shell script, the server will shut down. Therefore, only the server user ID should have write access.

Start, stop and monitor the server

137

######################################################################## # # # Sample OS390 Lotus Domino Server Startup Script # # # # This script starts the OS/390 Lotus Domino Server as a background # # task, redirecting both input and output. # # # ######################################################################## # # # Notes Input/Output Files # # # # NOTESDATAD -> set to your notes data directory # # NOTESINPUT -> set to the file to be used for notes input # # NOTESOUTPUT -> set to the file to contain the notes console ouput # # NOTESBINDIR -> set to the location of the notes executables # # # ######################################################################## NOTESDATAD=/domino1/notesdata NOTESINPUT=$NOTESDATAD/noteslog/notes.input NOTESOUTPUT=$NOTESDATAD/noteslog/notes.log NOTESBINDIR=/usr/lpp/lotus/notes/latest/os390 NOTESTOOLDIR=/usr/lpp/lotus/bin # # Obtain Current userid # userid=$(id -un) # # Check for existance of the server # if [ ! -x $NOTESBINDIR/server ] then echo "server: Cannot access server command - exiting" exit 1 fi # # Check for the Data Directory # if [ ! -d $NOTESDATAD ] then echo "server: Cannot access $NOTESDATAD directory - exiting" exit 1 fi
Figure 69. Server startup script rc.notes - part 1

138

Lotus Domino for S/390 R5 Installation, Customization and Administration

# # Check for the Data Directory # if [ ! -d $NOTESDATAD ] then echo "server: Cannot access $NOTESDATAD directory - exiting" exit 1 fi # # Check for the Data Directory/noteslog directory # if [ ! -d $(dirname $NOTESOUTPUT) ] then echo "server: Cannot access $(dirname $NOTESOUTPUT) directory - exiting" exit 1 fi # # Save the old console log # mv $NOTESOUTPUT $NOTESOUTPUT.$(date +%m%d).$(date +%H%M%S) # # Create a new input file and issue a show tasks. # When the results of the show tasks command shows up, the # server has completed its initialization. # rm $NOTESINPUT touch $NOTESINPUT echo " show tasks" >> $NOTESINPUT # # Change to the Data Directory # cd $NOTESDATAD # # Start the server # echo "Starting Domino for S/390" $NOTESTOOLDIR/server $userid $NOTESDATAD < $NOTESINPUT > $NOTESOUTPUT 2>&1 &
Figure 70. Server startup script rc.notes - part 2

The script rc.notes has some restrictions you should be aware of: By default, there is just one instance of the script, which means that only one server can be started. If you have multiple servers running on the same machine, you could have a copy of rc.notes in each notes data directory. Each Domino Server has its own RACF user ID. To start a server, logon to your UNIX environment with its user ID and call the rc.notes script that is dedicated to this server. Make sure that the shell environment has been set up. Switching to the user ID with the su command does not necessarily do this.

Start, stop and monitor the server

139

9.3.2 Starting the server with rc.notes


To start the server with rc.notes, logon to your OS/390 UNIX environment with the user ID of the Domino Server and call the script (see Figure 71)
DOMINO3 @ SC67:/domino3/notesdata>/usr/lpp/lotus/bin/tools/rc.notes Starting Domino for S/390 DOMINO3 @ SC67:/domino3/notesdata>

Figure 71. Starting the server in the background

As you dont have a server console, make sure that the server really comes up by checking the content of the file notes.log (see Figure 72). As notes.log is a text file you can use the ISHELL or one of the shell utilities more, cat or tail to browse it. If the server doesnt start, see 9.6, What to do if the server does not start or stop on page 155.

D1ANDRE @ SC67:/>cd /domino1/notesdata/noteslog D1ANDRE @ SC67:/domino1/notesdata/noteslog>more notes.log Lotus Domino (r) Server, Build 5.0a.03 (Intl), 3 June 1999 Copyright (c) 1985-1999, Lotus Development Corporation, All Rights Reserved 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 12:04:52 12:04:53 12:04:55 12:04:57 12:04:57 PM PM PM PM PM Begin scan of databases to be consistency checked End scan of databases: 24 found Cluster Administration Process started DNS Resolver failed to initialize.: DNS resolver error Mail Router started for domain ITSO

Figure 72. Check the notes.log after starting the server

9.4 Stopping the server


When the server has been started successfully, you have different options for stopping the server, depending on the way it was started: Domino Server console (Telnet/rlogin session) Concom Character console (cconsole) Domino Web Administration Domino Administrator client This chapter only describes some basic console commands for the Domino Server. For a more detailed summary of the administrative tasks, see Chapter 16, Simple administration tasks on page 325.

9.4.1 Stopping the server from the server console


When the server was started from a Telnet or rlogin session, this session becomes the Domino Server console. To stop the server from the server console, enter either quit or exit. You should see the messages in Figure 73 on page 141.

140

Lotus Domino for S/390 R5 Installation, Customization and Administration

06/15/99 > quit 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99 06/15/99

05:37:46 PM Database Server started 05:37:57 05:37:57 05:37:57 05:37:57 05:37:57 05:37:57 05:37:58 05:37:58 05:38:00 05:38:01 05:38:02 05:38:02 05:38:03 05:38:03 05:38:03 05:38:03 05:38:11 05:38:13 05:38:13 PM PM PM PM PM PM PM PM PM PM PM PM PM PM PM PM PM PM PM Starting Server shutdown Database Replicator shutdown Router: Shutdown is in progress Schedule Manager shutdown complete AMgr: Executive '1' shutting down Agent Manager shutdown complete IMAP Server: Waiting for all tasks to complete SMTP Server: Waiting for all tasks to complete Index update process shutdown Administration Process shutdown Mail Router shutdown Event Dispatcher shutdown IMAP Server: All tasks have completed IMAP Server: Shutdown SMTP Server: All tasks have completed SMTP Server: Shutdown HTTP Web Server shutdown Stats agent shutdown Server shutdown complete

Figure 73. Console display as the server stops

Then log off from UNIX System Services using the command exit. This command works from both the UNIX System Services TSO Shell (OMVS) and an rlogin or Telnet session.
Note: If the server does not shut down completely, or is not responding, see 9.6, What to do if the server does not start or stop on page 155.

9.4.2 Stopping the server using the concom utility


When you use a script like rc.notes to start the Domino Server in the background, Domino console commands can be issued by using the utility concom. You will find this utility in /usr/lpp/lotus/notes/latest/os390, with a symbolic link to it in /usr/lpp/lotus/bin/tools. Before you can use concom, customize it to fit your Domino installation. Make sure that the changes match those for rc.notes in 9.3.1, Customization for rc.notes on page 136. An example of the concom utility we used for the server DOMINO1 is shown in Figure 74 on page 142. In terms of multiple (partitioned) servers, concom has the same restrictions as rc.notes (see The script rc.notes has some restrictions you should be aware of: on page 139).

Start, stop and monitor the server

141

######################################################################## # Sample OS390 Lotus Domino Server Console Command Submission # # This script submits commands to the server console running in the # # background. (ie. a server started with rc.notes). # # Issue: # # concom <server cmd string> # # If the server command contains a double quote (e.g. broadcast) # # then the quote should be escaped (\") For example: # # concom broadcast \"Great weather we are having...\" # ######################################################################## # Notes Input/Output Files # # NOTESDATAD -> set to your notes data directory # # NOTESINPUT -> set to the file to be used for notes input # # NOTESOUTPUT -> set to the file to contain the notes console ouput # # NOTESBINDIR -> set to the location of the notes executables # ######################################################################## NOTESDATAD='/domino1/notesdata' NOTESINPUT=$NOTESDATAD'/noteslog/notes.input' NOTESOUTPUT=$NOTESDATAD'/noteslog/notes.log' NOTESBINDIR='/usr/lpp/lotus/bin' # # How long to sleep??? SLEEP_SECS="1" # # Find out how many lines are in the log now... START_LINES=$(cat $NOTESOUTPUT | wc -l) # # Put command into input file... echo "Submitting '$@' to Notes Input Stream" echo "$@" >> $NOTESINPUT # # Sleep a couple of seconds to allow the command to complete # # echo "Sleeping for $SLEEP_SECS second(s) " sleep $SLEEP_SECS # # Now how may lines in the log??? # END_LINES=$(cat $NOTESOUTPUT | wc -l) # That make how many new lines added??? # DIFF_LINES=$(($END_LINES -$START_LINES)) # # Show that many lines from the end of the log.... # tail '-'$DIFF_LINES $NOTESOUTPUT
Figure 74. The concom utility for server DOMINO1

Figure 74 shows how to use concom to issue a server command and stop the server. The syntax is: concom <server command>. You will not get a confirmation that the server stopped. So change to the noteslog directory and browse the file notes.log. The last append should be: Server shutdown complete .

142

Lotus Domino for S/390 R5 Installation, Customization and Administration

Note: We found concom useful only in a test environment, as it just relies on UNIX security. Every user who can execute concom and has write permission to the file notes.input can stop the Domino Server. Our recommendation is to use a tool that asks for the Domino administrator ID, like cconsole (see 9.4.3, Stopping the server using the character console on page 143).

DOMINO1 @ SC67:/domino1/notesdata>rc.notes Starting Domino for S/390 DOMINO1 @ SC67:/domino1/notesdata>concom show server Submitting 'show server' to Notes Input Stream Sleeping for 1 second(s) > show server Lotus Domino (r) Server (Build 5.0a.03 (Intl) for UNIX) 06/16/99 10:02:31 AM Server name: domino1/Itso Server directory: /domino1/notesdata Partition: .domino1.notesdata Elapsed time: 00:01:31 Transactions/minute: Last minute: 0; Last hour: 0; Peak: 0 Peak # of sessions: 0 at Transactions: 0 Availability Index: 100 (state: AVAILABLE) Message Tracking: Not Enabled Shared mail: Not Enabled Number of Mailboxes: 1 Pending mail: 0 Dead mail: 0 Waiting Tasks: 0 Transactional Logging: Not Enabled DOMINO1 @ SC67:/domino1/notesdata>concom quit Submitting 'quit' to Notes Input Stream Sleeping for 1 second(s) quit DOMINO1 @ SC67:/domino1/notesdata> cd noteslog DOMINO1 @ SC67:/domino1/notesdata/noteslog> tail notes.log 06/16/99 09:59:33 AM IMAP Server: All tasks have completed 06/16/99 09:59:33 AM IMAP Server: Shutdown 06/16/99 09:59:45 AM Stats agent shutdown 06/16/99 09:59:46 AM HTTP Web Server shutdown 06/16/99 09:59:46 AM Server shutdown complete
Figure 75. Using concom

9.4.3 Stopping the server using the character console


Domino Release 5 provides a new function to issue server commands and to reconnect to the server console: cconsole. This utility is available on Domino UNIX platforms and is much more secure than concom because you have to authenticate with a Domino ID with administrator rights. To use cconsole, you must have the Domino server ID file accessible in an HFS directory. If it is not stored on a local disk on your workstation, it can be detached from the Domino Directory (NAB) and uploaded to the UNIX HFS using FTP. To start cconsole, change to the notesdata directory of the server you want to manage. See Figure 78 on page 145 for an example to shutdown the server DOMINO1 in our test environment.

Start, stop and monitor the server

143

D1ANDRE @ SC67:/>cd /domino1/notesdata D1ANDRE @ SC67:/domino1/notesdata>cconsole -l Domino Character Console v0.0 Warning: You are remotely connected to host SC67. If you have not taken precautions to secure this connection, passwords will be exposed over the network. Do you want to end this cconsole session? [y/n] n Enter the full path to your ID file: /domino1/notesdata/admin.id Enter your password: 06/16/99 11:33:00 AM Initiating cconsole on SC67 > sh server Lotus Domino (r) Server (Build 5.0a.03 (Intl) for UNIX) 06/16/99 11:33:09 AM Server name: Domino1/Itso Server directory: /domino1/notesdata Partition: .domino1.notesdata Elapsed time: 00:03:53 Transactions/minute: Last minute: 0; Last hour: 18; Peak: 36 Peak # of sessions: 2 at 06/16/99 11:30:31 AM Transactions: 38 Availability Index: 100 (state: AVAILABLE) Message Tracking: Not Enabled Shared mail: Not Enabled Number of Mailboxes: 4 Pending mail: 2 Dead mail: 0 Waiting Tasks: 0 Transactional Logging: Not Enabled > quit Warning: You entered the command to shutdown the Domino server. (Use the "done" command to stop the console without server shutdown.) Do you really want to shutdown the Domino server? [y/n] y 06/16/99 11:33:22 AM BROADCAST from Domino1/Itso: Domino server exiting > 06/16/99 11:33:28 AM Ending cconsole on SC67. D1ANDRE @ SC67:/domino1/notesdata>
Figure 76. Using the character console utility cconsole

If you want to stop cconsole without shutting down the server: Issue the cconsole command done. Press Ctrl-c 16.4.1, Starting the Domino Character Console on page 351 contains a description of cconsole command line parameters.
Note: OS/390 UNIX Telnet does not have the capability to provide encryption of the data stream like, for example, the TN3270 server . When authenticating as an administrator using cconsole, the password therefore will be exposed over the network.

9.4.4 Stopping the server from the Domino Administrator client


To shut the server down from the administration client, use the following commands: 1. Start the Domino Administrator client on your workstation screen and select the server you want to administer (see Figure 77) by clicking File -> Open Server.

144

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 77. Selecting a server to administer in the Domino Administrator

2. In the server menu on the right side select Shutdown as shown in Figure 78.

Figure 78. Shutting down the server with the Domino Administrator

Start, stop and monitor the server

145

The Domino Administrator also provides the server console function to send commands to the server. To use it, follow the next steps: 1. Load the Domino Administrator client and select see server as shown in Figure 79.

Figure 79. Loading the server console

2. Enter either quit or exit in the server console command field and press Enter (see Figure 80).

Figure 80. Server shutdown with the live console

146

Lotus Domino for S/390 R5 Installation, Customization and Administration

3. Load the server console by clicking Console (see Figure 79 on page 146).
Note: You can use the server console to send other commands to a server. Refer to the Domino R5 Administration Help database for additional information on server commands.

9.4.5 Stopping the server using the Web Administrator


If you do not have a Domino Administrator client available, you can use a Web browser and the Domino Web Administrator to shut down the server. For this to work, the http task of the Domino Server has to be configured properly as described in chapter Chapter 10, Lotus Domino R5 and the Internet on page 163. 1. Open your Web browser and specify the URL http://<servername>/webadmin.nsf, where <servername> is the hostname or the IP address of your Domino Server. If the http task is configured not to run on the well known port, the URL will look like this:
http://<servername>:<port>/webadmin.nsf

2. You will be prompted for the Domino administrator ID and password. After a successful authentication you will get the Web administrator screen as shown in Figure 81.

Figure 81. Domino Web Administrator

1. Select Console from the administration menu on the left to load the server console.

Start, stop and monitor the server

147

Figure 82. Stopping the server with the Domino Web Administrator

1. Enter quit or exit in the Domino console command field and click Send as shown in Figure 82.

9.5 Monitoring the status of the server


It may be necessary to check the status of the server. This section shows some commands that may be of use.

9.5.1 From an OS/390 console


The MVS command D A,L shows all of the active address spaces. Figure 83 on page 149 shows sample output.

148

Lotus Domino for S/390 R5 Installation, Customization and Administration

SDSF DA SC67 SC67 PAG 0 SIO 14 CPU 16/ 11 COMMAND ISSUED COMMAND INPUT ===> D A,L SCROLL === RESPONSE=SC67 IEE114I 18.16.15 1999.167 ACTIVITY 690 JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM OAS 00025 00033 00003 00028 00114 00003/00030 00039 LLA LLA LLA NSW S JES2 JES2 IEFPROC NSW S VTAM44 VTAM44 NET NSW S DFSMSHSM HSMSC67 DFSMSHSM NSW S VLF VLF VLF NSW S RMF RMF IEFPROC NSW S APPC APPC APPC NSW S ASCH ASCH ASCH NSW S RRS RRS RRS NSW S IHV IHV PSTEP01 OWT S SDSF SDSF SDSF NSW S DFRMM DFRMM IEFPROC NSW S OAM OAM IEFPROC NSW S OPTSO OPTSO OPTSO OWT S RUNCF RUNCF IEFPROC NSW S RACF RACF RACF NSW S TSO TSO STEP1 OWT S TCPIPMVS TCPIPMVS TCPIP NSW SO TCPIPOE TCPIPOE TCPIP NSW SO INETD1 STEP1 OMVSKERN OWT AO D1ANDRE5 STEP1 D1ANDRE IN AO DOMINO3 STEP1 DOMINO3 IN AO DOMINO31 STEP1 DOMINO3 OWT AO DOMINO37 STEP1 DOMINO3 IN AO DOMINO38 STEP1 DOMINO3 IN AO DOMINO39 STEP1 DOMINO3 OWT AO DOMINO31 STEP1 DOMINO3 IN AO DOMINO32 STEP1 DOMINO3 IN AO DOMINO33 STEP1 DOMINO3 IN AO DOMINO33 STEP1 DOMINO3 IN AO DOMINO34 STEP1 DOMINO3 IN AO DOMINO35 STEP1 DOMINO3 IN AO DOMINO36 STEP1 DOMINO3 IN AO DOMINO37 STEP1 DOMINO3 IN AO
Figure 83. MVS console display of address spaces

The address spaces of the Domino Server are prefixed with the user ID that started the Notes server. In Figure 83, this was DOMINO3. The MVS command D OMVS,U=DOMINO3 shows the OMVS processes related to the user ID of the Domino Server. Figure 84 on page 150 shows sample output. The command D OMVS,A=ALL could be used to see all processes in the OS/390 UNIX environment.

Start, stop and monitor the server

149

COMMAND INPUT ===> D OMVS,U=DOMINO3 SCROLL === RESPONSE=SC67 BPXO040I 18.18.42 DISPLAY OMVS 694 OMVS 000F ACTIVE OMVS=(6C) USER JOBNAME ASID PID PPID STATE START CT_SECS DOMINO3 DOMINO31 009A 1761607689 1761607722 1WI 18.14.48 1.365 LATCHWAITPID= 0 CMD=sh -L DOMINO3 DOMINO32 00C6 687865866 469762129 1S 18.15.15 1.904 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/amgr DOMINO3 DOMINO32 00BD 721420299 469762129 HS 18.16.03 .833 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/smtp DOMINO3 DOMINO36 00C0 520093709 469762129 1S 18.15.37 .512 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/stats DOMINO3 DOMINO37 00BB 1392508942 469762129 HS 18.15.42 3.085 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/http DOMINO3 DOMINO33 00AA 637534234 687865866 HD 18.15.16 1.496 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/amgr DOMINO3 DOMINO3 00A3 1761607722 167772223 1W 17.13.16 8.988 LATCHWAITPID= 0 CMD=sh -L DOMINO3 DOMINO38 00C5 536870973 469762129 1S 18.14.58 .889 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/router DOMINO3 DOMINO3 00A3 167772223 16777238 1F 17.13.05 8.988 LATCHWAITPID= 0 CMD=otelnetd -Y 9.12.2.165 -p domino3 -a vt1 DOMINO3 DOMINO39 00A8 1761607749 469762129 HS 18.15.53 .907 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/pop3 DOMINO3 DOMINO31 00AC 1308622920 469762129 1SI 18.15.09 .488 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/update DOMINO3 DOMINO31 009F 1291845710 469762129 HS 18.15.58 2.200 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/nntp DOMINO3 DOMINO35 00AF 1157627983 469762129 HS 18.15.31 2.225 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/event DOMINO3 DOMINO37 00AB 469762129 1761607689 HS 18.14.51 7.749 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/server DOMINO3 DOMINO38 00B8 1778384978 469762129 HS 18.15.48 .835 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/imap DOMINO3 DOMINO39 00BA 1291845715 469762129 1S 18.15.04 .283 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/replic DOMINO3 DOMINO33 00B3 1442840661 469762129 1S 18.15.20 1.050
Figure 84. MVS console display of address spaces - sample output

9.5.2 From the UNIX System Services environment


From UNIX System Services the command ps -ef displays information about all UNIX processes. Figure 85 on page 151 shows sample output.

150

Lotus Domino for S/390 R5 Installation, Customization and Administration

D1ANDRE @ SC67:/u/d1andre> ps -ef UID PID PPID C STIME TTY TIME CMD STC 1 0 - Jun 15 ? 0:06 STC 16777222 1 - Jun 15 ? 5:17 STC 754974731 16777275 - 18:45:34 ttyp0001 0:01 STC 16777232 1 - Jun 15 ? 6:10 STC 16777238 1 - Jun 15 ? 0:00 STC 16777239 1 - Jun 15 ? 0:00 STC 27 1 - Jun 15 ? 0:00 STC 28 1 - Jun 15 ? 0:00 STC 29 1 - Jun 15 ? 0:00 STC 30 1 - Jun 15 ? 0:00 DOMINO1 1560281135 352321604 - 18:39:10 ttyp0000 0:03 /usr/lpp/lotus/notes/latest/os390/cldbdir STC 889192496 1 - 12:11:16 ? 12:20 DOMINO1 1258291249 352321604 - 18:39:00 ttyp0000 0:03 /usr/lpp/lotus/notes/latest/os390/http DOMINO1 50331699 352321604 - 18:38:15 ttyp0000 0:00 /usr/lpp/lotus/notes/latest/os390/replica DOMINO1 822083636 352321604 - 18:38:20 ttyp0000 0:00 /usr/lpp/lotus/notes/latest/os390/update DOMINO1 67108917 352321604 - 18:38:10 ttyp0000 0:01 /usr/lpp/lotus/notes/latest/os390/router DOMINO1 184549430 201326666 - 18:38:27 ttyp0000 0:01 /usr/lpp/lotus/notes/latest/os390/amgr -e 1 DOMINO1 704643127 352321604 - 18:39:05 ttyp0000 0:00 /usr/lpp/lotus/notes/latest/os390/maps DOMINO1 352321594 352321604 - 18:38:37 ttyp0000 0:00 /usr/lpp/lotus/notes/latest/os390/calconn DOMINO1 838860862 67108917 - 18:38:12 ttyp0000 0:02 /usr/lpp/lotus/notes/latest/os390/mtc DOMINO1 301989955 352321604 - 18:38:48 ttyp0000 0:04 /usr/lpp/lotus/notes/latest/os390/event DOMINO1 352321604 2097152064 - 18:37:52 ttyp0000 0:20 /usr/lpp/lotus/notes/latest/os390/server DOMINO1 2046820422 352321604 - 18:39:15 ttyp0000 0:01 /usr/lpp/lotus/notes/latest/os390/clrepl DOMINO1 989855817 352321604 - 18:38:43 ttyp0000 0:02
Figure 85. UNIX System Services display of processes

BPXPINPR EZBTCPIP ps -ef EZBTCPIP INETD OPORTMAP FTPD PORTMAP RSHD FTPD

/usr/sbin/syslogd

You can also check whether the Domino tasks are listening on their individual TCP/IP ports by using the onetstat command. If you have multiple stacks running you can specify a stack with the -p option. The standard output of the onetstat command is shown in Figure 86 on page 152. It shows the status of all TCP/IP socket connections.

Start, stop and monitor the server

151

D1ANDRE @ SC67:/domino3/notesdata> onetstat -p TCPIPOE MVS TCP/IP onetstat CS V2R6 TCPIP Name: TCPIPOE User Id Conn Local Socket Foreign Socket ------- ---- ------------------------DOMINO12 03B08 9.12.2.28..25 0.0.0.0..0 DOMINO14 03AE0 9.12.2.28..1352 0.0.0.0..0 DOMINO17 03AF7 9.12.2.28..80 0.0.0.0..0 DOMINO18 03B05 9.12.2.28..2744 9.12.2.28..1352 FTPDOE1 0001E 0.0.0.0..21 0.0.0.0..0 INETD1 00010 0.0.0.0..513 0.0.0.0..0 TCPIPOE 00003 0.0.0.0..1025 0.0.0.0..0 TCPIPOE 00007 127.0.0.1..1026 127.0.0.1..1025 D1ANDRE5 0144C 0.0.0.0..514 *..* D1ANDRE @ SC67:/domino3/notesdata>
Figure 86. Output of the onetstat command

10:47:30 State ----Listen Listen Listen ClosWait Listen Listen Listen Establsh UDP

To see whether the Domino server actually communicates over the TCP/IP stack, use the -b option, which shows the number of bytes transferred through the socket connections. Figure 87 and Figure 88 show the output of this command immediately after server startup and after a connection from a Notes client has been established, respectively.
D1ANDRE @ SC67:/domino3/notesdata>onetstat -b -p tcpipmvs MVS TCP/IP onetstat CS V2R6 TCPIP Name: TCPIPMVS 06/17/1999 MVS TCP/IP Real Time Network Monitor User Id B Out B In L Port Foreign Socket ------- ------------- -------------DOMINO31 0000000000 0000000000 00080 0.0.0.0..0 DOMINO32 0000000000 0000000000 00143 0.0.0.0..0 DOMINO33 0000000000 0000000000 00110 0.0.0.0..0 DOMINO34 0000000000 0000000000 00119 0.0.0.0..0 DOMINO35 0000000000 0000000000 00025 0.0.0.0..0 DOMINO39 0000000000 0000000000 01352 0.0.0.0..0 FTPDMVS1 0000000000 0000000000 00021 0.0.0.0..0 PORTMAP 0000000000 0000000000 00111 0.0.0.0..0 RXPROC 0000000000 0000000000 00514 0.0.0.0..0 RXPROC 0000000000 0000000000 00512 0.0.0.0..0 TCPIPMVS 0000000000 0000000000 01025 0.0.0.0..0 TCPIPMVS 0000001174 0000000724 01025 127.0.0.1..1026 TCPIPMVS 0000000724 0000001174 01026 127.0.0.1..1025 TCPIPMVS 0000000000 0000000000 00023 0.0.0.0..0 PORTMAP 0000000000 0000000736 00111 *..* Connections displayed: 17 D1ANDRE @ SC67:/domino3/notesdata>
Figure 87. Output of onetstat -b directly after server startup

10:32:45 State ----Listen Listen Listen Listen Listen Listen Listen Listen Listen Listen Listen Establsh Establsh Listen UDP

152

Lotus Domino for S/390 R5 Installation, Customization and Administration

D1ANDRE @ SC67:/domino3/notesdata>onetstat -b -p tcpipmvs MVS TCP/IP onetstat CS V2R6 TCPIP Name: TCPIPMVS 06/17/1999 MVS TCP/IP Real Time Network Monitor User Id B Out B In L Port Foreign Socket ------- ------------- -------------DOMINO31 0000000000 0000000000 00080 0.0.0.0..0 DOMINO32 0000000000 0000000000 00143 0.0.0.0..0 DOMINO33 0000000000 0000000000 00110 0.0.0.0..0 DOMINO34 0000000000 0000000000 00119 0.0.0.0..0 DOMINO35 0000000000 0000000000 00025 0.0.0.0..0 DOMINO39 0000000000 0000000000 01352 0.0.0.0..0 DOMINO39 0000082524 0000000882 01352 9.12.2.165..2075 FTPDMVS1 0000000000 0000000000 00021 0.0.0.0..0 PORTMAP 0000000000 0000000000 00111 0.0.0.0..0 RXPROC 0000000000 0000000000 00512 0.0.0.0..0 RXPROC 0000000000 0000000000 00514 0.0.0.0..0 TCPIPMVS 0000001174 0000000724 01025 127.0.0.1..1026 TCPIPMVS 0000000000 0000000000 01025 0.0.0.0..0 TCPIPMVS 0000000724 0000001174 01026 127.0.0.1..1025 TCPIPMVS 0000000000 0000000000 00023 0.0.0.0..0 PORTMAP 0000000000 0000000736 00111 *..* TCPIPMVS 0000000102 0000000000 03267 *..* Connections displayed: 19 D1ANDRE @ SC67:/domino3/notesdata>
Figure 88. Output of command onetstat -b after connection establishment

10:37:00 State ----Listen Listen Listen Listen Listen Listen Establsh Listen Listen Listen Listen Establsh Listen Establsh Listen UDP UDP

9.5.3 From the server


There are various commands that can be issued to the Domino Server. These can be entered on all available consoles described throughout this chapter, like Domino Administrator, cconsole, etc. Two useful commands are show tasks and show users. Following is sample output from the show tasks command.

Start, stop and monitor the server

153

> show tasks Lotus Domino (r) Server (Build 5.0a.03 (Intl) for UNIX) 06/16/99 07:09:48 PM Server name: Server directory: Partition: Elapsed time: Transactions/minute: Peak # of sessions: Transactions: Availability Index: Message Tracking: Shared mail: Number of Mailboxes: Pending mail: 3 Waiting Tasks: Transactional Logging: Task Database Server Database Server Database Server Database Server Database Server Database Server Database Server Database Server Database Server Database Server SMTP Server SMTP Server Cluster Replicator Cluster Directory Maps Extractor HTTP Web Server Stats Event Monitor Schedule Manager Calendar Connector Admin Process Agent Manager Agent Manager Indexer Replicator MT Collector Router Domino1/Itso /domino1/notesdata .domino1.notesdata 00:31:51 Last minute: 4; Last hour: 12; Peak: 119 4 at 06/16/99 07:05:19 PM 358 100 (state: AVAILABLE) Enabled Not Enabled 4 Dead mail: 0 0 Not Enabled

Description Perform console commands Listen for connect requests on TCPIP Cluster Manager is idle Load Monitor is idle Server for Notes Admin/Itso on TCPIP Server for Domino1/Itso on TCPIP Idle task Idle task Perform Database Cache maintenance Idle task Listen for connect requests on TCP Port:25 Control task Idle Idle Idle Listening on port(s) 80 Idle Idle Idle Idle Idle Executive '1': Idle Idle Idle Idle Idle, collection interval is 900 seconds, next collection Idle

Figure 89. Output from the show tasks command

Following is sample output from the show users command.

> show user User Name Notes Admin/Itso

Databases Open

Minutes Since Last Used

Figure 90. Output from the show users command

To get a list of available server commands, issue help from the server console (see Figure 91 on page 155).

154

Lotus Domino for S/390 R5 Installation, Customization and Administration

> help BROADCAST "msg" ["user"] Broadcast a message to user(s) of this server DBCACHE Database Cache management commands DISABLE Disable use of database cache FLUSH Clear out database cache SHOW Show contents of database cache DROP ["username"] [ALL] Drop one or more sessions EXIT [password] Exit server HELP Help (Displays this help information) LOAD pgmname Load program PULL servername Replicate one-way (pull) PUSH servername Replicate one-way (push) QUIT [password] Quit (exit server) REPLICATE servername Replicate two-way request RESTART Restart information: SERVER [password] Restart Server PORT portname Disable/Enable transactions on port ROUTE servername Route mail to server SET Set server option: CONFIGURATION "variable=value" Configuration variable SECURE [current-password] [new-password] Secure Console Password STAT [Facility] [Statname] Reset statistics SHOW Show server information: ALLPORTS Show configuration for all ports CLUSTER Cluster information CONFIGURATION variable Configuration variable DATABASE filename Show Database Information DBS Show Open Database Information DIRECTORY Directory Information DISKSPACE filesystem Available disk space MEMORY Memory information PORT portname Port specific information SCHEDULE Next Schedule [Server/Program/Location] [Appl] SERVER Server information STATISTIC variable Statistic variable TASKS Server tasks USERS Users with open sessions START Starts the specified service PORT portname Enable transactions on port STOP PORT Stops the specified service PORT portname Disable transactions on port TELL taskname command-string Send command-string to a task TRACE servername Trace server connection

Figure 91. List of available server consol commands

9.6 What to do if the server does not start or stop


If the Domino Server crashes, does not stop completely, or fails to restart, you may have problems with shared memory and semaphores. The Domino Server uses shared memory. The shared memory resides in data spaces that are managed by the OS/390 UNIX Kernel. The shared memory is retained even if you cancel the Domino Server address spaces. Therefore, you must have a method to clean up this shared memory in the event of Domino abnormally terminating.

Start, stop and monitor the server

155

9.6.1 Terminating the server with nsd -kill


Domino R5 no longer provides the killnotes script for terminating the server. Killnotes has been replaced by a more powerful diagnostic utility called nsd. This utility is available for Domino on UNIX platforms. To remove Domino processes, memory and semaphores, run the shell script
/usr/lpp/lotus/bin/nsd with the -kill option. This is shown in Figure 92 on page

157. You must be in the Domino Notes data directory when you run this script and be logged on with the user ID of the Domino Server you want to terminate. Nsd places temporary files in the directory /tmp/nsd.<serverid>, where <serverid> is the user ID of the Domino Server. Make sure that this user ID has write access to /tmp.

156

Lotus Domino for S/390 R5 Installation, Customization and Administration

DOMINO3 @ SC67:/> cd /domino3/notesdata DOMINO3 @ SC67:/domino3/notesdata>nsd -kill INFO: Using cache file /tmp/nsd.DOMINO3/nsd_3.2.7_cache.ins Script Version : nsd 3.2.7 Notes Version : Notes Base : UNKNOWN Data Dir : /domino3/notesdata Notes Exec Dir : /usr/lpp/lotus/notes/latest/os390 Search Path : /usr/lpp/lotus/notes/latest/os390 /usr/lpp/lotus/notesapi Debugger : /bin/dbx Debugger Version: Compiled: Feb 23 1999 11:09:56 GMT as BFP Script Dir : . Host Info : OS/390 SC67 06.00 02 9672 User : DOMINO3 (DOMINO3) Date : Wed Jun 16 19:53:50 EDT 1999 Clearcase View : ins Input arguments : INFO: Killing /usr/lpp/lotus/notes/5001/os390/router 1879048201 INFO: Killing /usr/lpp/lotus/notes/5001/os390/sched 704643082 INFO: Killing /usr/lpp/lotus/notes/5001/os390/replica 536870925 INFO: Killing /usr/lpp/lotus/notes/5001/os390/server 1711276046 INFO: Killing /usr/lpp/lotus/notes/5001/os390/stats 654311450 INFO: Killing /usr/lpp/lotus/notes/5001/os390/pop3 587202621 INFO: Killing /usr/lpp/lotus/notes/5001/os390/smtp 201326655 INFO: Killing /usr/lpp/lotus/notes/5001/os390/event 1778384965 INFO: Killing /usr/lpp/lotus/notes/5001/os390/amgr 1325400136 INFO: Killing /usr/lpp/lotus/notes/5001/os390/amgr 1174405199 INFO: Killing /usr/lpp/lotus/notes/5001/os390/update 1308622926 INFO: Killing /usr/lpp/lotus/notes/5001/os390/http 1795162194 INFO: Killing /usr/lpp/lotus/notes/5001/os390/nntp 1325400147 INFO: Killing /usr/lpp/lotus/notes/5001/os390/adminp 1459617877 INFO: Removing Share Mem IPC keys 0xf802a801 0xf802a802 0xf802a800 INFO: Removing Semaphore IPC keys 0xf802a807 0xf802aa70 0xf802a801 0xf802a802 0x f802a803 0xf802a804 0xf802a805 0xf802a800 0xf802a806 Remaining IPC Keys (Notes IPC keys start with 0xf8) Message Queues: Shared Memory: T ID KEY MODE OWNER GROUP m 105555 0xf8129802 --rw-rw---- DOMINO1 OEDOMINO m 105556 0xf8129801 --rw-rw---- DOMINO1 OEDOMINO m 367701 0xf802a801 --rw-rw---- DOMINO3 OEDOMINO m 367702 0xf802a802 --rw-rw---- DOMINO3 OEDOMINO m 367703 0xf802a800 --rw-rw---- DOMINO3 OEDOMINO m 105560 0xf8129800 --rw-rw---- DOMINO1 OEDOMINO Semaphores: T ID KEY MODE OWNER GROUP s 740900 0xf8129807 --ra-ra---- DOMINO1 OEDOMINO s 937509 0xf8129806 --ra-ra---- DOMINO1 OEDOMINO s 347689 0xf8129802 --ra-ra---- DOMINO1 OEDOMINO s 347690 0xf8129801 --ra-ra---- DOMINO1 OEDOMINO s 1199660 0xf8129a70 --ra-ra---- DOMINO1 OEDOMINO s 806453 0xf8129800 --ra-ra---- DOMINO1 OEDOMINO Note: You can set the environment variable NSD_LOGDIR to point to the directory where you want your logs/cores to be automatically saved Log file : ./kill_OS390_SC67_06_16@19_53.log Run nsd -help for more info on new options/features DOMINO3 @ SC67:/domino3/notesdata>
Figure 92. Terminating the server with nsd -kill

Start, stop and monitor the server

157

9.6.2 Additional options in nsd


Nsd provides more functions than just cleaning up the server processes and memory. Figure 93 on page 159 lists the available options. Using the -info option with nsd, you get lots of information about your current Domino environment, such as: General information: Domino data directory, script version, etc. IPC statistics Content of notes.ini Listing of the shell environment Complete listing of executables and library files with file attributes System info: hostname, max cputime, number of file descriptors File system mount table TCP/IP info based on /etc/resolv.conf Process list Complete listing of the Domino data directory and its subdirectories

This information provides you with an environmental snapshot that could be very helpful for problem determination. The output of the nsd utility is saved in the Domino data directory in a log file with the following filename: <nsd_option>_<OS name>_<hostname>_<timestamp>.log The commands nsd -kill and nsd -ps will therefore result in files like the following:
kill_OS390_SC67_06_16@19_53.log ps_OS390_SC67_06_17@12_01.log

You can set the environment variable NSD_LOGDIR to point to the directory where you want your nsd information to be saved. Set the variable in the file .profile in the home directory of the user ID that runs the Domino Server. The home directory of a user is defined in its RACF OMVS segment.

158

Lotus Domino for S/390 R5 Installation, Customization and Administration

SEMRA @ SC67:/domino1/notesdata> nsd -help Usage: nsd [options] [ core_file | pid ] Options: -batch -info -noinfo -nolog -ver*sion -ps -kill -memcheck -nomemcheck -lsof -nolsof -user <user_id> -exec_path <dir[:dir]*> -filter <log_file> -help -help <option> -help gen*eral -help lim*itations -help update

(run in batch mode -- don't write to tty) (just report system info) (don't report system info) (don't log output to log file) (just show version header) (show process tree) (kill all/user notes processes and cleanup IPCs) (run the Notes memory checker only) (don't run the Notes memory checker by default) (run lsof only -- list Notes open files) (don't run lsof by default) (operate only on notes process run by 'user_id') (add additional directories to the search path) (filter stack output of log_file) (show this help list) (where option is any one of the above) (general info about the script and how it works) (general info on script limitations) (list script version update info)

Figure 93. Options of the nsd utility

9.6.3 Cleaning up the server resources manually


If there are still resources allocated to the server either after an orderly shutdown using quit (or exit) or after using nsd -kill, you can clean up these resources manually. During our project we experienced such a situation after the server had been started with a user that had UID=0. Use the ipcs command to get a list of IPC resources currently allocated, along with their IDs (see Figure 94 on page 160). Switch to a superuser ID and clean up the resources belonging to the Domino server using the command ipcrm: ipcrm -m <ID> (for shared memory) ipcrm -s <ID> (for semaphores) UNIX processes can be killed in the following ways: From the UNIX shell using the command kill <processid> From the MVS console or SDSF using: STOP command (p) CANCEL command (c) FORCE command (consider the FORCE command as a last resort when the CANCEL command fails) Modify command: F BPXOINIT,TERM=<processid> Modify command: F BPXOINIT,FORCE=<processid>

Start, stop and monitor the server

159

D1ANDRE @ SC67:/domino3/notesdata>ipcs Message Queues: Shared Memory: T ID KEY MODE m 302162 0xf8129806 --rw-rw---m 105555 0xf8129802 --rw-rw---m 105556 0xf8129801 --rw-rw---m 498773 0xf8129805 --rw-rw---m 498774 0xf8129803 --rw-rw---m 498775 0xf8129804 --rw-rw---m 105560 0xf8129800 --rw-rw---Semaphores: T ID KEY MODE s 740900 0xf8129807 --ra-ra---s 937509 0xf8129806 --ra-ra---s 478758 0xf8129805 --ra-ra---s 347687 0xf8129804 --ra-ra---s 347688 0xf8129803 --ra-ra---s 347689 0xf8129802 --ra-ra---s 347690 0xf8129801 --ra-ra---s 1199660 0xf8129a70 --ra-ra---s 806453 0xf8129800 --ra-ra---D1ANDRE @ SC67:/domino3/notesdata>
Figure 94. List IPC resources with ipcs

OWNER DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 OWNER DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1 DOMINO1

GROUP OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO GROUP OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO OEDOMINO

Note: With OS/390 Version 2 Release 4 and later releases, the UNIX address spaces are managed by Workload Manager. When the Domino Server ends, the address spaces are retained for a period so that they are available for other users. This avoids the processing of an address space delete and create. Therefore, you may still see the Domino OS/390 address spaces after the Domino Server has stopped. If you restart Domino, it may use those address spaces again if they are still available.

9.7 DOMCON
This section explains where and how to download the DOMCON package.

9.7.1 Accessing the DOMCON package


You can download the DOMCON package from the IBM Web site:
http://www.s390.ibm.com/products/domino

Select the DOWNLOADS page, and click on DOMCON OS/390 Operator's Console Support . This will open the DOMCON Web page. Follow the instructions on this page to download a copy of the discussion database to your local workstation. The package is delivered as a Domino database, which means you will need a Notes client to use it. After downloading it to your local disk, open the file using: File->Database->Open from your Notes client The Explorer by double-clicking it, which will open your Notes client. IBM employees can access the database directly on the Domino Server d02dbl04 (in the d_dir, filename domcon.nsf). If you have problems accessing this server,

160

Lotus Domino for S/390 R5 Installation, Customization and Administration

add a connection document to d02dbl04.somers.hqregion.ibm.com to your local address book. The DOMCON database is a Notes discussion database that contains information about the installation and usage of this package. This database can be updated by IBMers. Customers will need to have their IBM representative update or append this database with questions or comments about this package. Currently, the discussion database is refreshed bi-weekly on the Web site. The latest code (version 2.2 at the time of writing) and documentation is contained in this database in the topic "DOMCON 2.2 is Available." In this topic you find two attachments: A pax file containing the DOMCON code An Acrobat Reader file containing the documentation Detach these files by double-clicking on each and selecting Detach on the popup menu. The DOMCON documentation explains in detail how to install and use the product.

9.8 Monitoring the Domino Server using SMF


Domino R5 can create SMF 108 records for providing information about the Lotus Domino address space. At the time of writing not much information about the DOMINO-related SMF records was available. Therefore, we decided not to cover this issue in this redbook. Another residency will cover Domino performance in detail. Refer to the redbook of that residency (SG24-5149-01) when it is available.

Start, stop and monitor the server

161

162

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 10. Lotus Domino R5 and the Internet


The tasks described in this chapter are mostly non-OS/390 specific. Therefore only the major topics are described to provide the reader with a general overview. We do not exhaustively cover every Internet-related feature. However, if there is something specific to the OS/390 platform, we cover it in more depth.

10.1 Lotus Domino Web Server


One of the major tasks of Lotus Domino R5 is the HTTP task. It brings together Lotus Domino and the World Wide Web. The HTTP task can be used to publish Lotus Domino databases to the Internet and your private intranet. It can also be used as a simple HTTP daemon, which means you can publish flat HTML files to the Internet and run Client Gateway Interface (CGI) scripts or programs.
Important

Whenever running the HTTP task on a Lotus Domino R5 server, remember that all databases on this server can be accessed via the Internet unless they are protected. You will have to make sure that the ACLs of all databases are set appropriately. You should add the Anonymous user to every database and assign the appropriate access permission to this user.

Whenever you want to change the settings of the Domino Web Server, you have to follow these steps: 1. Start the Domino Administrator. 2. Choose the server you want to reconfigure. If you do not know how to choose a server, please refer to 16.2.1, Selecting a server on page 341. 3. Choose the Configuration tab. 4. Choose Server -> All Server Documents. 5. Double-click on the Domino Server you want to change, or select the server and click Edit Server.

Copyright IBM Corp. 1999

Figure 95. Web server configuration

10.1.1 Setting up a Domino Web server


To set up a Domino Web server, click Ports -> Internet Ports in the server document. The Web tab should be selected by default. In the section SSL settings you can choose the key file and other SSL settings. We cover security-related topics in 18.2, Secure Sockets Layer (SSL) on page 377. To enable the Web server, you have to choose the TCP/IP ports you want your server to use. If possible, it is best to use well-known ports, such as 80 for the non-secure Web server and 443 for the secure Web server. The secure server will not run until you create a server certificate.
Note: Your OS/390 system may already be running a Web server that listens on port 80 or port 443. In this case, you must choose which Web server will own which ports.

Make sure that your TCP/IP stack allows a process to bind to ports 80 and 443. If the parameter TCPCONFIG RESTRICTLOWPORTS is used in your TCP/IP profile data set, then ports 80 and 443 must be reserved to OMVS or a specific jobname (see Figure 96 on page 165). If you choose to use a specific jobname (in our case the Domino server) you must ensure that the Domino server user ID is 8 characters long. Otherwise a number in the range of 1 to 9 will be appended to the user ID to define the jobname. By default, the Domino HTTP task will bind to all available TCP/IP stacks (address spaces). If you already have another Web server defined for a specific

164

Lotus Domino for S/390 R5 Installation, Customization and Administration

stack, you must use the bind to host name option to restrict the Domino HTTP task to another stack (Figure 129 on page 199).

... TCPCONFIG UDPCONFIG PORT 20 TCP OMVS 21 TCP OMVS 23 TCP OMVS 80 TCP OMVS 111 UDP OMVS 111 TCP OMVS 443 TCP OMVS 512 TCP OMVS 513 TCP OMVS 514 TCP OMVS 514 UDP OMVS 515 TCP OMVS ...

RESTRICTLOWPORTS RESTRICTLOWPORTS ; ; ; ; ; ; ; ; ; ; ; ; OE OE OE OE OE OE OE OE OE OE OE FTP Server FTPD control port Telnet Server Web Server Portmapper Server Portmapper Server Web Server SSL Port Remote Execution Server Rlogin Server Remote Shell Server SyslogD Server

Figure 96. TCP/IP profile data set

Next you should go to Internet Protocols -> HTTP. In this section you should make at least the following changes: Enable logging to log files or to Domlog.nsf, if you want to create statistics telling you about, for example, who, how much, and which pages were accessed on your Web server. If you have chosen log files, then you have to choose a Directory for log files. We recommend the creation of an HFS data set for the log files. If you have a lot of hits on your Web server you might get several megabytes of log files per day. You should also choose which log files you want to be written. If, for example, you do not need the agent log, just clear the field. In the Mapping section you should customize the Home URL. It should be either a Notes database or an HTML file.

Lotus Domino R5 and the Internet

165

Figure 97. HTTP server setup

If you need further information, refer to Domino 5 Administration Help.

10.1.2 Starting, stopping and refreshing the Domino Web server


There are two ways to start the Domino Web server. You can start it by entering load http at the server console, or you can start it at Lotus Domino R5 startup by adding it to the ServerTasks in notes.ini. By default, the HTTP task is added to the notes.ini file. To stop the Web server, enter tell http quit at the server console or remove http from the ServerTasks in notes.ini and restart the Domino Server. Type tell http restart at the server console to refresh the Web server.

166

Lotus Domino for S/390 R5 Installation, Customization and Administration

10.1.3 Lotus Domino virtual Web servers


Starting with Lotus Domino R5, all Web server settings are made in the Domino Directory. You do not have to use an HTTPD.CNF file as you might in other Web servers, such as Apache or Domino Go Webserver. Select the server document and choose Action -> Web and the appropriate sub panel. While there is a database template for creating a Domino configuration database domcfg.nsf as in the previous versions, you should use the domino directory to do so. There are two enhancements to the configuration of Web servers you might have missed in the previous versions: File Protection and Create Realm. Now you can: 1. Create virtual servers and hosts 2. Create URL mappings and redirections URL-to-URL URL-to-Directory Redirection URL-to-URL 3. Create file protection 4. Create realm The difference between a virtual server and a virtual host is that virtual servers have different IP addresses and different host names, while virtual hosts use the same IP address but different host names. Prior to installing a virtual server, you have to change the network setup. Prior to installing a virtual host, you have to change your DNS settings. Contact your Network Administrator team to set up a DNS entry. Although both types could coexist, you should use either virtual servers or virtual hosts.
10.1.3.1 Create virtual servers or hosts If you want to create a virtual server or host, you have to select Actions -> Web -> Create Virtual Servers from the menu bar. Now you will be asked whether you want to create a Virtual Host or a Virtual Server (see Figure 98).

Figure 98. Creating a virtual host

Choose Virtual Host . Creating a virtual server is very similar, except that you will be asked for the IP address instead of the host name.

Lotus Domino R5 and the Internet

167

Figure 99. Virtual server

In the Mapping tab you can specify the path name mappings to the HTML directory, the Icon directory, the CGI directory and the home URL. This tab is the same for both server types.

Figure 100. Virtual server mapping

The Security tab lets you make decisions about your security settings for the virtual server. You can decide if Name and Password or anonymous authentication will be used. You can also customize the SSL settings. For more information, refer to 18.2, Secure Sockets Layer (SSL) on page 377.

168

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 101. Virtual server security

10.1.3.2 Create URL mappings There are three different types of URL mappings. Depending on this choice, you will get three or four tabs to configure the mapping.

1. URL-to-URL mapping enables you to define alias names for URL paths; for example, you could map the directory of /gifs to the directory of /images.

Figure 102. URL-to-URL mapping

2. URL-to-directory mapping enables you to specify which URL path should be mapped to which real directory on your server. For example, if you store all the images on your Web pages in a directory /web/images, you have to create a directory mapping /web/images-to-/gifs to be able to access these pictures via the Internet.

Lotus Domino R5 and the Internet

169

Figure 103. URL-to-directory mapping

3. Redirection URL-to-URL. Using this you can move pages to a different server without making the old URL invalid.

Figure 104. Redirection URL-to-URL

In each choice, you have to specify in the Site Information tab which virtual server is affected by this mapping. In the Mapping tab you have to specify the actual mapping. If you have defined a URL-to-directory mapping, you also have to specify whether your data is read-only or also executable.
10.1.3.3 Create file protection One of the things missing in Domino Release 4.x was the ability to protect flat files created by the Domino administrator in a UNIX environment. You could define the file protection, but you could not manage this as a Domino Administrator. Now, with Lotus Domino R5, this can be done by choosing Actions -> Web -> Create File Protection . This ability might be needed in mixed environments where you have some data in Notes databases and other data in

170

Lotus Domino for S/390 R5 Installation, Customization and Administration

flat files. These protection settings apply to all Web servers on a Lotus Domino R5 server.

Figure 105. File protection - basic settings

You can only grant access to users specified in the servers Domino Directory, even though you could enter any user name. You assign these permissions by pressing Set/Modify Access Control List in the Access Control tab; see Figure 104.

Figure 106. Access control for file permissions

There are three access levels you can assign to a user: 1. Read/Execute access (GET method) 2. Write/ Read/Execute access (POST and GET method) 3. No access

Lotus Domino R5 and the Internet

171

Figure 107. Access Control List for file protection

In the name field (see Figure 107) you can specify the user name by typing the name or by using the Domino Directory lookup. After assigning the appropriate access permission, you have to press Next to apply this user to the Access Control List. To remove a user, click the name and then Clear.
10.1.3.4 Create a realm New with Lotus Domino R5 is the ability to set a realm in the browser authentication dialog. The browser uses the realm to determine which credentials (username and password) to send with the URL for subsequent requests. If you want to grant users access to different directories without having to reauthenticate, you should define a realm for them. You do this by choosing Actions -> Web -> Create Realm; see Figure 108.

Figure 108. Creating a realm

172

Lotus Domino for S/390 R5 Installation, Customization and Administration

10.1.4 Managing Java servlets on a Web server


A servlet is a Java program that runs on a Web server in response to a browser request. Servlets for Domino must conform to the Java Servlet API Specification, an open standard published by Sun Microsystems, Inc. For information on creating Java servlets, see Domino 5 Designer Help. From the Domino Administrator, click the Configuration tab, choose Server, and then open the Server document shown in Figure 109.
Note: To run Java servlets, you must have Java for OS/390 installed. See 3.2.1, OS/390 release level on page 52 for details.

Figure 109. Domino Web Engine - servlet support settings

Click the Internet Protocols / Domino Web Engine tab, complete the following fields, and then save the document:

Lotus Domino R5 and the Internet

173

Field
Java servlet support

Enter
Choose one: None (the default) to not load the Java Virtual Machine (JVM) or the servlet manager when the HTTP task starts. Domino Servlet Manager to load the JVM and the servlet manager that comes with Domino. Third Party Servlet Support to load the JVM, but not the Domino servlet manager. This lets you use a servlet manager other than Domino, such as IBM WebSphere. The path in a URL that signals Domino that the URL refers to a servlet. The default is /servlet. One or more paths that the Servlet Manager and JVM search to find servlets and dependent classes. The standard Java libraries installed with Domino are automatically in the class path. This setting allows you to add additional paths. You may specify directories, JAR files, and ZIP files. Paths may be absolute or relative to the Domino data directory. The following are examples of valid Class path entries: domino\servlet specifies files in the c:\lotus\domino\data\domino\servlet directory c:\apps\myservlets specifies files in the c:\apps\myservlets directory c:\javamail\mail.jar specifies the mail.jar file in the c:\javamail directory domino\servlet\sql.zip specifies the sql.zip file in the c:\lotus\domino\data\domino\servlet directory The default is domino\servlet.

Servlet URL path

Class path

Servlet file extensions

A list of URL file extensions that signal Domino that a URL refers to a servlet. You must map each extension to a single servlet by a directive in the servlets.properties file. The default is no extensions. Choose one: Enabled (the default) to have the Domino servlet manager check periodically the user activity of all HttpSession instances. Sessions that are idle for the period of time specified in the Idle session timeout field are automatically terminated. The servlet manager calls the method HttpSession.invalidate() to inform the servlet that the session will be terminated. Disabled to not check for user activity. Domino uses this setting and the settings below only if the servlet uses the Java Servlet API HttpSession interface. The HttpSession interface support is completely separate from the Domino HTTP session authentication feature. The amount of time in minutes the user is allowed to remain idle before the session is terminated. The default is 30 minutes. The number of simultaneous active sessions allowed. The default is 1000. After this limit is reached, the sessions that have been idle the longest are terminated.

Session state tracking

Idle session timeout

Maximum active sessions

174

Lotus Domino for S/390 R5 Installation, Customization and Administration

Session persistence

Choose one: Enabled to save session data to a disk file called sessdata.ser in the Domino data directory when the HTTP task exits. Domino saves the data in the Domino data directory in a file named sessdata.ser. Domino reloads the session data when the HTTP task restarts. Domino also saves objects that the servlet has bound to sessions if the objects implement the java.io.Serializable interface. Disabled (the default) discards all session data when the HTTP task exits.

10.2 Internet cluster manager


To use the Internet cluster manager, you will have to set up the Domino enterprise server. We cover this in 11.4.10, The Internet Cluster Manager (ICM) on page 218.

10.2.1 Server Web navigator


The server Web navigator could be likened to a proxy server. A Notes client can access Web pages through the server Web navigator without having access to the Internet itself. The server Web navigator loads a Web page from the Internet and stores it in a Notes database called web.nsf, which is automatically created at the first start of the Web retrieving process. If a client requests a page that is already in web.nsf, the server navigator sends it directly to the client. There are two options to start the server Web navigator. You can run the command load web at the server console or you simple add web to the notes.ini ServerTasks line. It will automatically be started at each Lotus Domino R5 server restart. To stop the server Web navigator, enter tell web quit at the console. If you want to connect to servers on the Internet through a firewall, you have to specify a proxy or socks server. You can do this from the Domino Administrator by clicking the Configuration tab and opening the server document for Web navigator server. Choose Ports -> Proxies. Do not use IP addresses in the No proxy for these hosts and domains section. You can use wildcards; for example, *.ibm.com would mean that all addresses in the domain ibm.com will be accessed directly.

Lotus Domino R5 and the Internet

175

Figure 110. Server proxy settings

10.3 NNTP
Network News Transfer Protocol (NNTP) is an Internet protocol for reading and distributing Network News, or newsgroups. It is used both for client-server connections and for communications between servers. It is an alternative to setting up a mailing list, using direct mail to distribute messages. Such remailing is inefficient when the number of subscribers grows beyond a handful of people. What you require is efficient, centralized storage of messages that people can access if and when they need them. NNTP provides means for distribution, inquiry, retrieval, and posting of news articles using a reliable stream client-server model. NNTP is designed so that news articles need only be stored on one host, while subscribers on other hosts may read news articles over TCP/IP connections, thereby minimizing the disk and CPU resources necessary on the client hosts. The following NNTP features are supported by Lotus Domino R5: Support for Notes Release 4.6 clients and above, standard newsreader clients, and Web browser clients Support for USENET newsgroups that are distributed across the Internet Support for private newsgroups for use within your organization Distribution of news articles using NNTP feeds to and from other NNTP servers Security for servers, including these security features: Anonymous access Basic authentication Secure Sockets Layer (SSL) encryption and authentication

176

Lotus Domino for S/390 R5 Installation, Customization and Administration

Archiving of newsgroup articles

10.3.1 Starting and stopping an NNTP server


There are three options for starting the NNTP server: If you selected NNTP when you installed Lotus Domino, the NNTP server task will be activated automatically. If you did not select NNTP when you installed Lotus Domino, you may start it manually using the following command at the server console:
load nntp

To start the NNTP server task automatically at Lotus Domino Server startup, add NNTP to the ServerTasks entry in notes.ini. For example:
ServerTasks=NNTP,REPLICA,ROUTER,UPDATE,

You can verify that the NNTP server is running by using the command show tasks at the server console. The output should include a few lines similar to these:
NNTP Server NNTP Server NNTP Server Scheduler Listen for connect requests on TCP Port:119 Control task

To shut down the NNTP server, you have two options: Shut it down manually by executing the command tell nntp quit at the server console. Deactivate the automatic startup by removing NNTP from the ServerTasks entry in notes.ini, and then restart the Lotus Domino Server.

10.3.2 Configuring newsfeeds


Lotus Domino R5 has four types of newsfeeds: Accept, Push, Pull, and Push-Pull. A push newsfeed allows your Lotus Domino Server to connect to a remote NNTP server and send new articles to that server. A pull newsfeed connects to a remote NNTP server and requests new articles from that server. A pull-push newsfeed will copy articles in both directions. If you want another NNTP server to be able to initiate a push newsfeed to your server, you need to set up an accept newsfeed. Please refer to the Lotus Domino R5 documentation for more information.
Note

Prior to configuring a newsfeed, you must contact your Internet newsfeed provider or the administrator of the remote news server. The newsfeed will not work unless the remote administrator permits it.

To connect to another news server, you have to create a connection document in the Domino Directory of the server. In Domino Administrator (see Figure 111), click Configuration -> Server -> Connections. Select the server running the NNTP task. Click Add Connection.

Lotus Domino R5 and the Internet

177

Figure 111. Adding an NNTP connection

On the Basics tab you have to specify the Connection type as News/NNTP Feed and the Destination server, which is the news server you want to connect (see Figure 112).

Figure 112. NNTP server connection - Basic tab

Next you have to click the NNTP tab (seeFigure 113 on page 179). Here you choose News feed type, the Authentication as agreed on with the administrator of the remote news server, whether you want your server to create new newsgroups automatically or not, and the names of the remote newsgroups you want

178

Lotus Domino for S/390 R5 Installation, Customization and Administration

downloaded to your news server. You can use wildcards to specify the newsgroups; for example, *. or comp.groupware.*.

Figure 113. NNTP server connection - NNTP tab

That is all you need for a first setup of the newsfeed.


Notes

Access control lists for newsgroups are not distributed through an NNTP newsfeed. If you include private newsgroups in a newsfeed, you must trust the remote NNTP server to enforce the access control policy. To enforce access control for private newsgroups within your organization, you should use Lotus Domino replication instead of an NNTP newsfeed.

10.3.3 Creating a newsgroup


A newsgroup on a Lotus Domino R5 server is a Notes database created using the NTTP Discussion template in the NNTP directory. Make sure that the user ID you are using is allowed to create new databases. Follow these steps to create a newsgroup called itso.redbooks.os390.domino on Domino1/Itso: 1. Start Domino Administrator. 2. Choose File -> Database -> New. 3. In the Server field, select Domino1/Itso. 4. In the file name field, enter nntp/itso.redbooks.os390.domino.nsf.

Lotus Domino R5 and the Internet

179

5. Select server Domino1/Itso as the template server, and highlight the template NNTP Discussion (R5.0) . Your dialog box should now look similar to the one in Figure 114.

Figure 114. Create a newsgroup database

6. Click OK to create the database. It might take a little while before you see the next window. 7. The next window you should see is the Database Profile window for the database you just created (see Figure 115 on page 181). There might also be an About... window popping up, but it is safe to close it down. Verify that the settings are the ones you entered when you created the database. The Database Profile Editor field will be filled in with the creator of the database. You might want to add people or groups to this field. By checking Private, you make it a private newsgroup. Private newsgroups might or might not be moderated. When you are done, click Save and Close.

180

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 115. Newsgroup database profile

Congratulations! Your newsgroup has been created, and you can start posting news articles to it. If the NNTP server task is running, NNTP clients can also connect and post news articles at this time.
Note

The newsgroup may not be visible to NNTP clients and remote NNTP servers for up to two hours. To make the newsgroup immediately visible, type tell nntp quit and then load nntp to stop and then restart the NNTP server.

10.4 LDAP
The Lightweight Directory Access Protocol (LDAP) is an Internet standard protocol that has evolved to meet the needs of sharing information in a directory between computers that might be on different networks, using different operating systems and different applications. LDAP is quickly gaining wide acceptance as the directory access method of the Internet and is, therefore, also becoming strategic within corporate intranets. It is supported by a growing number of software vendors and included in an increasing number of software applications.

Lotus Domino R5 and the Internet

181

If you would like further information about LDAP, refer to the following redbooks: LDAP Implementation Cookbook , SG24-5110, Understanding LDAP, SG24-4986, and Lotus Notes and Domino R5.0 Security Infrastructure Revealed, SG24-5341.

10.4.1 Lotus Domino R5 and LDAP


Lotus Domino R5 LDAP service supports the following features: LDAP V3 and V2. Different access protections including anonymous access to specified fields, user and password authentication, SSL and X.509 certificates, and others. Support of third-party LDAP clients. Use of LDAP clients to add, delete, and modify directory entries. Schema publishing and customization. Searches based on alternate languages.

10.4.2 Installation and configuration


The Lotus Domino R5 LDAP server task is automatically installed when you install Lotus Domino R5. There is no need to install additional software to enable Lotus Domino to function as an LDAP server. There is also very little extra configuration needed. The following is a quick overview of the steps involved in turning Lotus Domino into an LDAP server: 1. Configure LDAP server security, including who is authorized to access the directory, and whether or not to encrypt and sign transfers. 2. Create a full-text index of the Domino Directory on the server that runs the LDAP service. 3. If you are using more than one Global Domain, specify which the LDAP service should use to form Internet addresses. 4. Load Domino LDAP task. 5. Configure LDAP clients to connect to the LDAP server. 6. (Optional) Customize the default LDAP service configuration. 7. Check whether the LDAP service is set up correctly. These are the steps you have to perform to configure your LDAP task: 1. Start Domino Administrator. 2. Select the desired server. 3. Click the Configuration tab. 4. Select Servers -> Current Server Documents. 5. Click Edit Server to open the Server document. 6. Choose Ports -> Internet Ports -> Directory. 7. Set the LDAP port (it is best to keep the default port), enable the service and choose the appropriate authentication options.

182

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 116. LDAP Configuration

10.4.3 Starting and stopping the LDAP server task


There are three options for starting the LDAP server: 1. If you selected LDAP when you installed Lotus Domino, the LDAP server task will be activated automatically. 2. If you did not select LDAP when you installed Lotus Domino, you may start it manually with the following command at the server console:
load ldap

3. To start the LDAP server task automatically at Lotus Domino Server startup, add LDAP to the ServerTasks entry in notes.ini. For example:
ServerTasks=LDAP,REPLICA,ROUTER,UPDATE,

Lotus Domino R5 and the Internet

183

You can verify that the LDAP server is running with the command show tasks at the server console. The output should include a few lines similar to these:
LDAP Server LDAP Server Listen for connect requests on TCP Port:389 Control task

To shut down the LDAP server, you have two options: 1. Shut it down manually by executing the command tell ldap quit at the server console. 2. Deactivate the automatic startup by removing LDAP from the ServerTasks entry in notes.ini and then restarting the Lotus Domino Server. The show tasks console command should now show no LDAP entry.

184

Lotus Domino for S/390 R5 Installation, Customization and Administration

Part 3. Advanced installation topics

Copyright IBM Corp. 1999

185

186

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 11. Domino Enterprise Server


In July 1998, the Domino Advanced Services license ceased to exist and was incorporated into the Domino Enterprise Server (DES) offering. The logical features provided by the DES license remain unchanged; however, R5 provides additional functionality in some areas. The Domino Enterprise Server features consist of: Partitioning: See 11.3, Domino Server partitioning on page 189 Clustering: See 11.4, Domino server clustering on page 200 Billing: See 11.5, Domino Server billing on page 225 The Domino Enterprise Server enables sites to exploit Lotus Domino. It allows Domino service providers to make their service more reliable, scalable, manageable and secure, while allowing for more detailed and customized usage tracking for billing their services. Additional material on clustering and partitioning can be found in the following locations: The Domino Cluster Zone at http:/www.lotus.com/cluster. The following Iris Today articles at http://www.notes.net Workload Balancing with Domino Clusters (Michael Kistler - IBM) Fine Points of Configuring a Domino Cluster (Michael Kistler - IBM) The Domino Internet Cluster Manager (Lori Fucarile - Lotus)

11.1 Domino Enterprise Server lab environment


Figure 117 on page 188 shows the lab environment that was used for testing server partitioning and the relevant server details.

Copyright IBM Corp. 1999

187

S SYS 67
O S /3 9 0 R 2 .6
D F S M S 1 .4

S YS 6 3 S6
O S /3 9 0 R 2 .7
D F S M S 1 .5

(1 L P A R )

(1 L P A R )

T C P IP M V S

9 .1 2 .3 .5 8

T C P IP O E

9 .1 2 .1 5 .3 5

D o m i n o 3 / IT S O 2 p o rt 1 3 5 2

CTC

D o m i n o 4 / IT S O 2

p o rt 1 3 5 2

T C P IP O E

9 .1 2 .1 5 .2 8

D o m in o 1 /IT S O p o r t 1 3 5 2 + p o r t m a p p in g D o m in o 2 /IT S O p o rt 1 3 5 2 0
O SA2200 LCS

T ID T O T ID 5
W in d o w s N T 4 .0

9 . 1 2 .1 5 .1 6 4

O SA2220 LCS

TR

T O T ID 5 / IT S O 2 p o rt 1 3 5 2

N o te s c l i e n ts

N o te s c li e n ts

N o te s c l i e n ts

Figure 117. Our test environment

11.2 Domino Enterprise Server installation


All of the enterprise features are installed at the same time by selecting a particular type of server installation. This preliminary step is defined here because it is a common prerequisite to all of the configurations discussed later in the chapter. In effect, some configuration may be required before this step is reached; for instance, in setting up multiple file systems for partitioned servers. The installation steps are described in detail in Chapter 6, Installing a Domino Server on page 85.

188

Lotus Domino for S/390 R5 Installation, Customization and Administration

11.3 Domino Server partitioning


This section covers the installation and configuration of multiple Domino Servers on a single machine. Partitioned servers share the same binary files (version of code), but have individual data directories, which allows for independent configuration of resources. There are several reasons for implementing partitioned servers: 1. Segregation of server tasks on a single machine For example, a mail server and application server can have individually tuned Domino tasks but run on the same hardware. 2. Segregation of independent user communities For example, hosting multiple Domino domains or Domino-hosted Web sites on a single machine. 3. Independent operation of services and resources Partitioned Domino Servers operate independently and do not have any effect on each other.This allows an administrator the flexibility to treat each partitioned server as though it were a separate system. 4. To reduce operating system and hardware limiting factors

11.3.1 Planning a partitioned server deployment


The following are basic guidelines to help plan a partitioned server deployment: The limit of six supported partitioned servers (DPARs) on one system has been removed in Domino R5. Available system resources were the limiting factor. Partition identifiers are based on the server data directory names. A minimum of 200 MB of disk space for each separate data directory must be allocated. Use the TCP/IP protocol as this is the only supported configuration for Domino Enterprise Server R5 services. Partitioned servers can share, for example, one Open Systems Adaptor. See 11.3.3, Configuring partitioned servers for TCP/IP on page 190. A partitioned server may be a member of a cluster; however, it is recommended that the other Lotus Domino Servers in the cluster be located on other systems. Table 14 shows the naming conventions used for the partitioned servers running in the lab environment on the host sys67.ibm.com DNS with alias domino1.ibm.com and host sys67oe.ibm.com with alias domino2.
Table 14. Partitioned server lab parameters

Partition 1 2 3

Domino Server Name Domino1/ITSO Domino2/ITSO Domino3/ITSO2

RACF User ID Name DOMINO1 DOMINO2 DOMINO3

Data Directory Names /domino1/notesdata /domino2/notesdata /domino3/notesdata

Domino Enterprise Server

189

11.3.2 Domino partitioning and S/390 logical partitioning


For those readers who understand S/390 Logical Partitioning, it may be helpful to understand some of the differences between Domino partitioning (DPARs) and logical partitioning (LPARs). With logical partitioning we can run up to 15 different operating systems on a single S/390 processor. These operating systems can be any combination of the operating systems and release levels available on S/390. We could, for example, run an OS/390 Release V1R3 system and an OS/390 Release V2R7 system on the same processor. Therefore: We could run multiple OS/390 operating systems, each with a single Domino Server, on a single S/390 processor. This would provide better workload isolation, because now the operating systems are not shared. With separate OS/390 operating systems, the Domino Servers can be at different software levels. This would enable a test or development environment to run in parallel with a production system. If your current production system is at an earlier release than OS/390 V2R6, you could install a current OS/390 release in an LPAR to run Domino R5. When your production environment is upgraded to a supported release, you could then merge Domino into that system. You could use a combination of Domino partitioning and logical partitioning to run multiple OS/390 systems with multiple Domino Servers on each one. On a S/390, you could also use hardware partitioning on a multiprocessor or VM/ESA to provide the same types of function. For more information on S/390 logical partitioning, see S/390 Processor Resource/Systems Manager Planning Guide, GA22-7236.

11.3.3 Configuring partitioned servers for TCP/IP


You need to plan your partitioned server configuration before you install the Domino Servers. The way you implement your partitioned servers may influence the server names. There are different ways to configure partitioned servers for TCP/IP network access. You can: Use a unique IP address for each Domino Server,, as shown in Figure 118.

Server 1 O SA Server 2 O SA Server 3

9.12.14.58

domino1

9.12.2.28

domino2

9.12.2.29

domino3

Figure 118. Partitioned servers using unique IP addresses

Use a unique TCP/IP port number for each Domino Server on the same IP address, as shown in Figure 119 on page 191.

190

Lotus Domino for S/390 R5 Installation, Customization and Administration

Server 1
port mapper

9.12.14.58:1352

domino1

OSA

Server 2 Server 3

9.12.14.58:13520

domino2

9.12.14.58:13521

domino3

Figure 119. Partitioning servers using unique port numbers on one IP address

The decision as to which port number to use depends largely on your IP network configuration. The first option requires the use of more IP addresses. If you have the ability to do so, we recommend that you use unique TCP/IP addresses. This allows a one-to-one connection between the Domino Server name and the IP host name, which offers the easiest connection between the Notes clients and Domino Servers. It also provides the best performance and availability, as the servers are independent of each other. If you use unique TCP/IP port numbers on one TCP/IP address, you must define one server as a port mapper. The port mapper server must be running for Notes workstations to make a new connection to any of the partitioned servers. If the port mapper server is down, new sessions cannot connect. Existing sessions remain connected. We therefore recommend that if you run a server as a port mapper, its one and only function should be port mapping. Do not run the server also as a mail, database or application server. In this solution, all the servers must be in the same domain.
11.3.3.1 Using unique IP addresses When each Domino Server has a unique IP address:

1. Assign a unique IP address to each partitioned server. Table 15 shows an example.


Table 15. Partitioned servers with unique IP addresses

Server number First Second Third

IP address 9.12.14.58 9.12.2.28 9.12.2.29

IP host name domino1 domino2 domino3

Domino names

server/domain

domino1/ITSO1 domino2/ITSO2 domino3/ITSO3

2. Use the TCP/IP host name of each server as the server name. You define this during server configuration. For example, for the partitioned server with IP host name domino1, use the server name domino1/ITSO during server configuration. 3. Edit the notes.ini file of each partitioned server to include:
TCPIP_TcpIpAddress=0,IPaddress:1352

where TCPIP is the port name as specified in the server document of the Public Address Book in the network configuration section, and IPaddress is the TCP/IP address of the specific partitioned server. For example, for the server domino1/ITSO1:

Domino Enterprise Server

191

TCPIP_TcpIpAddress=0,9.12.14.58:1352

4. Ensure that the Domain Name Service (DNS) in the IP network contains definitions for all of the IP host names (which are the same as the Domino server names) and corresponding IP addresses. As an alternative, particularly for testing, you could include each partitioned server name as a separate entry in the hosts file on your client, as shown in Figure 120.

######################################################################### # hosts # # This file contains the hostnames and their address for hosts in the net # This file is used to resolve a hostname into an Internet address # # The format of this file is # Internet Address Hostname Aliases # Comments # Items are separated by any number of blanks. A # indicates the beginning # of a comment. # # Internet Address Hostname Alias # Comments 9.12.14.58 9.12.2.28 9.12.2.29 Domino1 Domino1/ITSO1 # partitioned server 1 Domino2 Domino2/ITSO2 # partitioned server 2 Domino3 Domino3/ITSO3 # partitioned server 3

Figure 120. IP Definitions on Notes client - multiple IP addresses

5. Edit the server document in each partitioned server Domino Directory to include the host names defined in the previous step in the network configuration section: Open the Domino Directory by using the Domino Administrator. Select Configuration Tab > Servers > All Server Documents to display the list of server documents. Select the server document that you want to define and click Edit Server. Click Ports > Notes Network Ports . 6. You can (for example) use a S/390 Open Systems Adaptor (OSA) card as your network connection. The OSA card can support multiple IP addresses as well as unique IP addresses. If you are using an OSA card for each IP address, configure each card to correspond to one partitioned server's unique IP address. If you want to define multiple IP addresses on a single OSA port, you can do this using OSA/SF. For detailed instructions on how to configure the OSA card, see Open Systems Adaptor 2 Implementation Guide, SG24-4770.
11.3.3.2 Using unique TCP/IP port numbers You can use port mapping to configure multiple partitioned servers on a single IP address. Port mapping requires that you assign a unique IP port number to each partitioned server that shares an IP address, and assign one of these servers to be the port mapper server.

The port mapper server is the one that will listen on port number 1352. This is the port that Notes clients will connect to when they access a server. (You can tell a client to connect to a different port number. However, since this would require changes to every client, you are unlikely to do that, except perhaps for testing.)

192

Lotus Domino for S/390 R5 Installation, Customization and Administration

The port mapper then decides which of the partitioned servers the client is trying to connect to, and passes the connection request on. The port mapper server must be running so that partitioned servers that share its IP address can receive new connections from workstations. If the port mapper server is down, new sessions cannot connect. However, existing sessions remain connected. Also, each client maintains a cache of recent server connections. This means that clients can still reach other partitioned servers if the requested server connection information is in the cache. To provide higher availability for partitioned servers, we recommend that the first partitioned server function only as a port mapper. It should not run other Notes applications. This reduces the chance of a failure of the port mapper, which would cause the other partitioned servers to lose connectivity. The downside of using a dedicated port mapping server is the additional overhead of running an extra partitioned server. To reduce the resource utilization of the dedicated port mapper server, you can remove all the server tasks from your notes.ini file to minimize the number of server processes that run. You can also remove large databases (such as the help database) from the data directory of this server. Do not remove the Public Address Book for this server. For details on how to configure using TCP/IP port numbers, see Domino 5 Administration Help and read the following. To set up the partitioned servers, we: 1. Assigned one partitioned server to be the port mapper server. We recommend that you remove all server tasks from the notes.ini file in the port mapper server. 2. Assigned a unique port number to each partitioned server that is not the port mapper server. The port mapper uses port 1352, the Notes default. In our system we used port numbers 13520 and 13521 for the other two partitioned servers. You can use any port numbers that are not used by other applications. 3. Edited the notes.ini file of the port mapper server to include: The TCP/IP address for the port mapper, in the form TCPIP_TcpIpAddress=0,IP Address:1352. The port mapping settings for each of the other partitioned servers, in the form
TCPIP_PortMappingNN=CN=server_name/O=org,IPaddress:tcp/IP portnumber

On our system the definitions looked like this:

. 000056 000057 000058 000058 .

TCPIP=TCP, 0, 15, 0 TCPIP_TcpIpAddress=0,9.12.14.58:1352 TCPIP_Portmapping00=CN=domino2/O=ITSO2,9.12.14.58:13520 TCPIP_Portmapping01=CN=domino3/O=ITSO3,9.12.14.58:13521

Figure 121. Port mapper server TCP/IP definitions

Domino Enterprise Server

193

4. Edited the notes.ini file of the other partitioned servers to include their TCP/IP address and port number, in the form TCPIP_TcpIpAddress=0,IP Address:ipport_number. On our second server the definition looked like this:

. TCPIP=TCP, 0, 15, 0 TCPIP_TcpIpAddress=0,9.12.14.58:13520 .


Figure 122. Second partitioned server TCP/IP definitions

5. Ensure that the Domain Name Service (DNS) in the IP network contains definitions for all of the Domino server names (as IP host names) and the corresponding single IP address. As an alternative, particularly for testing, you could include each partitioned server name as a separate entry in the hosts file on your client, as shown in Figure 123. 6. To reduce resource use for a dedicated port mapper server, you can remove all the ServerTasks from your notes.ini to minimize the number of server processes. You can also remove large databases (such as the help database from the data directory for this server). Do not remove the Domino Directory from this server.

######################################################################### # hosts # # This file contains the hostnames and their address for hosts in the net # This file is used to resolve a hostname into an Internet address # # The format of this file is # Internet Address Hostname Aliases # Comments # Items are separated by any number of blanks. A # indicates the beginning # of a comment. # # Internet Address Hostname Alias # Comments 9.12.14.58 domino1 9.12.14.58 domino2 9.12.14.58 domino3 domino1/ITSO1 domino2/ITSO2 domino3/ITSO3 # port mapper server # second partitioned server # third partitioned server

Figure 123. IP Definitions on client or Domino Administrator -- single IP address

11.3.4 Setting up partitioned servers


Our configuration had three servers with the following definitions:
Table 16. Domino partitioned server definitions

Server 1 Server name Data Directory RACF user id RACF group id domino1 domino1/notesdata DOMINO1 OEDOMINO

Server 2 domino2 domino2/notesdata DOMINO2 OEDOMINO

Server 3 domino3 domino3/notesdata DOMINO3 OEDOMINO

194

Lotus Domino for S/390 R5 Installation, Customization and Administration

Notes:

1. Our partitioned servers were not all in the same domain, but they could have been. 2. You must use a separate data directory for each server. We recommend that you create a separate file system (HFS data set) for each partitioned server's data directory. For more information on how to create an HFS data set, see 13.1.1, Creating a new HFS data sSet on page 269. For ease of management, include the Domino Server name in the HFS data set name and in the data directory name. 3. Create a separate RACF user ID to start each of the partitioned servers. You can use the same RACF group name for all the servers. If you use the same RACF user ID for multiple servers, then when you run nsd -kill it will kill all of the servers started with the user ID that runs nsd -kill. For more information on how to start and stop the Domino Server, please refer to the following in Chapter 9, Start, stop and monitor the server on page 127.
11.3.4.1 Setup of partitioned servers To set up the partitioned servers, run http httpsetup for each server, one at a time. This is exactly the same as we saw in 7.3, Running the server configuration program on page 106. Make sure that you use the correct server name and data directory. Note that each server is defined independently. They can be in the same domain or in different domains. They can each be the first server in their domain or an additional server in an existing domain.

11.3.5 Installing partitioned servers


After choosing to install a Domino Enterprise Server, as shown in 6.5.1, Interactive installation on page 90, the following additional steps must be taken: 1. At the question Do you want to run more than one Domino Server on this computer? press the spacebar to change the answer to Yes and then press Tab.

=============================================================================== Domino Server Installation ===============================================================================

You can run more than one Domino Server on a single computer at a time. This feature is called Domino Partitioned Servers.

------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press the Spacebar to change the setting until you get the one you want. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------>>> Do you want to run more than one Domino Server on this computer ? [Yes]

Figure 124. Choosing to run multiple server partitions

2. Press Enter to edit the number of data directories and type in the number required (one per partition) and then press Enter.

Domino Enterprise Server

195

=============================================================================== Domino Server Installation ===============================================================================

Each Domino Partitioned Server requires its own data directory. How many Domino Partitioned Server data directories would you like to install ?

------------------------------------------------------------------------------Press ENTER to retain the current setting or Type a new setting and press ENTER. ------------------------------------------------------------------------------Number of data directories current setting : 5 Number of data directories new setting : 2

Figure 125. Setting the number of server partitions

3. Press Tab to continue. 4. The install routine will then ask whether to generate data directory path names automatically; the default is Yes. 5. Press the spacebar to change the answer to No and then press Tab.

=============================================================================== Domino Server Installation =============================================================================== The install program can generate path names for the individual data directories by appending the numbers 1 through 2 to a base path name you supply. If you do not want the path names to be generated, you will be prompted for them each individually. ------------------------------------------------------------------------------Type h for help. Type e to exit the Install program. Press ESC to return to the previous screen. Press the Spacebar to change the setting until you get the one you want. Press TAB to accept a setting and continue to the next screen. ------------------------------------------------------------------------------>>> Do you want install to generate the pathnames for you ? [No ]

Figure 126. Choosing to manually generate partitioned data directory names

Note

The file used to identify the partition number for the server, .sgf.notespartition, is no longer used in R5. Instead the partition name is based upon the data directory name so data directory names should be unique. For example, a data directory name of /domino1 generates a partition identifier of .domino1. 6. A default path will be presented; press Enter to edit this and type in the required name, for example /domino1/notesdata, and then press Enter.

196

Lotus Domino for S/390 R5 Installation, Customization and Administration

=============================================================================== Domino Server Installation ===============================================================================

Enter the pathname for data directory 1 of 2.

------------------------------------------------------------------------------Press ENTER to retain the current setting or Type a new setting and press ENTER. ------------------------------------------------------------------------------Current path : /local/notesdata New path : /domino1/notesdata

Figure 127. Changing the name of the partitioned data directory

7. Press Tab to continue. 8. Repeat steps 6 and 7 for each partitioned server until all directory names have been entered. Notice that the screen display in Figure 127 shows how many data directories have been entered and the total number being installed. 9. Continue the installation process as normal, noting that only one RACF user ID can be specified at this time. Thus only one RACF user ID (the first Domino servers) will own all of the servers directories before you change ownership. 10.Changing file ownership is done using the chown command, an example of which can be found in 4.5.5, Defining a user to RACF with UNIX authority on page 67. 11.At the final review screen, Figure 128, review the data directory names listed to ensure that they are unique.
=============================================================================== Domino Server Installation =============================================================================== Installation settings: Installation type Program directory Data directories : Domino Enterprise Server : /usr/lpp/lotus : /domino1/notesdata /domino2/notesdata /domino3/notesdata : domino1 : oedomino

UNIX user name UNIX group name

Press the Escape key to re-configure the settings Press the Tab key to perform the installation...

Figure 128. Reviewing Installation Settings for Partitioned Servers

12.If this information is correct, press Tab to perform the installation.

Domino Enterprise Server

197

Note

Port mapping works only for Notes to Domino NRPC communication. It does not work for the Internet protocols such as HTTP and LDAP. Each of these services must be configured in the server document to use unique non-standard TCP/IP port numbers. These port numbers must then be made available to users wishing to connect clients to those services. For details on how to configure TCP/IP port numbers, refer to the Lotus Domino R5 Administration Help database.

11.3.6 Considerations for Internet server tasks


On a partitioned server, you have to specify additional parameters for the tasks HTTP, IMAP4, POP3, LDAP, NNTP and for SMTP.
11.3.6.1 Considerations for HTTP If you plan to use the HTTP task for multiple partitions, you have to ensure that each server responds only to requests for its own particular IP address. This is achieved by enabling a technique called binding, where each server is told explicitly to only accept requests for a specified host name or IP address.

For each partitioned server, edit the server document and then perform the following steps: 1. Switch to the Internet Protocols-HTTP tab. 2. Enter the IP address or fully qualified host name of the server in the field labelled Host name(s). 3. Change the value of the field Bind to host name to Enabled.

198

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 129. Enabling Bind to host name for HTTP task

4. If the HTTP task is running, then stop and restart it to enable the change.
11.3.6.2 Considerations for IMAP4, POP3, NNTP and LDAP If there are multiple network interfaces into the server, the following entries must be added to the notes.ini file for these tasks to run in a partitioned server environment for the respective protocol:
IMAPAddress=<IP address or fully qualified hostname> LDAPAddress=<IP address or fully qualified hostname> NNTPAddress=<IP address or fully qualified hostname> POP3Address=<IP address or fully qualified hostname>

11.3.6.3 Considerations for SMTP If there are multiple network interfaces into the server, the following entries must be added to the notes.ini file for the SMTP task to run in a partitioned server environment for the respective protocol:
TCPIP_TCPIPADDRESS=0,9.12.2.28:1352 SMTPNOTESPORT=TCPIP

Domino Enterprise Server

199

11.3.7 Starting and stopping partitioned servers


Each server must be started in such a way that it runs with a unique RACF user ID and uses its own data directory.
Recommendations

Give each RACF user a separate .profile file defining a unique PATH environment variable. Then edit each .profile and add the particular Domino Server data directory for that user to the path statement.

If the server startup is performed via a scripted startup routine, as in 9.3, Starting the server in the background using rc.notes on page 136, then each server must have its own unique script.
Recommendation

Create one script per server and ensure that the correct user account and data directory are referenced in each script.

11.3.7.1 Handling a partitioned server failure Partitioned server shutdowns and failures do not affect other partitioned servers that run on the same computer. If one server shuts down, the others continue to run. The setting KillProcess=1 should be present in the notes.ini file of each partitioned server (or in a server configuration document), enabling automatic cleanup of all of the processes associated with a partitioned server. With this default setting, you can restart a failed partitioned server without restarting the machine, but you have to make sure to clean up the interprocess communication resources (shared memory and semaphores) before restarting the server; see Chapter 9, Start, stop and monitor the server on page 127 for more details.
Note

If you run each partition with a separate RACF user ID and account, then finding processes, shared memory and semaphores relating to a specific server is much simpler.

11.3.8 Tuning partitioned server memory usage


The parameter NSF_Buffer_Pool_Size may have been specified for a machine running a single server partition. In R5 we recommend that you do not specify it manually for single instance servers. It should always be specified for partitioned servers, since the physical memory in the machine has to be shared between multiple servers.

11.4 Domino server clustering


Multiple Domino Enterprise Servers can be interconnected to provide high availability, scalability, and load balancing to Lotus Notes users and browser clients (HTTP and HTTPS requests). This is achieved by placing multiple replicas of some or all databases onto different servers within the cluster. Subsequently,
200

Lotus Domino for S/390 R5 Installation, Customization and Administration

transparent failover or load balancing can redirect the open request for a database on a failed or overloaded server to another member of the cluster. These clustered servers should be interconnected through a sufficiently high data transfer bandwidth network to allow for near real-time synchronization between the databases in the cluster. See Figure 130.

SYS67
OS/390 R2.6
DFSMS 1.4

SYS63
OS/390 R2.7
DFSMS 1.5

Cluster - RealTime Replication


ITSO2 Domain (1 LPAR) ITSO2 Domain (1 LPAR)

TCPIPMVS 9.12.3.58
Domino3/ITSO2 port 1352

TCPIPOE

9.12.3.176

CTC

Domino4/ITSO2

port 1352

TCPIPOE

9.12.15.28

Domino1/ITSO

port 1352 + port mapping


Domino2/ITSO port 13520
OSA2200 LCS

TOTID5
Windows NT 4.0

ITSO2 Domain

OSA2220 LCS

9.12.15.164
TOTID5/ITSO2

TR

port 1352

Notes clients

Notes clients

Notes clients

Figure 130. Clustering in an OS/390 environment

While clustering affords the following benefits, it is important to remember that it adds extra complexity to the domain and additional administrative responsibilities that are not apparent in non-clustered environments. The main advantages of clustering are: High availability Scalability -- growing the cluster to accommodate more users The clustering strategy also offers the advantage of gradual, scalable growth. It is easy to add another server to the cluster to share the growing workload. Clusters allow for a heavily used database to be distributed over several servers to balance the client requests. Replication in a cluster provides almost real-time synchronization of databases; however, some caveats do apply (see 11.4.3, Cluster replication vs. scheduled replication on page 203). As a cluster scales to contain more servers, an administrator can migrate users from one machine in the cluster to another. But keep in mind to plan your

Domino Enterprise Server

201

requirements carefully and consider the overhead clustering causes, as well as the additional administration effort. Load balancing within the cluster Clustering allows for the efficient use of server resources and better user response times. An administrator can balance the workload across all servers in the cluster by adjusting the availability threshold of each server. Through its load balancing and failover capabilities, the cluster software shifts users attempting to access a database on a loaded (busy) cluster member to a tightly synchronized replica on an available cluster member. It will not shift users that already have a database opened at that server.

11.4.1 Differences between Domino clustering and Parallel Sysplex


For those readers who understand S/390 Parallel Sysplex it may be helpful to understand some of the differences between Domino clustering and Parallel Sysplex. Let us start by saying that Domino for S/390 does not support any of the features of Parallel Sysplex technology. In a Parallel Sysplex-enabled database server such as DB2, there might be only one copy of the database. All of the DB2 servers access and update the single copy. With Domino clustering, each Domino server has its own copy of the database. Therefore: Domino clustering uses more disk space, since there are multiple copies of the databases. If a Domino database fails, there is a copy of the database on another server (if that database is replicated). If you only have one copy of the database, a failure to the disk on which that database resides can cause an outage. For critical data you may choose to use concurrent copy or RAID DASD to reduce the outage window. With Domino clustering, updates made to one version of the database are sent to the other servers to be applied to their copies. Therefore, there is a time delay (maybe a few seconds) and the databases are not in synch. If a user fails over to a different server, he may find that the information is slightly different because of that time delay. With Parallel Sysplex, everyone accesses the same database, so that cannot happen. With Domino clustering all changes are sent from server to server. This has a higher network and processor overhead than in Parallel Sysplex, where each processor updates the database directly. In a Parallel Sysplex the Workload Manager in each system knows the status and current performance of all the servers in the cluster. It can therefore route work to the best server. With Domino clustering, each server only knows about its own workload. It can therefore decide to route work to other servers, but does not have the information to determine which would be the best one to route it to. Parallel Sysplex, therefore, provides better performance and resource usage.

11.4.2 How many servers a cluster should contain


A requirement to cluster many servers usually results in the question:

Should you have a small number of large clusters (5 or 6 servers) or a large number of small clusters (2 or 3 servers)?

202

Lotus Domino for S/390 R5 Installation, Customization and Administration

While there is no easy way to recommend one approach over the other, you should take the following consideration into account. If a server in a cluster fails, then its workload must be absorbed by its peers in the cluster. For a 2-node cluster, this means that each server must have the capacity to handle an additional 50 percent workload, or in other terms they each run normally at 50 percent of their capacity. This is a waste of resources. For a cluster of 6 servers, each of the other 5 servers need only cope with an additional 20 percent workload, so they can in fact run at 80 percent of their total capacity under normal conditions.

11.4.3 Cluster replication vs. scheduled replication


There are some important feature differences between the event-driven cluster replicator and the usual schedule-driven replicator.
11.4.3.1 Cluster replicator caveats The following is a list of reasons for configuring regular schedule-driven replication in addition to running the cluster replicator task:

Although it is possible to disable cluster replication for databases, more than likely they will still need to replicate, but not in real-time. For example, template updates still need to replicate. Cluster replication events are held in memory only, and if a source server is shut down before pushing these changes to other members, the real-time replication event is lost. No data is lost but the change will not propagate until the next scheduled replication. Cluster replication ignores all selective replication formulas due to the overhead of computing what may turn out to be a complex formula. As a result, all changes are replicated, whether they match a selective replication formula or not. The standard replicator may then revert these changes back to honor the replication formula being used.
Note

Design element, deletions and access control list settings enabled or disabled via the Advanced section of a databases replication settings dialog box are implemented as selective replication formula. Cluster replication will propagate all design, deletions and ACL changes regardless of these settings. The cluster replicator pushes changes to other servers that have a replica of the changed database, but it does not update other replicas on its own server. A situation may arise where a server hosts more than one replica of a database, and it may seem perfectly reasonable to have two replicas on a server if one is a selective replica. In this scenario scheduled replication must be used to keep the two replicas synchronized.

Domino Enterprise Server

203

Note

When there are multiple replicas of a database on a server, the Cluster Manager uses "failover by pathname" to select the replica for a user to open in a failover situation. So if there are multiple replicas of a database on a server, make sure path names (directory path and file name) are consistent on all servers in the cluster. In R4.x, when one of the servers in a cluster fails, the cluster replicators on the other servers queue replications that must be pushed to that server, and periodically check for the server to become active again. In Domino R5, the cluster replicator detects servers rejoining the cluster much more rapidly, usually within a minute or two, and so the delay in updates to a failed server that may have been noticed in an R4.x environment should no longer be an issue. Regular and frequent scheduled replication is the solution to all of the above issues.
Recommendation

Enable scheduled replication 24 hours a day, 7 days a week at an interval of 60 minutes. Each time a server starts, it performs any due or overdue replications. If a cluster server has been down for more than 60 minutes, and with replication set for every 60 minutes and always enabled, then when it restarts, it immediately replicates with the other servers in the cluster. Finally, to allow users to experience a consistent set of database features regardless of the server they access in the cluster, the cluster replicator and the scheduled replicator should both propagate private folders.
Note

Private folders can only be accessed by the creator or a server within a cluster. Only servers defined by a server or server group entry type in the database ACL can access and replicate the private folders within the database.
11.4.3.2 Replication with servers outside the cluster One of the benefits of Domino clusters is that they can help simplify a replication topology, and at the same time improve its reliability and performance. This is because Domino allows you to configure a server outside the cluster to effectively replicate with all servers in the cluster using a single Server Connection document that specifies the server outside the cluster as the source and the cluster name as the target server of the replication. When a server replicates with a cluster, any databases on the server that also have a replica on any server in the cluster will replicate. Databases do not have to be on the same server in the cluster. If more than one replica of a database exists in the cluster, Domino replicates with one replica, and cluster replication propagates the changes to the other replicas. The server that initiates the replication does not have to be a Domino Enterprise Server but must be running Release 4.6.4 or higher.

204

Lotus Domino for S/390 R5 Installation, Customization and Administration

Replication with a cluster is also more reliable, since Domino replicates with any server in the cluster that has a replica of the database. So if one server in the cluster is unavailable, replication can continue as normal as long as all databases on the unavailable server also reside on another server in the cluster. Furthermore, when replicating with a cluster, Domino uses its workload balancing mechanisms to choose the target servers so that replication performs as quickly as possible.

11.4.4 Domino R5 clustering enhancements


Enhancements have been made to the operation of R5 clustered servers to support the following features not previously available: Failover and load balancing for Web clients Free-time calendaring and scheduling lookup Synchronous new mail agents that execute regardless of host server Type-ahead addressing and address resolution Synchronised unread marks across cluster replicas

11.4.5 Use of private LAN for cluster communication


To improve performance, it is recommended to direct the intra-cluster traffic (traffic within the cluster) to a private network, separate from the client-to-server traffic. Then each member of the cluster must be connected to two LANs. One LAN, the public LAN, is used for normal client access to the cluster. The second LAN, the private LAN, is used for all the communication within the cluster, such as heartbeat messages and cluster replication. Each LAN is a separate physical wire and may or may not be connected by a router. Note that all cluster members must be connected to the private LAN as well as to the public LAN. Each cluster member must use an identical set of ports.
Note: If your Domino servers are running on S/390 servers in a Parallel Sysplex, you can use the coupling facility to route the intra-cluster traffic. See 2.13.3, Exploitation of CTC connections through a coupling facility on page 41.

9.12.15.28.x

10.a.b.c

Client Traffic

Cluster Server 1

Cluster Replicator and Probes

Private LAN 10.a.b

9.12.3.58.y

10.a.b.d

Public LAN 9.12.x.x

Cluster Server 2

Figure 131. Dual network cluster server connectivity

Domino Enterprise Server

205

Each adapter should be configured with its own individual IP address and be connected to the appropriate network segment. The following steps can be carried out to set up the second network segment for use by the clustered Domino Server: 1. Start the administration client and select the cluster server from the bookmarks. 2. Click the Server tab. 3. Click the Server tools pane on the right hand side and an entry labelled Setup Ports should be visible, as shown in Figure 132 on page 206.

Figure 132. Setting up a new server port

4. The familiar port configuration dialog box should be displayed, as shown in Figure 133.

206

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 133. Server port configuration

5. Click New, type in a name for the port (for example, Cluster), choose the TCP protocol, and click OK. See Figure 134.

Figure 134. Creating a new network port

6. Click OK again and then a new port definition will be made in the notes.ini file on the server. 7. Edit the notes.ini file for each server and add the following lines (examples shown based on Figure 131 on page 205 and using ports named TCPIP and Cluster):
TCPIP_TcpIpAddress=0,9.12.2.x:1352 Cluster_TcpIpAddress=0,10.a.b.c:1352 Server_Cluster_Default_Port=Cluster

8. Edit the server document. 9. Click the Ports tab. 10.Enter the name of the new port (example, Cluster), a Notes Named Network entry (example, Cluster Network), and the IP address. See Figure 135.

Domino Enterprise Server

207

Figure 135. Adding a cluster port entry on the server document

11.Close and save the document. 12.The server must be restarted for this port change to take effect. 13.Once the server is started, issue the show cluster command at the Domino Server console to ensure that the cluster replicator is using the specified port for cluster traffic. Check the port name at the end of the line starting Server cluster default port. See Figure 136.

> show cluster Cluster Information Cluster name: ITSOCLUSTER, Server name: domino1/ITSO Server cluster probe timeout: 1 minute(s) Server cluster probe count: 220 Server cluster default port: Cluster Server availability threshold: 0 Server availability index: 100 (state: AVAILABLE) Cluster members (2)... server: domino1/ITSO, availability index: 100 server: domino2/ITSO, availability index: 100

Figure 136. Output of the show cluster command

11.4.6 Configuration of a cluster


The conceptual ideas behind clustering are discussed in detail in other redbooks and articles mentioned at the beginning of this chapter, so only R5-specific configuration methods are described here.
11.4.6.1 System requirements The following points should be observed prior to setting up servers for clustering:

1. Prepare for the cluster by ensuring consistent protocol usage on existing servers; only TCP/IP is supported in R5.

208

Lotus Domino for S/390 R5 Installation, Customization and Administration

1. Determine database distribution in the cluster and acquire sufficient storage for the existing and new servers. You would replicate application databases for load balancing and/or high availability, and mail databases only for high availability. 1. Ensure each server was installed with the Domino Enterprise Server installation type (see 11.2, Domino Enterprise Server installation on page 188). Servers do not have to have the same Lotus Domino version but they must be part of the same domain. 1. Make sure that an Administration Server is specified in the Advanced section of the access control list of the Domino Directory before trying to create a cluster. 1. In a private LAN configuration, ensure that appropriate network interfaces have been installed, configured and connected to the correct network segments.
Note

In a mixed-release cluster, all R4.x servers must be upgraded to R4.6.4a as this will be the required minimum for clustering with R5 servers.

11.4.6.2 Creating the cluster Using an administration client, open the replica of the Domino Directory database on the server specified as the Administration Server for the domain.
Recommendation

Using the replica of the Domino Directory on the server designated as the Administration Server means that requests do not have to be replicated between servers in the Administration Requests database before they can be actioned.

The following procedure can now be executed to generate the cluster: 1. Click the Configuration tab. 2. Expand the Server section in the left-hand pane. 3. Click All Server Documents. 4. Highlight (select) the servers that will be in the cluster that you are about to create. 5. Click Add to Cluster (see Figure 137).

Domino Enterprise Server

209

Figure 137. Selecting servers to create a cluster

6. Confirm that the action should continue by clicking Yes in the Verification dialog box (Figure 138 on page 210).

Figure 138. Confirm creation of a cluster

7. For new clusters choose *Create New Cluster and click OK , or choose the appropriate existing cluster name (Figure 139).

Figure 139. Choosing or adding a cluster name

8. Type in the name of the cluster and click OK (Figure 140 on page 211).

210

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 140. Creating a new cluster name

9. Decide whether the cluster should be created immediately or via the administration process and click the appropriate button as shown in Figure 141.

Figure 141. Create cluster immediately or via Administration Process

10.If the choice in step 9 was Yes, then a confirmation dialog like that shown in Figure 142 should be displayed when the process is completed.

Figure 142. Confirmation of Cluster Creation

11.If the choice in step 9 was No, then a dialog box like that shown in Figure 143 should be displayed and the following extra steps are needed.

Figure 143. Confirm submission of Admin Request to create cluster

12.Opening the Administration Requests database should reveal an Add Server to Cluster document for each server selected.

Domino Enterprise Server

211

13.When the changes in the Domino Directory replicate to the servers who are now members of the cluster, the Cluster Administration task, cladmin, is started on each server. 14.Then the Cluster Directory task, cldbdir, starts and creates the Cluster Directory Database (cldbdir.nsf). Sample server console output is shown in Figure 144.

02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99 02/03/99

11:18:39 11:18:42 11:18:42 11:18:42 11:18:44 11:18:48 11:18:52 11:18:55 11:18:58 11:18:58 11:18:59 11:18:59 11:18:59 11:19:00 11:19:08

Cluster Database Directory started Opened session for domino1/ITSO Starting replication with server domino1/ITSO Unable to replicate cldbdir.nsf Pulling names.nsf from domino1/ITSO names.nsf Finished replication with server domino1/ITSO Created database Cluster Database Directory: cldbdir.nsf Cluster Replicator started Finished initialization of Cluster Database Directory Replicating Cluster Database Directory with domino1/ITSO Opened session for domino1/ITSO Starting replication with server domino1/ITSO Pulling cldbdir.nsf from domino1/ITSO cldbdir.nsf Finished replication with server domino1/ITSO Cluster Administration Process shutdown

Figure 144. Cluster directory task startup

15.The entries cldbdir and clrepl will be added automatically to the ServerTasks= line of the notes.ini file so that they start automatically on each server restart. 16.Before continuing, stop the cluster replicator clrepl and cluster directory cldbdir tasks on each member server of the new cluster with the commands tell clrepl quit and tell cldbdir quit, respectively. The cluster creation is now complete, but there are some additional tasks that must be carried out to improve the operation of the cluster. These should be done before allowing the servers to replicate, but are not critical.
11.4.6.3 Modifying the contents of the cluster directory database When the cluster directory manager task creates the cluster directory database (cldbdir.nsf), it populates it with every database (*.nsf) and template (*.ntf) it can find in the servers data structure.

212

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 145. A new cluster directory database

Many databases and templates do not need to be replicated in real-time, and if they are left enabled, impose an overhead (albeit a small amount per database) on the operation of the cluster.
Recommendation

Use Tools -> Disable Cluster Replication of Selected Databases to disable cluster replication of non-critical databases and templates.
Tools -> Enable Cluster Replication of Selected Databases can be used at any time to re-enable particular entries.

Note

Whenever a new database or template is added to a cluster server an entry will be placed in the Cluster Directory database and it will be enabled by default and may have a corresponding replica on other cluster members. Remember to check whether this new database or template has a replica on another cluster member, and if it does, decide whether they really need to be cluster replicated and disable them if they do not.

The cluster directory databases are replicas on each server in any given cluster, and hence, each server replica will contain a list of all databases and templates

Domino Enterprise Server

213

on all servers available on the clustered servers once the servers have replicated with each other.
11.4.6.4 Removing a server from a cluster Using an administration client, open the replica of the Domino Directory database on the server specified as the Administration Server for the domain.

The following procedure removes a server from a cluster: 1. Click the Configuration tab. 2. Expand the Cluster section in the left-hand pane. 3. Click Clusters. 4. Highlight (select) the servers that will be removed from the cluster. 5. Click Remove from Cluster (see Figure 146).

Figure 146. Removing a server from a cluster

6. Confirm that the action should continue by clicking Yes in the Verification dialog box.

Figure 147. Confirm removal of server from cluster

214

Lotus Domino for S/390 R5 Installation, Customization and Administration

7. Decide whether the server should be removed immediately or via the administration process and click the appropriate button as shown in Figure 148.

Figure 148. Remove cluster immediately or via Administration Process

8. If the choice in step 7 was Yes, then a confirmation dialog like that shown in Figure 149 should be displayed when the process is completed.

Figure 149. Successful removal of server from cluster

9. If the choice in step 7 was No, then a dialog box like that shown in Figure 150 should be displayed.

Figure 150. Confirm submission of Admin Request to remove server from cluster

10.The cluster processes clrepl and cldbdir will be stopped on the server and the entries removed from the ServerTasks= line in notes.ini. 11.The database entries in the Cluster Directory database (cldbdir.nsf), for databases on the server being removed, will be purged from the replica copy on the least busy of the remaining cluster servers. 12.The local Cluster Directory database will be deleted from the server that is being removed from the cluster.

11.4.7 NOTES.INI file settings


There are several notes.ini variables that are required to tune or modify the behavior of clustered servers.

Domino Enterprise Server

215

Table 17 shows the relevant notes.ini variables and their purpose.


Table 17. Clustering specific notes.ini variables

Variable Name Server_Cluster_Default_Port Server_Restricted Server_MaxUsers Server_Availability_Threshold

Purpose The default port on which to send/receive all intra-cluster server-to-server communications. Disable acceptance of new client connection requests. In a load-balancing scenario, set a limit to the number of concurrent client connections to the server. A threshold set to determine when a server is considered busy; new requests will fail over to another cluster member when the threshold is reached. Enable router delivery failover to another replica of a users mail database when the home server is unavailable. Enable cluster replication event logging.

MailClusterFailover

RTR_Logging

Details of specific values can be found in the Lotus Domino R5 Administration Help database.

11.4.8 Mail delivery failover


Mail cluster failover is a process that allows a router on one server to deposit mail into a replica of a users mail database that resides on a clustered server other than the home server specified in a person document. To achieve this, the field Cluster failover on the Router/SMTP-Advanced-Controls tab of a server configuration document must be set. An example is shown in Figure 151 on page 217.

216

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 151. Enabling mail cluster failover

This configuration document must be set for all members of the cluster and for all servers that route mail to servers in the cluster. For example, a mail routing hub may not be a member of a cluster but since it may route mail for delivery to clustered servers, it must also have a configuration document to enable failover. The default value is Enabled for last hop only, and allows a router to failover delivery on the final hop of a message route only. To always allow failover at any point in the routing of a message, the setting Enabled for all transfers in this domain should be used instead.

11.4.9 Calendaring and scheduling support


In previous releases of Domino, when a client failed over to a server other than the home serve,r it was not possible to perform a free-time lookup for any user when their home server was unavailable, because the only copy of the busy time database containing their information existed on that failed server. With Domino R5, a version of the free-time database that can be replicated between cluster members resolves the problem so that full calendar scheduling support can be provided in times of particular server failure. When the schedule manager task sched starts up on a server that has become a member of a cluster, a new busy-time database is created that can be replicated across cluster members. If an original busytime.nsf database exists, then this is deleted first and the information is recreated in the new database.
Note: The new cluster-wide free-time database has a file name of clubusy.nsf.

Domino Enterprise Server

217

The reverse process is executed when a server is removed from a cluster. The sched task deletes the clubusy.nsf database and recreates a standard busytime.nsf. Each of the servers remaining in the cluster purges the deleted information from its replica copies of clubusy.nsf.

11.4.10 The Internet Cluster Manager (ICM)


The ICM is the task that manages failover and load balancing of Web client requests for data stored on clustered Domino Enterprise Servers. ICMs can be deployed in four main configurations: a single ICM inside or outside of the cluster, or multiple ICMs inside or outside of the cluster. Each ICM is dedicated to one and only one cluster. However, one cluster can be supported by multiple ICMs and the ICM server must belong to the same domain as the cluster. The ICM can be used to broker client requests in a mixed-release cluster. However, since R4.x Domino Servers cannot reference the ICM in the URLs they return, load balancing of requests cannot be achieved. When a client is redirected to a cluster member that is not R5, all subsequent requests for data will be sent to that server until failover or redirection to another server via a specific URL link occurs. Individual requests will not be load balanced across the other member servers in a mixed release cluster. The characteristics of the ICM are end-to-end security and authentication. Whatever authentication method is required for access to protected data served via HTTP or SSL connections, the ICM will preserve those connection types. All requests to the ICM are anonymous, that is, there is no authentication between the Web client and the ICM. Once the ICM has received a request and has decided where that request can be best fulfilled, it sends a redirection response code and target server details back to the Web client and a connection is made directly between the client and the specified server. At this point any authentication controls maintained by the target clustered server will be obeyed. Although no authentication exists between client and ICM, the transport of requests between the two can be protected via SSL encryption. Since no authentication takes place at the ICM, protecting it from unauthorized access is best served by implementing a firewall.
11.4.10.1 ICM outside the cluster Figure 152 on page 219 shows the way that a server running the ICM task can front-end traffic destined for clustered Web servers. As was said previously, multiple servers running the ICM could be used, with incoming requests being balanced between them using techniques such as round-robin DNS (where the same host name is used for all instances of the ICM).

218

Lotus Domino for S/390 R5 Installation, Customization and Administration

Domino Enterprise Server 1

ICM
Browser Domino Enterprise Server 2

Browser

Domino Enterprise Server with ICM

Domino Enterprise Server 3

Domino Cluster
Figure 152. Running the ICM outside the cluster

In this scenario the server is running solely to provide the ICM, and by removing all redundant services (such as the mail router and schedule manager) the server will be able to concentrate its resources on responding to Web client requests.
Note: Remove all unnecessary tasks from a server dedicated to running an ICM task to improve stability and performance of the server. 11.4.10.2 ICM inside the cluster Figure 153 shows the way that a server that is already a member of a cluster can host the ICM task. Once again, multiple cluster members could be configured to run the ICM, with incoming requests being balanced between them using techniques such as round-robin DNS.

ICM
Browser Domino Enterprise Server 1 with ICM

Browser

Domino Enterprise Server 2

Domino Enterprise Server 3

Domino Cluster

Figure 153. Running the ICM inside the cluster

Domino Enterprise Server

219

11.4.10.3 Configuring a server to provide ICM services Whether the ICM server is inside or outside the cluster, the configuration is essentially the same. Differences will be highlighted where appropriate.

Start the administration client and select the server that will run the ICM from the bookmarks: 1. Click the Configuration tab. 2. Click the Server section in the left-hand pane. 3. Edit the server document. 4. Click the Server Tasks-Internet Cluster Manager tab, and the form shown in Figure 154 will be shown.

Figure 154. Configuring ICM in the server document

5. In the Cluster name field enter the name of the cluster that this ICM will support (if the server is a member of the cluster, this can be left blank). 6. If the ICM will share the IP address of the server, skip to step 10. 7. Create a new Notes port definition, with a name of ICM for example, in a similar way to that described in steps 1-12 of 11.4.5, Use of private LAN for cluster communication on page 205. 8. Add the following entry in the notes.ini file:
220
Lotus Domino for S/390 R5 Installation, Customization and Administration

ICM_TcpIpAddress=0,a.b.c.d assuming the new port name created in step 7 was ICM. 9. Enter the Notes port name in the field ICM Notes port. 10.If SSL connections are required; specify the keyring file name in the ICM SSL keyfile field. 11.Ensure that browsing is not allowed. 12.Choose whether the ICM for this server should use this server document for its configuration or whether it should use another server document .
Note: At first glance this may seem a strange option to provide; why would an ICM on this server not use its own server document?

The reason for allowing the ICM on one server to use the configuration of another ICM is so that multiple ICMs serving one cluster can share the same configuration more easily. 13.If the option another server document is chosen, then the form will present a field named Obtain ICM configuration from in which a server name should be entered. 14.Enter the fully-qualified host name that clients will use to connect to the ICM. This can either be a registered DNS name (recommended) or an IP address. 15.The TCP/IP port number need only be changed if the ICM is running on a cluster member that already has HTTP enabled and no spare IP address is available. See 11.5.4.6, HTTP request billing on page 229 for details regarding assigning IP address aliases, because the same method applies as was used to install partitioned servers.
Recommendation

Providing the ICM with its own IP address is much simpler than sharing a single IP address, because standard TCP/IP port definitions can be used. If a separate IP address is assigned to the ICM task, ensure that the HTTP task is bound to its specific IP address only (see 11.3.6.1, Considerations for HTTP on page 198 for details on setting this up). 16.Unless all traffic between clients and the ICM requires encryption, the field TCP/IP port status should be left enabled. 17.To specify a non-standard SSL port number (where a single IP address may be in use and the HTTP server already uses SSL), enter a new port number in the SSL port number field. 18.Change the SSL port status field value to enabled if SSL is required between client and the ICM. 19.Close and save the server document. 20.Edit the notes.ini file of the server on which the ICM will run. 21.Add the entry ICM to the end of the ServerTasks= line.

Domino Enterprise Server

221

11.4.11 Monitoring cluster processes


General information about a server in a cluster can be found using the show cluster command at the server console. Details of the cluster name, availability thresholds and other servers in the cluster are shown. An example of this has already been seen in Figure 136 on page 208. Logging of cluster replication events is disabled by default, since they are by nature large in volume. Logging should be turned on only when problems are suspected and tracking information is required. To enable logging, add the line RTR_Logging=1 to the notes.ini file of the server to be logged.
11.4.11.1 Cluster servers To determine whether the intra-cluster (server-to-server) traffic is performing at optimum levels, use the statistics shown in Table 18. They do not appear on the normal cluster statistics reports but can be seen using the show stat command on the server console.
Table 18. Intra-cluster traffic statistics

Statistic Name Replica.Cluster.Successful Replica.Cluster.Unsuccessful Replica.Cluster.SecondsOnQueue .Avg Replica.Cluster.SecondsOnQueue .Max Replica.Cluster.WorkQueueDepth Replica.Cluster.WorkQueueDepth. Avg Replica.Cluster.WorkQueueDepth. Max

Description Number of successful replications since server startup. Number of unsuccessful replications since server startup. Average time in seconds that database spent on work queue. Maximum time in seconds that database spent on work queue. Current number of databases awaiting replication by the cluster replicator. Average work queue depth since server startup. Maximum work queue depth reached since server startup.

The value indicated by Replica.Cluster.SecondsOnQueue.Avg shows the average amount of time taken for changes made on this server to be pushed to the other cluster members. A value of 60 or less means all changes are reaching the other servers within 1 minute of the change occurring. The Replica.Cluster.WorkQueueDepth.Avg depends upon the number of databases on the server and the volatility of the data contained in them. Typically, this value should be consistently below 15; values higher than this may indicate that the network bandwidth is restricting the servers ability to push changes to the other cluster members. If the cluster servers are not using a separate private network for intra-cluster replication, then moving to this topology should resolve this problem.

222

Lotus Domino for S/390 R5 Installation, Customization and Administration

When load-balancing is implemented in a cluster, the statistics shown in Table 19 can be monitored to determine whether the workload is well balanced.
Table 19. Workload balancing statistics

Statistic Name Server.AvailabilityIndex Server.Cluster.OpenRedirects .LoadBalance.Successful Server.Cluster.OpenRedirects .LoadBalance.Unsuccessful Server.Cluster.OpenRequest. ClusterBusy Server.Cluster.OpenRequest. LoadBalanced

Description The current value of the availability index. Number of times a busy server successfully redirects to another server. Number of times a busy server unsuccessfully redirects to another server. Number of times a busy server tries to redirect a request when all other servers are busy. Number of times a client tried to open a database on this server when the server was busy.

11.4.11.2 ICM servers The statistics shown in Table 20 can be used to monitor the general use and performance of the ICM task.
Table 20. General ICM statistics

Statistic Name ICM.Command.Total ICM.Command.Unknown ICM.Command.Redirects. Successful ICM.Command.Redirects. Unsuccessful ICM.Command.Redirects. ClusterBusy ICM.Command.Redirects. Per1Hour.Total ICM.Command.Redirects. Per1MinuteTotal ICM.Command.Redirects. Per5MinutesTotal

Description The number or URL commands received The number of unrecognized URL commands Number of successful client redirects to a cluster member Number of unsuccessful client redirects to a cluster member Number of client requests received when all cluster members were busy Number of requests received in the past hour Number of requests received in the past minute Number of requests received in the past 5 minutes

11.4.12 Managing databases in a cluster


In the administration client choose the server to work with from the bookmarks and then select the Files tab to display the databases and templates on the chosen server. The following steps change the characteristics of one or more databases: 1. Select the files from the list using the Shift or Ctrl keys as appropriate to make multiple selections. 2. Right-click one of the selected files. 3. Click Cluster from the popup menu as shown in Figure 155 on page 224.

Domino Enterprise Server

223

Figure 155. Selecting databases for cluster management

4. Choose the appropriate action from the Cluster Management dialog box (an example is shown in Figure 156), then click OK to carry out the action.

Figure 156. Choosing a cluster management action

The available options are: Out of Service The database cannot be accessed and client requests are failed over to another replica in the cluster. In Service To make a previously out-of-service database available again. Pending Delete
224
Lotus Domino for S/390 R5 Installation, Customization and Administration

Mark database for deletion only after all active user sessions have completed.

11.5 Domino Server billing


The billing activity of a server provides an enterprise with additional data to enable it to perform several tasks: Charge for usage of servers Monitor usage trends Conduct resource planning When enabled, the server collects client and server activity information and places the information in the billing message queue. Periodically, the billing process takes this data and writes it to disk, creating records that can be reviewed and used for the tasks described above. The billing process on a Domino Enterprise Server consists of two major components: 1. Lotus Domino Server enabled for billing: the server provides billing information according to seven billing classes, discussed later. 1. The Lotus Domino billing task collects the information provided by the server and generates billing records, stored either in a database (billing.nsf), a binary file (billing.nbf), or both.

11.5.1 Billing classes


The BillingClass setting in notes.ini controls which of the seven allowed billing classes are to be tracked, as shown in Table 21.
Table 21. Billing classes

Billing Class Session

Tracks When users and servers start or end sessions with a billing server and when network-related activities such as document creation and editing occur during the session. Also includes client-initiated replication and mail events. When users and servers open and close databases and duration of use, including mail delivery events. Read and write activity for specified documents, the document form must contain a hidden field named $ChargeRead or $ChargeWrite that has a cost value in it. When a billing server initiates replication with another server, does not include cluster replication events. When the mail router on a billing server transfers mail to another server. When users and servers run server-based agents on the billing server, as well as the execution time of the agents, but does not include agents executed on Web servers. When a billing server responds to a Web browser request.

Database Document

Replication Mail Agent

HTTPRequest

See the Lotus Domino R5 Administration Help database for further details.

Domino Enterprise Server

225

11.5.2 Enabling the billing process


To enable billing on a server, either the notes.ini file can be edited directly or the settings shown below can be specified through the NOTES.INI Settings tab of a server configuration document: ServerTasks=...,Billing To enable the billing task at server startup. BillingClass=<all> or some of the classes defined in Table 21 on page 225. The list of billing class events that are to be tracked BillingAddInWakeup=seconds (default = 60) How often the billing task processes items in the billing message queue.
Note: This value must be greater than the value specified for BillingAddinRuntime.

BillingAddInRuntime=seconds (default = 10) The amount of time that the billing task will execute after wakeup BillingSuppressTime=minutes (default = 15) The frequency of record stamping during session and database activities if those classes are specified by BillingClass BillingAddInOutput=value Determines where the records will be stored or displayed according to the following table:
Table 22. Locations for billing records

Value 1 2 3 8 9 10 11

Location Notes database (billing.nsf) Server console Notes database and server console Binary file (billing.nbf) Both database and binary file Binary file and server console Database, binary file and server console

As an example, assume we want billing to be active for Mail, Replication and Web, starting generating records every 10 minutes for 2 minutes, logging to a binary file. We would specify in notes.ini:
ServerTasks=...,Billing BillingClass=Mail,Replication,HttpRequest BillingAddInWakeup=600 BillingAddInRuntime=120 BillingAddInOutput=8

226

Lotus Domino for S/390 R5 Installation, Customization and Administration

11.5.3 Optimizing billing performance


During times of peak usage, if system performance is an issue, reduce the frequency with which the server posts session and database activity information on the billing message queue by increasing the BillingSuppressTime parameter. In addition, the billing load can be reduced by running the billing task less frequently (increase BillingAddInWakeup) and/or shortening the amount of execution time that it is allowed (reducing BillingAddInRuntime). Finally, multiple billing tasks can execute in parallel to transfer records from the billing message queue to the chosen storage location. For example, to enable two billing tasks to run on a server, specify the following line in notes.ini:
ServerTasks=......,Billing,Billing

11.5.4 Sample billing records


This section contains samples from the billing.nsf database only, since the binary file billing.nbf cannot be displayed. Notes API programs must be used to produce reports based on the contents of the binary file. The standard billing database does not provide any totalling across documents listed in the views of the database. For better analysis, records should be categorized and totalled to provide at-a-glance totals and subtotals of relevant numeric indicators such as document read and write charges.
11.5.4.1 Session billing Session billing collects information of the data volume of a certain user session that indicates who has transferred how many bytes; see Figure 157.

Figure 157. Sample session billing document

Domino Enterprise Server

227

11.5.4.2 Database billing Database billing delivers two types of records (DBOpen and DBClose), which allow tracking of how long a database has been in use by a certain user and how long it has taken to actually perform the open and close actions; see Figure 158.

Figure 158. Sample database billing documents

Note

The value stored in $ChargeRead or $ChargeWrite is interpreted as whole currency units. For example, assuming a currency denomination of US dollars, a numeric value of 10 in these fields is translated and displayed as $10.00 in the views of the billing database.

11.5.4.3 Replication billing Replication billing offers information on which servers exchanged data during replication, how much data for which database, and when the replication occurred; see Figure 159.

Figure 159. Sample replication billing document

228

Lotus Domino for S/390 R5 Installation, Customization and Administration

11.5.4.4 Mail billing Mail billing indicates which mail has been routed where, who created it, the size, and the recipient; see Figure 160.

Figure 160. Sample mail billing document

11.5.4.5 Agent billing Agent billing allows tracking of the time an agent executed on the server, which database it acted on, and who started the agen; see Figure 161.

Figure 161. Sample agent billing document

11.5.4.6 HTTP request billing HTTP request billing provides extensive information about which objects have been retrieved from the Web server, the time elapsed to fulfill the request, the

Domino Enterprise Server

229

user who retrieved the data, the number of bytes retrieved, and the IP address of the client system; see Figure 162.

Figure 162. Sample HTTP request billing document

230

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 12. Upgrading the Domino Server


Upgrading a Domino Server can be broken into two distinct parts: to prepare and install the new software, and to exploit the features and functionality made available by that software. The goal of a successful upgrade is to minimize downtime and disruption to the users of the existing Domino Servers while maintaining a similar or enhanced level of service. Although this chapter serves to guide the administrator in upgrade methodology and good practice, it cannot cover every eventuality because every installation is different in some way. With this goal in mind, much of the early preparation for the upgrade involves testing and fine tuning the procedures through which the upgrade of the environment will be achieved. This ensures that everyone involved in carrying out upgrades will be familiar with the procedures and will be aware of any specific issues that may be encountered within their environment. The upgrade process and its duration is significantly different for each organization and is a function of the size of the current implementation and the resources available to perform the upgrades required in that environment.

12.1 Preparation
The key to a successful upgrade is careful planning and preparation. One of the earliest tasks is to identify members of the project team and their associated roles and responsibilities. For small installations the team may consist of one or two people, but in large enterprise installations, the teams will not only be comprised of more members, but they may also be geographically dispersed. Everyone involved must be comfortable with the new software and the procedures that will be followed to carry out the upgrade. Training and testing in a separate test environment are key to achieving the required level of competence. An upgrade schedule is important so that the project is properly coordinated and everyone is kept informed of the current status and of the next stages. Users must be notified of impending changes to the servers that will affect them so that they are prepared for downtime, unless of course the resources are available to perform server upgrades during out-of-hours periods.

12.1.1 Planning the order of your upgrade


As mentioned in section 12.1, a schedule is very important to maintain a structured approach to the upgrade process. The key to this schedule is the order in which the elements of the infrastructure will be upgraded. The following is the recommended order: 1. Public Name and Address Book (NAB) Since the new public NAB, now called the Domino Directory, is designed to be backwardly compatible with earlier releases of software, the design can be upgraded on the existing servers prior to installing the R5 software on them. This is the most critical database in any Domino environment and is one of the main steps in the upgrade process. Having the new Domino
Copyright IBM Corp. 1999

231

Directory in operation before starting to install new software will give everyone confidence in the next stages of the project. 2. Servers Upgrading the servers before clients ensures that a user cannot request a service from a server that cannot be provided because the server is running an earlier release of the software. 1. Hub servers Hub servers generally exhibit two characteristics that make them prime candidates for upgrades early in the schedule. Firstly, hub servers do not usually have any or many active users connected to them so a problem with the upgrade impacts the user community much less severely than, say, a problem with an upgraded mail server. Secondly, they are typically small in number, are located centrally, and are managed by skilled administrators.
Note: If the first server upgraded is not the server designated as the administration server of the Domino Directory, then the server that is the administration server should be the next one to be upgraded.

2. Mail and application (spoke) servers Once the hub servers are upgraded and are performing satisfactorily, attention can be turned to the servers that make up the bulk of the infrastructure and procedures can be fine-tuned with any additional lessons learned. The mail and application (spoke) servers may or may not be located centrally. Where they are remote, the team members responsible for carrying out upgrades should have achieved the necessary level of competency in the upgrade process. The testing and training stages of the project should be used to produce extensive documentation tailored to the specific environment. 3. Other servers Lastly, in terms of servers, those performing specific tasks utilizing add-in or 3rd-party API products (such as gateways) can be considered. Here there are some choices and possibly restrictions on what can be done. The server may have to be left alone to continue running the R4.x version until an R5-specific version of the add-in product is produced, or, where there are no version-specific dependencies, the server can be upgraded. Specific attention should be paid to these types of servers during the testing phase to ensure that the add-in tasks or API programs perform as expected after upgrade to R5. 4. Clients Although outside of the scope of this particular book, the clients should be upgraded once server upgrades have been completed.
Note: The R5 setup program ignores an R3.x workspace and desktop.dsk file, so an R3 to R5 upgrade will result in an empty bookmarks database. There is no client in the OS/390 environment.

3. Applications Finally, when all clients have been successfully upgraded, the process is completed by upgrading mail databases and applications to take advantage of the new features afforded by R5.

232

Lotus Domino for S/390 R5 Installation, Customization and Administration

In practice, clients and applications can be upgraded in parallel with servers, provided that the servers that a particular group of clients access have already been upgraded to R5.

12.1.2 Testing your upgrade procedures


In order to achieve competence, understanding and faith in the upgrade process, a significant amount of time must be allowed for testing and training. R5 contains many new features for both the administrator and end user, and prior to upgrading the administrator must be comfortable with the way they will be required to work after the upgrade has been completed.
Recommendation

Build an isolated test environment, modeled exactly on the existing environment, with good backup and restore capabilities. Use at least two servers and two clients in this environment. Use this environment to also test application functionality and interoperability.

12.1.2.1 Defining a test environment The simplest way to produce a test environment that exactly mimics the real live environment is to register and configure two additional servers in the existing public NAB and install two servers using the current releases of the operating system and Domino software in use on the production servers. This should produce two servers that have characteristics identical to the other servers in the domain. Replicate any critical applications that require testing onto these servers. Disconnect them from the live network and create an isolated private network through which they can communicate only with themselves. Once the servers are disconnected, all references to them can be removed from the live public NAB.

As mentioned in 12.1.1, Planning the order of your upgrade on page 231, specialized servers running add-in or API tasks must also be considered. A test server utilizing these types of programs can be created in the same way as discussed previously. Install test clients, again with the same releases of software as are already in use, and connect them to the same test network. Before testing begins, take a complete backup of the servers and clients. The upgrade process will undoubtedly be performed several, if not many, times in this environment and a full restore is the quickest and easiest way to reset one of the systems to its original state. Throughout the testing process, detailed documentation should be created, which can be used to produce the final upgrade procedure. It is important not only to document the correct steps but also to record mistakes and problems in the process so that others reading the documentation are made fully aware of specific key points or pitfalls, and to help in their understanding of why things are done in a particular way.

Upgrading the Domino Server

233

12.1.2.2 Consider clustering For servers that are particularly critical, or during the early stages of the upgrade project, clustering the server with an R4.6x server can be a valuable way of providing standby resilience. By clustering the existing server with another running a well-proven level of Domino software, users are protected from server crashes because their requests for data can be failed-over to the R4.x server until the problems with the R5 server are resolved. 12.1.2.3 Database design considerations When the new version of the software is applied to the server, many of the existing templates that are shipped with Domino will be overwritten with newer versions.

An important exercise to undertake before the upgrade project commences is an audit of the databases on all the servers in the domain. This will provide information to allow administrators to ensure that any design elements that have been changed are preserved when system database designs are updated. Use should be made of the testing environment to ensure that the customizations are still necessary and that they work as expected with the new design. Some of the customizations may no longer be required because the needs they addressed may have been satisfied by new features of the standard R5 database designs. The audit should record all databases that have been based upon any of the standard templates and any changes or customizations that have been made.
Recommendation

Make sure that design elements that are not to be changed by a design refresh or replace have the property Do not allow design refresh/replace to modify enabled.

During this audit, administrators should also ensure that all database and template access control lists contain an entry for an appropriate administration group with manager access, because all administration must now be done from remote clients. Agents could be written to crawl the server and return the required information in an appropriate format.
Recommendation

Make sure that all databases and templates allow manager access to all users responsible for their administration.

Once the installation is completed, the customized design elements can be reapplied using the audit list to check and track the changes that are required. See 12.2.5, Install a new release of server code on page 247.

12.1.3 Pre-installation upgrade requirements


The importance of backups during the upgrade project cannot be stressed too much. Refer to Chapter 14, Data backup on page 283 and subsequent sections for details regarding backing up the contents of the OS/390 file systems.

234

Lotus Domino for S/390 R5 Installation, Customization and Administration

Recommendation

Ensure that a complete backup is taken of any server prior to carrying out any of the upgrade procedures detailed in this chapter. To reverse a software upgrade by restoring from backup will be significantly easier and less time consuming than having to re-install and configure original software.

Before actually installing new code on a server there are some steps that can be taken to prepare for the install. As mentioned in 12.1.1, Planning the order of your upgrade on page 231, the public NAB can be upgraded on all servers in the domain since it contains all of the information required by an R4.x or even R3.x server. Any new features or information added to the forms for use by an R5 server are ignored by servers running older releases of the software. The following sections detail the steps to upgrade the design of the public NAB and also changes that need to be made to the notes.ini file just prior to installation of the R5 software.
12.1.3.1 Upgrading the Public Name and Address Book Upgrading the design of the public NAB is a straightforward task and is much the same as changing the design of any database. The test environment recommended in 12.1.2.1, Defining a test environment on page 233 should be used to perform a test upgrade from the R4.x design to the new R5 Domino Directory design. Once it is confirmed that the R4.x server will operate correctly with this new design, the production NAB can be upgraded as described below.

The new template for the R5 Domino Directory has the same filename, pubnames.ntf, and the same template name, StdR4PublicAddressBook, as the existing NAB template. There are two possible ways to upgrade the design.
Note: The very first step must be to make a backup of both the existing public NAB and the template from which it inherits its design before attempting to upgrade to the Domino Directory.

Replace the existing R4.x NAB template This procedure assumes that the R5 template is present on an administrators R4.x client machine and is ready to be placed on the servers, and that the administrator has permission to overwrite the existing template on the chosen server.
1. Choose a server from which design changes will replicate to all other servers in the domain, usually a hub server. 2. Choose File -> Database -> Open from the Notes client menu; the dialog box shown in Figure 163 on page 236 will be displayed.

Upgrading the Domino Server

235

Figure 163. Adding the pubnames.ntf icon to the desktop

3. Ensure that the entry in the box labelled Server is Local. 4. Press the Tab key twice so that the cursor moves to the input box labelled Filename. 5. Overtype any existing filename with pubnames.ntf 6. Click Select Icon to place the icon on the current workspace and then Done to return to the workspace. 7. Click the template icon once so that it is selected on the desktop. 8. Choose File -> Replication -> New Replica from the client menu and the New Replica dialog box shown in Figure 164 will appear.

Figure 164. Creating a new database replica

9. Change the entry in the Server input box to match the server on which the new template will be replicated. 10.Ensure that the options for Immediately and Copy Access Control List are selected. 11.Click OK and then confirm that you wish to replace the existing file named pubnames.ntf. 12.Click Yes to confirm replacement and complete the process of replacing the existing R4.x template with the new R5 one.

236

Lotus Domino for S/390 R5 Installation, Customization and Administration

13.The decision can then be made to force replication to other servers or wait for scheduled replication to propagate the new template to the other servers in the domain. 14.The Design task will upgrade the NAB during its next scheduled execution on each server.
Note: If there are servers that should not have their NAB upgraded at this time, then the replication of the template to these servers must be disabled or restricted before replacing pubnames.ntf. The template on the server to be left with an R4.x NAB can either have the option Temporarily disable replication selected in the Replication Settings dialog box, or the access control list of the templates should be modified to not allow any design changes to be propagated.

Replace the existing R4.x NAB design As with the first method, this procedure assumes that the R5 template is present on an administrators R4.x client machine and is ready to be used to replace the design of the existing NAB, and that the administrator has permission to replace the design of the NAB on the chosen server.
1. Choose a server from which design changes will replicate to all other servers in the domain, usually a hub server. 2. Click on the NAB icon once so that it is selected on the desktop. 3. Choose File -> Database -> Replace Design from the Notes client menu and the Replace Database Design dialog box, shown in Figure 165, will be displayed.

Figure 165. Replacing the design of the Public NAB

4. Ensure that the entry in the box labelled Template Server is Local. 5. Scroll down the list of templates and select Domino Directory; the filename next to the About button should reflect the name of the template, usually pubnames.ntf. 6. Inherit future design changes is selected by default.
Note: If you choose to Inherit future design changes at this point, then the R4.x pubnames.ntf template must be replaced on the servers to which this

Upgrading the Domino Server

237

new design will replicate, otherwise, the design task will revert the design back to an R4.x NAB when it next executes. If you do not want to have to replace the template on all servers at this time, do not select Inherit future design changes. 7. Click Replace to continue; the warning shown in Figure 166 will be displayed.

Figure 166. Replace database design warning

8. Click Yes to complete replacing the design. 9. The decision can then be made to force replication to other servers or wait for scheduled replication to propagate the new design.
12.1.3.2 Preserving directory design customizations The procedures detailed previously for updating the design of the NAB assume that a direct replacement for the standard design is required. In many environments the design of the NAB may have been customized by administrators or application developers to support specific application or administration needs. Under these circumstances, a direct replacement is clearly not a good idea.

Follow these steps to reproduce the design customizations that are still required, in the test environment, to create a new customized template: 1. Create a backup of the existing NAB and template that contain the customizations. 2. Upgrade a test copy of the R4.x NAB with the standard R5 design. 3. Use this design on one of the test servers to verify that the server operates correctly. 4. Apply the customizations to this upgraded design. 5. Create a new R5 customized template from this database design, giving it a name other than pubnames.ntf to distinguish it from the original. 6. Use one of the methods described in 12.1.3.1, Upgrading the Public Name and Address Book on page 235 to upgrade the design using this new template. Wherever reference is made to pubnames.ntf, substitute the name given to the newly customized template. To simplify the task of determining what elements have been added or removed from the design, they are listed for reference in 6.5, Running the installation program on page 90.
12.1.3.3 New database options There is a set of options you can specify during database creation to provide higher performance and function for specific uses. For example, unread marks

238

Lotus Domino for S/390 R5 Installation, Customization and Administration

can be disabled for individual databases to avoid the sometimes substantial overhead of maintaining unread marks for all users of the database. When you change the attributes of a database, run compact on it twice to ensure that the new attributes are set.
12.1.3.4 Administration during the upgrade period Since the new R5 database designs make extensive use of a feature called tabbed tables, administering forms that use this feature from an R4.x client is possible but difficult.
Recommendation

Administrators should have their clients upgraded to R5 in readiness for the start of the upgrade process so that they can view the database contents correctly and take advantage of the new features of the Administration Client, see 16.1, Installing the Lotus Domino Administrator client on page 325.

In addition, the R5 software imposes some limitations in the creation and use of ID files. An R4.x client must be retained if either of the two following scenarios apply to the environment: 1. New ID files are required for use by an R3.x client. 2. Flat (non-hierarchical) ID files are required and new ones need to be created. However, R5 fully supports the maintenance of existing flat ID files. The renewal of existing flat certificates and the certification of new hierarchical ID files with a flat certificate are supported.
Recommendation

If the environment still uses flat ID files, consider moving to a hierarchical certification model for increased security, flexibility of access control and simpler administration through use of the administration process.

12.1.3.5 Updating the contents of the Domino Directory When the Domino Directory is opened for the first time after upgrade, a form called the Domino Directory Profile is presented, which must be completed. This form is shown in Figure 167 on page 240, as seen using an R5 client:

Upgrading the Domino Server

239

Figure 167. Editing the Domino Directory profile

The fields and their meanings are listed in Table 23.


Table 23. Fields used in the Domino Directory profile

Field Name Domain defined by this directory Directory catalog filename for domain Sort all new groups by default

Description The Notes domain for this directory - completed automatically when the server is configured The filename of the directory catalog database if one is to be created Select Yes to automatically sort alphabetically the members of each new group created - performance slows if yes is selected. Select No to have members displayed in the order in which they were added to the group - member list can be sorted as needed.

Use more secure Internet passwords Allow the creation of alternate language information

Select Yes to use strong encryption for Internet passwords or No to use basic encryption. Select Yes to allow creation of alternate language documents to be used in LDAP directory queries or No to prevent creation.

12.1.3.6 Modifying the NOTES.INI file This procedure should be carried out once the server has been shut down and is ready to be upgraded.

Domino R5 no longer uses the Report task for statistics reporting and collection. The file statistics collection once performed by Report is now done by the Directory Catalog task instead. In addition, the Collector task is used to enable a

240

Lotus Domino for S/390 R5 Installation, Customization and Administration

server to collect its own statistics or to act as a central gathering server for others in the domain, in the same way that servers could be designated collectors in R4.x. To remove the Report task from the notes.ini file, do the following at a UNIX shell command prompt:

# cd /domino1/notesdata # /usr/lpp/lotus/bin/tools/viascii notes.ini

Figure 168. Editing the notes.ini file

This will open the notes.ini file using the viascii editor, see C.5, Using the UNIX vi editor on page 407 for details of available commands for use in this editor. In a TSO OMVS you can use the oeditascii editor. Scroll down the file to the line that starts ServerTasks= as shown in Figure 169.

EDITEXP23=Word for Windows 6.0,2,_XW4W,W4W49T/V0,.DOC,,2, DDETimeout=10 $$$OpenSpecial=NotesNIC $$$NotesNIC=CN=Home/OU=Notes/O=NET, welcome.nsf, Notes NIC Welcome, Notes Networ k Information Center on the Internet ServerTasks=Replica,Router,Update,Stats,AMgr,Adminp,Sched,CalConn,Event,Report ServerTasksAt1=Catalog,Design ServerTasksAt2=UpdAll,Object Collect mailobj.nsf ServerTasksAt3=Object Info -Full ServerTasksAt5=Statlog :wq

Figure 169. Removing the Report task from the notes.ini file

If one of the tasks listed along this line is report, then delete it from the line by moving the cursor to the r of report and pressing the x key, which should delete a letter at a time. Once the word is removed, save and exit the modified file by pressing Escape, then type :wq (as shown above) and press Enter. If any of the following entries exist in the notes.ini file, then they should also be removed: NSF_Buffer_Pool_Size= NSF_DbCacheMaxEntries= Server_Name_Lookup_Noupdate= Any other debugging parameters

Some other entries in the notes.ini file may be ignored by the R5 server. Many of these now have an equivalent setting option on a server configuration document and do not need to be listed explicitly in the notes.ini file. They will not impact server performance if left in the file, but they should be noted so that after upgrade the equivalent options can be completed in the relevant fields on the configuration forms.

12.1.4 System requirements


Prior to installation of the R5 server software it is necessary to ensure that the server hardware and supporting software, such as the operating system, meet or

Upgrading the Domino Server

241

exceed the specified requirements as defined in Chapter 5., Prepare to install the Domino Server on page 71. If the current system does not meet the new requirements, then to continue with the Domino Server upgrade, those elements of the platform that do not meet these requirements must be upgraded first.
Note: It is important to remember that the OS/390 platform does not include a Notes or Administration client component. See 16.1, Installing the Lotus Domino Administrator client on page 325 for details about installation of the Administration client on other platforms.

12.1.5 Task checklist


Table 24. The tasks required to upgrade the Domino Server code

Task
Stop Domino server Back up the current server files Upgrade operating system software Remove symbolic link to existing server code Remove the Notes binary directory Check HFS space requirements Install new release of server code Migrate directory/database links to Domino R5 Upgrade searching and indexing Upgrade MAIL.BOX Domino directory compaction and indexing Start the server Server task and API program testing Additional system databases upgrade Upgrade Domino mail topologies

Date Completed

12.1.6 Stop the Domino Server


Shut down the Domino server by typing exit or quit. See Chapter 9, Start, stop and monitor the server on page 127.

12.2 Upgrade operating system software


First back up your files as described below. Then read the installation documentation provided with the new Domino Server release and upgrade the operating system software as required. In particular, check for new PTFs that are needed. See Chapter 3, Prerequisites on page 51. Stop the server before performing the upgrade.

242

Lotus Domino for S/390 R5 Installation, Customization and Administration

12.2.1 Back Up the current server's files


Back up all the data in your current Domino Server. This includes the HFS data sets containing the server code and the Notes and mail data, and the LPA (if Domino 4.x) and Dynamic LPA data sets created by the ALOCPROD job that hold the Domino executable code. When installing the new release of the Domino code, you will reuse the current HFS. Also make backup copies of any templates or files that you have modified or customized so that you can restore them later. To back up the data, do the following: Back up the HFS data sets as described in 14.6, Backup using DFSMSdss on page 296. Back up the UNIX files from a UNIX shell command prompt such as TSO OMVS or rlogin: 1. Create a backup directory to hold the existing data with the command:
mkdir /savedata

You may wish to put this directory in a separate HFS data set. See 13.1, Creating and mounting HFS data sets on page 269 for details. 2. Back up the existing server code with the command:
tar -cvzf /savedata/backupprod.tar -C /usr/lpp/lotus

3. Back up the Notes data directory with the command:


tar -cvzf /savedata/backupdata.tar -C /domino1/notesdata

Back up the LPA (if using Domino 4.x) and Dynamic LPA data sets from ISPF: 1. Create backup data sets with the same formats as the LPA and Dynamic LPA data sets using ISPF option 3.2. 2. Copy the contents of the data sets to the backup data sets using ISPF option 3.3 or IEBCOPY. 3. Delete all the members in the data sets and then compress them using ISPF option 3.1.

12.2.2 Remove the symbolic link to existing server code


The symbolic link /usr/lpp/lotus/notes/latest points to the Domino server code. You need to remove the link to the old server code with the UNIX command:
rm /usr/lpp/lotus/notes/latest

Then when you install the new level of the code, this link will be recreated and point to the new level of code. Figure 170 on page 244 shows a command sequence that you could use, and the effect of the rm command.

Upgrading the Domino Server

243

cd /usr/lpp/lotus/notes ls -al total 64 drwxr-xr-x drwx-----drwxr-xr-x lrwxrwxrwx rm latest ls -al total 24 drwxr-xr-x drwx-----drwxr-xr-x

<== Change directory <== List contents of directory

4 4 4 1

MACFAD6 MACFAD6 MACFAD6 MACFAD6

SYS1 SYS1 SYS1 SYS1

0 0 0 4

Jul Jun Jul Jul

16 12 16 16

10:49 14:15 10:47 10:49

. .. 4600 latest -> 4600

<== Remove the link <== List contents of directory again 4 MACFAD6 SYS1 4 MACFAD6 SYS1 4 MACFAD6 SYS1 0 Jul 16 10:49 . 0 Jun 12 14:15 .. 0 Jul 16 10:47 4600

Figure 170. Remove the symbolic link to server code

12.2.3 Remove the Notes binary directory


The Notes binary directory usr/lpp/lotus contains, amongst other things, symbolic links and the tools subdirectory. You need to delete this directory with the UNIX command:
rm -Rf /usr/lpp/lotus/

12.2.4 Check HFS space requirements


You need at least 300 MB free to be able to install Lotus Domino for S/390 Release 5. Enough free space may be available in the current HFS data sets, or it may be obtained by the HFS data set expanding if you have defined it with multiple extents and there is enough free space on the DASD volume. We recommend that a storage administrator check whether the space is available using ISMF. For procedures to manage HFS data sets, see 13.2, Space management on page 272.
12.2.4.1 Additional disk space considerations For a new installation of an R5 Domino Server, the system requirements referenced in the previous section provide a good starting point in terms of the disk capacities required. However, when upgrading an existing server some of the changes made to enhance the functionality of R5 increase the amount of disk space that will be needed, not only for storing databases but also for core server processes:

1. Existing databases converted to the new R5 On-Disk Structure (ODS) will, in the majority of cases, take up a very similar amount of disk space as they do using the current R4 ODS. However, the index directories for databases that have full-text indexes will increase by approximately 50 percent. 2. New mail databases now have both Notes and Web browser access functionality integrated into a single database design; a new empty mail database has a default size of approximately 5 MB as opposed to 2 MB for an R4.6 mail database.

244

Lotus Domino for S/390 R5 Installation, Customization and Administration

3. The new R5 indexing algorithm now produces temporary working files while it is building or updating database and full-text indexes. The amount of space required for these files depends on the number and size of the databases hosted on the server. By default, the temporary files are created in the server data directory as specified by the operating system. For optimal performance of the indexing process, it is better to store the temporary files on a different physical disk to the Domino data directory.
Indexing File Location

To change the location in which temporary files are stored during indexing, specify
View_Rebuild_Dir=/directoryname

in the servers notes.ini file

4. The introduction of Transaction Logging creates another requirement for additional disk space that was not necessary with previous releases of the Domino Server. Instead of always writing data directly to the database, transaction logging allows for writes to a central location on disk that can be replayed intermittently against the databases to commit the actual changes to the data stored in the database. Once again, optimal performance is achieved if the transaction logs, known as the Transaction Log Extent, are located on different physical disks to the Domino data directory so that writes to the logs and read requests for databases do not compete with each other.
Transaction Log Extent

To change the location in which the transaction logs are stored, edit the server document as shown in Figure 171 on page 246, and change the value for the field Log path on the Transaction Logging tab.

Upgrading the Domino Server

245

Figure 171. Changing the location of the Transaction Log Extent

A minimum of 200 MB of free space must be available to enable transaction logging, but unlike view indexing, a maximum size can be stipulated for the Transaction Log Extent. The maximum size allowed is 4 GB, and with circular logging enabled, disk space is reused by overwriting older log entries.
Note: If you are going to run transaction logging on a system that runs DFSMS 1.4 or below, you are limited to the size of a single physical disk. Therefore, you may not be able to have a 4 GB transaction log.
Recommendation

Since the transaction logs are critical to data integrity and maximum performance, we also strongly recommend that the disk used to contain the Transaction Log Extent be mirrored and, if possible, connected to a separate disk controller than that used to service the Domino data directory.

Domino R5 can now support significantly larger databases than previous releases, and although currently certified up to 64 GB, there is no imposed maximum size. To take advantage of this capacity, the OS/390 system must be running DFSMS 1.5.

246

Lotus Domino for S/390 R5 Installation, Customization and Administration

12.2.5 Install a new release of server code


The upgrade installation of the R5 code can be performed over the existing installed release, providing it is currently at release R4.1 or higher. See Chapter 5, Prepare to install the Domino Server on page 71, for the specific details of installing the R5 software for OS/390 and the necessary prerequisites to doing so.
Recommendation

To ensure the greatest level of stability and ease of upgrade, it is recommended that the current release of the code be brought up to the latest Quarterly Maintenance Release (QMR).

During the install, the program and data directories displayed by the install routine may not match the directory names in which the current program and data are stored. These must be changed as detailed below: 1. When prompted to supply the program directory, press Enter to change the setting. 2. Type in the new directory name to match the currently used program directory, and press Enter to confirm as shown in Figure 172.

=============================================================================== Domino Server Installation ===============================================================================

The program directory is the path where the Install program installs the Domino program files. The Install program automatically adds "lotus" to the path. ------------------------------------------------------------------------------Press ENTER to retain the current setting or Type a new setting and press ENTER. ------------------------------------------------------------------------------Current program directory setting : /usr/lpp/lotus

Figure 172. Changing the program install directory during upgrade

3. When the new directory is displayed, press Tab to continue. 4. When prompted to supply the Notes data directory, press Enter to change the setting. 5. Type in the new directory name to match the currently used data directory, and press Enter to confirm as shown in Figure 173 on page 248.

Upgrading the Domino Server

247

=============================================================================== Domino Server Installation =============================================================================== The data directory is the path where the Install program installs the Domino data files. ------------------------------------------------------------------------------Press ENTER to retain the current setting or Type a new setting and press ENTER. ------------------------------------------------------------------------------Current data directory setting : /local/notesdata New data directory setting : /domino1/notesdata

Figure 173. Changing the data install directory during upgrade

6. When the new directory is displayed, press Tab to continue. Once the software has been installed, customizations must be reapplied to templates that come shipped with the product. See 12.1.2.3, Database design considerations on page 234. Examples of such templates are: pubnames.ntf admin4.ntf log.ntf

12.2.6 Migrating directory/database links to Domino R5


In past releases of Domino for OS/390, database and directory links were stored in ASCII in the HFS. For Domino R5, directory and database links are now in native EBCDIC. To migrate all existing directory/database links in the Notes data directory, here is one method: A shell script called migratelinks.sh is provided in /usr/lpp/lotus/bin/tools. This script must be run from the Notes data directory for the server in question. This script searches the Notes data directory and converts all directory/database links to EBCDIC. This enables the links to function properly.

12.2.7 Upgrade MAIL.BOX


To take advantage of the new R5 on-disk structure (ODS) and performance enhancing features of the new R5 router mail box design, the mail.box file must be upgraded. Before the server is restarted, rename the file mail.box to mail.old. For example, see Figure 174. Enter the following commands at a UNIX shell command prompt:
# cd /domino1/notesdata # mv mail.box mail.old

Figure 174. Renaming MAIL.BOX

When the server is eventually restarted, it creates a new router mail box, mail.box. To improve performance and reduce disk space requirements, the

248

Lotus Domino for S/390 R5 Installation, Customization and Administration

database properties should be changed. See 12.2.11, Modifying Mail.box properties on page 250 for these steps.

12.2.8 Domino directory compaction and indexing


The design of the Domino Directory was upgraded in a previous stage of the upgrade; see 12.1.3.1, Upgrading the Public Name and Address Book on page 235. Now that the server has R5 software installed, some additional steps must be taken to complete this process. To take advantage of the performance and new features of the R5 ODS, it is necessary to compact the Domino Directory database twice.
Note: The first compact upgrades the database structure to the R5 ODS. The second compact enables any database properties that have been chosen, such as dont retain unread marks or allow soft deletions.

Perform these steps at a UNIX Shell command prompt before the server is restarted after upgrade.
12.2.8.1 Compact and view index rebuild 1. Type whoami and press Enter to determine the name of the current user.

2. If the current user is not the user defined to run the Domino Server, type su domino1 and press Enter (where domino1 is the user defined to run the Domino Server).
Note: To run the su command you must be logged on as a superuser. Alternatively, you could logon with the Domino Server userid.

3. Enter the users password and press Enter. 4. Type cd /domino1/notesdata and press Enter to move to the Domino data directory for the server. 5. Type compact names.nsf and press Enter to compact the directory database; see Figure 175.

$ whoami domino1 $ su - domino1

$domino1s Password:
$ cd /domino1/notesdata $ compact names.nsf 04/02/99 15:57:16 Compacting database names.nsf (ITSOs Address Book) 04/02/99 15:57:26 Finished compacting names.nsf, 126K bytes recovered (3%) 04/02/99 15:57:26 Database compact process shutdown

Figure 175. Compacting the Domino directory (names.nsf)

6. Type compact names.nsf and press Enter again to compact the directory database for the second time (repeat of point 5). After the compact process has completed, the view indexes can be rebuilt so that they are already up-to-date prior to the server being restarted. At the UNIX shell command prompt, type updall names.nsf and press Enter as shown in Figure 176 on page 250.

Upgrading the Domino Server

249

$ updall names.nsf 04/02/99 15:58:39 Index update process started 04/02/99 15:59:01 Index update process shutdown

Figure 176. Updating names.nsf view indexes

The server is now ready to be started.

12.2.9 Start the server


When the server restarts it will still prompt to upgrade the design of the Address Book. However, since this will have been done prior to software installation, there is no need to perform this step again. You can Press N to answer No to this question.

12.2.10 Upgrade searching and indexing


R5 introduces a brand new searching and indexing engine called Global Text Retrieval (GTR). The important point to note, as mentioned previously, is that full-text indexes are approximately 50 percent larger. Indexes will be rebuilt automatically as databases are used, and since the changes have been implemented below the API level, earlier releases of the client and applications performing search functions will continue to function correctly.
Note: An administrator may run the updall task to update all databases indexes at the same time. The indexing process is very CPU intensive. If a server has many full-text indexes to rebuild its performance will be degraded for a significant period of time in which case it may be desirable to perform this task out-of-hours with the server off-line.

Although the search indexes can be used by all releases of the client, users may come across an error during index rebuilding.
Note: If users attempt to search a database that is being updated from an R4 to an R5 full-text index, they will get an error message stating that they must wait for the indexing process to complete before they can search the database.

12.2.11 Modifying Mail.box properties


When the server is restarted and you have renamed the old mail.box (as in 12.2.7, Upgrade MAIL.BOX on page 248), it will create a new router mail box, mail.box. To improve performance and reduce disk space requirements, the database properties should be changed. This should be done using an administrators R5 client who has access to change the properties of the new mail.box database. 1. Right-click on the server mailbox icon or bookmark. 2. Choose Database -> Properties from the popup menu to show the database properties. 3. Click the right-most tab in the infobox and select the three options shown in Figure 177 on page 251.

250

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 177. Setting properties for the R5 router mailbox database

Any messages that had not been transferred or routed before the server was shut down will still be in the old router mail box database, mail.old. It will be necessary to move the messages waiting in mail.old back into the router mail box, mail.box, so that they can be delivered or transferred. The steps to achieve this are as follows: 1. Start a Notes or Administration client and enter a password if prompted to do so. 2. Open the original mail router database, mail.old. 3. Select all of the messages in the Mail view. 4. Select Edit -> Copy from the client menu. 5. Close the mail.old database. 6. Open the new mail router database, mail.box. 7. Select Edit -> Paste from the client menu. 8. Once the mail has been delivered or transferred from the new mail.box, delete the original mail.old database.
Note: These steps must be carried out using a Notes ID that has manager access to both the old router mail box, mail.old, and the new router mail box, mail.box.

12.2.12 Server task and API program testing


Once the server has been started, the tasks that run outside of normal office hours or that are not core Domino Server tasks should be manually loaded to ensure that they run satisfactorily. Enter each of the following commands at the Domino Server console, followed by pressing Enter, and ensure that the tasks start, do not produce any unexpected errors, and then exit successfully. load updall load design load catalog

Upgrading the Domino Server

251

Note any error messages or problems that are encountered during this process. Finally load any other third-party add-in or API tasks in the same way and check that they perform as expected.

12.3 Additional system database upgrades


To ensure that the new R5 servers in the environment have the necessary features they require to operate to the best of their ability, some of the other system databases must be upgraded with new designs in a similar way in which the Domino directory is updated. The main databases are discussed in the following sections.

12.3.1 Administration Requests database


Once the administration server of the Domino directory has been upgraded, one of the next steps in the project should be to upgrade the design of the Administration Requests database, admin4.nsf, to take advantage of new features.
Note: After the administration server is restarted and operational, upgrade the administration requests database on this server and then replicate to the other servers in the domain.

As with other elements, backwards compatibility is ensured so that the new design can be replicated to other servers in the domain that may not yet have been upgraded, and they will continue to operate successfully. To enable a faster upgrade, outstanding requests should be processed prior to the database design upgrade. 1. Type tell adminp process all at the Domino Server console and press Enter as shown in Figure 178.

05/02/99 14:12:36 05/02/99 14:17:40

Periodic full text indexer terminating Searching Administration Requests database.

> tell adminp process all > 05/02/99 14:40:32 Checking for all requests to perform

Figure 178. Forcing adminp to process outstanding requests

Check the Administration Requests database to ensure that the outstanding actions have been completed.
Note: The upgrade process can be performed with outstanding requests in the database but may take longer to complete.

2. Shut down the admin process on the server, type tell adminp quit at the Domino Server console and press Enter. See Figure 179.

> tell adminp quit 05/02/99 14:50:48 Administration Process shutdown

Figure 179. Stopping the adminp task

252

Lotus Domino for S/390 R5 Installation, Customization and Administration

3. From an administrators client, replace the design of the database with the new template named Administration Requests (R5.0). 4. Allow or force the database to replicate to the other servers in the domain.

12.3.2 Directory Assistance database


If the Directory Assistance database is used to provide multiple domain directory support, then it should be upgraded. To upgrade the design, do the following: 1. From an administrators client, replace the design of the database with the new template named Directory Assistance with a filename of da50.ntf. 2. Allow or force the database to replicate to the other servers in the domain.

12.3.3 Statistics and Events database


As discussed in 12.1.3.6, Modifying the NOTES.INI file on page 240, the report task is no longer used by R5 and so some changes need to be made in the configuration to specify statistics collection servers. Instead of the report task, the server should load the collect task if it is to be used for either of the following scenarios: Local logging of its own statistics reports Collecting remote statistics from other servers When the R5 server is restarted, the error shown in Figure 180 is displayed on the console if the Statistics Reports database (statrep.nsf) has not been upgraded.

09/02/99 11:13:33 Event Dispatcher started 09/02/99 11:13:34 The server access view does not exist. Update the Statistics Report template

Figure 180. Error on event task startup after server upgrade

If the collect task is started on a server before the design of the Statistics and Events database (events4.nsf) has been upgraded, the error message shown in Figure 181 will be displayed.

> 09/02/99 11:22:34 Collector started 09/02/99 11:22:34 Collector: Could not locate Server Statistics Collection domino1/ITSO in the Statistics & Events Configuration database. 09/02/99 11:22:35 Collector shutdown

Figure 181. Error on collect task startup after server upgrade

The database designs should be replaced with the updated R5 templates installed on the server. Refer to 12.1.2.3, Database design considerations on page 234 for information regarding the preservation of any design customizations that may have been used. After the Statistics and Events database has been upgraded, Server Statistics Collection documents must be created or edited to ensure that statistics collection is performed properly. These can be found under the view named

Upgrading the Domino Server

253

Server Statistic Collection and there should be one document per server that will collect statistics.
12.3.3.1 Local collection To enable a server to collect its own statistics locally, it must be running the collect task and have its own Statistics Server Collection document.

1. Edit or create a new document and fill in the fields on the form. 2. On the Basics tab, enter the name of the server in the Server field. 3. Choose From the following servers and select the same server name again as shown in Figure 182.

Figure 182. Specifying a server to collect statistics

4. Switch to the Options tab. 5. Check the Log statistics to a database checkbox. 6. Enter the name of the statistics reporting database, usually statrep.nsf. 7. Enter the collection report and alarm interval values; examples are shown in Figure 183 on page 255.

254

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 183. Specifying statistics collection Intervals

8. Save and exit the document.


12.3.3.2 Remote collection The concept of remote collection of statistics introduced in R4.5 is the same in R5. Once again, any server designated as a remote collector for other servers must be running the collect task and have a Server Statistic Collection document.

A single server can be designated to collect from all other servers in the domain. It can be designated to collect from a specific list of servers or it can also be designated to collect from all servers that are not already explicitly listed in another document.
12.3.3.3 Additional monitoring tools Statistics and Event monitoring now includes the provision of timed probes -- for the server, mail and TCP/IP services. These can be used to periodically check whether the server and its services are available and responding to external requests.

The server access probe checks connectivity using Notes Remote Procedure Calls (NRPC) as made by Notes clients. The mail probe is used to test the routing connectivity between two defined servers by sending a probe message to a specific recipient on the chosen server at a given interval. Each of the TCP/IP services, such as HTTP or NNTP, can be probed to monitor availability. When a probe fails, it generates an event that can be trapped and reported in one of the usual ways, such as mail to administrators, log to database, or SNMP trap.

Upgrading the Domino Server

255

For more information on the changes to Statistics and Events, refer to the online Lotus Domino R5 Administration Help database.

12.4 Upgrading Domino mail topologies


The R5 mail router is fully backwardly compatible with previous releases of the server software. All servers can be upgraded to R5 with no changes required in the routing topology. However, to benefit from the new features, some changes will have to be implemented, which can be done with a server-by-server approach and do not all have to be made at the same time. Although this section details steps for upgrading an existing SMTP MTA server, more information on the configuration of the SMTP routing functions can be found in Chapter 10, Lotus Domino R5 and the Internet on page 163.

12.4.1 Router transfer and delivery options


After a server has had the R5 software installed, the router can be configured to perform tasks in parallel, multithreading, to increase throughput of message transfer and delivery. Firstly, multiple mail router mailboxes can be specified so that the router threads do not have to contend with each other for exclusive access to a single mail router database. To specify how many router mailboxes should be used on a server, edit the server configuration document and enter a number in the field labelled Number of mailboxes on the Router/SMTP - Basics tab of the table. An example is shown in Figure 184 on page 257.

256

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 184. Increasing the number of router mailbox databases

When the server is restarted, additional databases named mail1.box, mail2.box, etc. will be created, up to the value specified. By default, Domino allows the router to use a maximum of one transfer thread per configured port. An administrator can override this default to increase the total number of threads available to the router for mail transfer to other servers. To specify a different value, edit the field labelled Maximum transfer threads on the Router/SMTP-Restrictions and Controls-Transfer Controls tab of the server configuration document. On the same tab, the field labelled Maximum concurrent transfer threads is used to specify how many of the total number of threads are allowed to execute concurrently. If this is not specified, the default will be the value of Maximum transfer threads divided by 2. An example is shown in Figure 185 on page 258.

Upgrading the Domino Server

257

Figure 185. Increasing the maximum router transfer threads

With R5, the delivery process of the router also became multithreaded. The default value is 1. To change this value edit the field labelled Maximum delivery threads on the Router/SMTP-Restrictions and Controls-Delivery Controls tab. An example is shown in Figure 186 on page 259.

258

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 186. Increasing the maximum router delivery threads

Recommendation

The recommended range for the maximum delivery threads is 3 to 25.

The R5 router has many more controls available than the previous router or SMTP MTA. These can be implemented through fields on the server configuration document found in the Router/SMTP-Restrictions and Controls and associated tabs.

12.4.2 SMTP/MIME considerations


The R5 router now supports native SMTP routing/delivery, and MIME format storage. When an R5 server routes a MIME message to an R4 server, it first converts it back to the Compound Document (CD) format because the R4.x server does not understand native MIME, but it also attaches a copy of the full MIME content so that message fidelity is preserved should that message be required by a MIME-compliant client at a later stage. In a mixed environment, to deliver a Notes CD format message, the R5 server utilizes the field Format preference for incoming mail on the Mail tab of the person document of a recipient to determine the users message format preference. See 12.4.4.8, Defining a users Internet mail storage options on page 265. The R5 router then delivers a message to that user in the format indicated by that setting.
259

Upgrading the Domino Server

Note: Person documents in the Domino directory must be updated for users with a MIME-compliant client, such as Notes R5, and for use with POP3/IMAP access protocols when accessing an R5 server.

12.4.3 Considerations in a mixed-release cluster


Should clustering be used to provide resilience during the upgrade process, then there are some important points to note, especially if some clients and mail databases have been upgraded to R5 before all of the servers: 1. The R5 mail template uses features not available in releases of Domino prior to R4.6.3b, so a client failing over to an R4.x server will have a reduced feature set and may even be subjected to error messages if the other cluster members are not running R4.6.3b. 2. R4 servers do not support soft deletions. The trash folder on an R4 server appears to contain all the documents in the mail file, and although this may be intimidating, it can be ignored. 3. R5 servers can deliver native MIME, but R4 servers cannot. Thus, when a Notes client fails over to an R4 server from an R5 server, MIME messages are converted to Notes format documents and appear different than when viewed on the R5 server. 4. Attempting to send a MIME message through an R4 server means that the message must be converted to Notes format with an attachment containing the original MIME. 5. Though failover is indicated in the Notes status bar at the bottom of the screen, this is not obvious and a failover from an R5 to an R4 server may not be apparent. However, as noted above, there are changes in functionality between R5 and R4 in clusters. Details of clustering Domino Servers can be found in 11.4, Domino server clustering on page 200.

12.4.4 Upgrading an SMTP MTA server


Where SMTP MTA servers exist in a domain, other R5 servers not configured to route SMTP mail themselves will recognize and use the routing information in the Domino directory to continue to route mail to the MTA for ongoing delivery outside of the local domain. This gives flexibility in terms of when MTA servers are upgraded; SMTP can be implemented all at once, gradually, or not at all. There are three main upgrade strategies for the MTA servers: 1. Leave the existing R4.x MTA in place until all other elements are upgraded. 2. This ensures a known level of service for SMTP traffic during the upgrade process. However, it does not allow other upgraded elements to take advantage of new features and imposes conversion processing for mail to be delivered to the R4.x MTA. 3. Replace all MTAs with R5 mail servers first. 4. This allows immediate access to new R5 SMTP features and enhanced performance but still requires message conversion for mail routing to the other servers until they are upgraded. 5. Replace all MTAs with R5 mail servers during system upgrade.

260

Lotus Domino for S/390 R5 Installation, Customization and Administration

6. In larger environments, this strategy allows the MTA servers to be upgraded at the same time as other servers in their vicinity, to which they route the majority of their SMTP traffic. 7. Redesign the Internet messaging infrastructure. 8. In an R4.x messaging infrastructure, the nature of the SMTP implementation dictated that specific servers be designated to perform SMTP routing functions to locations outside of the local domain. With R5, this restriction is no longer necessary since all servers can route natively to any remote location or via some relay host such as a virus scanning server or firewall. Once mail servers that used to route via the MTA have been upgraded, the MTA is no longer required and does not need to go through the upgrade process. The following sections describe the stages through which an existing R4.x SMTP MTA server can be upgraded to a native R5 SMTP mail server.
Note: As noted earlier, ensure that a full backup of the system is taken prior to commencing the upgrade process. 12.4.4.1 Disabling MTA housekeeping MTA housekeeping must be disabled. If it is left enabled, then after housekeeping is performed it will restart the MTA and inbound/outbound transport will be available, which may contaminate work queues that have been cleared down ready for the upgrade. To disable housekeeping:

1. Open the server document in the Domino directory. 2. Click the MTAs tab. 3. Click the R4.x Internet Message Transfer Agent (SMTP MTA) section header to expand the section. 4. Change the value of the field Enable daily housekeeping to Disable as shown in Figure 187 on page 262.

Upgrading the Domino Server

261

Figure 187. Disable MTA daily housekeeping task

5. Save and close the document


12.4.4.2 Shutting down the router Shutting down the router prevents any new messages being delivered from internal sources into the smtp.box database for processing. To stop the router, type tell router quit at the Domino Server console and press Enter as shown in Figure 188.

> tell router quit 08/02/99 16:10:01 Router: Shutdown is in progress 08/02/99 16:10:01 Mail Router shutdown

Figure 188. Stopping the mail router

12.4.4.3 Shutting down the inbound message transport task To allow the work queues to be cleared of any messages prior to upgrade, the task that accepts inbound routing connections must be disabled. To do this, type tell smtpmta stop inbound transport at the Domino Server console and press Enter as shown in Figure 189 on page 263.

262

Lotus Domino for S/390 R5 Installation, Customization and Administration

> tell smtpmta 08/02/99 16:15:05 08/02/99 16:15:05 08/02/99 16:15:05 08/02/99 16:15:05

stop inbound transport SMTPMTA: isesctl Shutting down SMTPMTA: iseshlr0 Shutting down SMTPMTA: iseshlr0 Shutdown complete SMTPMTA: isesctl Shutdwon complete

Figure 189. Stopping the SMTPMTA inbound message transport task

12.4.4.4 Clearing down the work queues Using a Notes or Administration client, check the databases Outgoing SMTP Mail (smtp.box), SMTP Inbound Work Queue (smtpibwq.nsf) and SMTP Outbound Work Queue (smtpobwq.nsf) to ensure that all pending messages are processed by the MTA. Any dead messages can be ignored; they will not be routed, but it may be worthwhile noting details so that the sender or recipients can be notified later that they had a problem with those messages.

Once the queues are clear, the server can be shut down. Type quit at the Domino Server console and press Enter.
12.4.4.5 Editing the NOTES.INI file To remove the SMTPMTA task from the notes.ini file, do the following at a UNIX shell command prompt:

# cd /domino1/notesdata # /usr/lpp/lotus/bin/tools/viascii notes.ini

Figure 190. Editing the notes.ini file

This will edit the notes.ini file using the UNIX viascii editor. You can also edit the notes.ini from a TSO OMVS session with the oeditascii editor. For details see D.1.2, Edit from an OMVS session using oeditascii on page 411, or D.1.3, Edit from rlogin or Telnet using viascii on page 411. Scroll down the file to the line that starts with ServerTasks= as shown in Figure 191.

EDITEXP23=Word for Windows 6.0,2,_XW4W,W4W49T/V0,.DOC,,2, DDETimeout=10 $$$OpenSpecial=NotesNIC $$$NotesNIC=CN=Home/OU=Notes/O=NET, welcome.nsf, Notes NIC Welcome, Notes Networ k Information Center on the Internet ServerTasks=Replica,Router,Update,Stats,AMgr,Adminp,Sched,CalConn,SMTPMTA ServerTasksAt1=Catalog,Design ServerTasksAt2=UpdAll,Object Collect mailobj.nsf ServerTasksAt3=Object Info -Full ServerTasksAt5=Statlog :wq

Figure 191. Removing the SMTPMTA task from the notes.ini file

One of the tasks listed along this line is smtpmta. To delete it move the cursor to the s of smtpmta and press the x key, which should delete a letter at a time. Once the word is removed, save and exit the modified file by pressing Escape, then type :wq (as shown) and press Enter.

Upgrading the Domino Server

263

12.4.4.6 Configuring SMTP on the server configuration document Edit the server configuration document for this server. If one does not already exist for this serve, then one must be created as follows:

1. Start the administration client. 2. Select the required server from the bookmarks. 3. Click the Configuration tab. 4. Open the server panel and click Configurations. 5. Select the configuration document and press Edit Configuration. If one does not exist, then click Add Configuration. An existing document is shown in the view in Figure 192.

Figure 192. Adding or editing a server configuration document

6. Enter a group or server name in the field Group or Server name. 7. Complete all required fields found under the Router/SMTP and MIME tabs. 8. Save and close the document.
12.4.4.7 Enabling the SMTP listener task To make the servers router aware that it is to accept incoming SMTP mail connections, the SMTP listener task must be enabled:

1. Edit the server document. 2. On the Basics tab, change the value of the SMTP listener task field to be Enabled as shown in Figure 193 on page 265.

264

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 193. Enabling the SMTP listener task

3. Save and close the document. 4. Restart the server to ensure all configuration changes are invoked.
12.4.4.8 Defining a users Internet mail storage options Each person document contains a field that the R5 router uses to determine whether a user prefers to receive messages in Notes or MIME format.

Once a server is upgraded to R5, this field should be populated for all users who have their mail delivered on that server to ensure they receive messages in the best format for the client that they are using; the choices are: No Preference -- recommended because backward compatibility is guaranteed Prefers MIME Prefers Notes Rich Text
12.4.4.9 Configuring relay host information In many R4.x MTA installations, the server is configured to relay all SMTP messages to a relay host, often a virus scanner or firewall. By entering a value in the field labelled Relay host for messages leaving the local Internet domain on the server configuration document, the server will relay all SMTP mail that is bound for an address outside of the local domain to this host.

Upgrading the Domino Server

265

This directly replaces the SMTP connection document that used to specify a relay host. In addition, a smart host can be specified in the field labelled Local Internet domain smart host through which all messages are routed if the server cannot find a match for the recipients address in the directory and the address is in the local Internet domain. Examples are shown in Figure 194.

Figure 194. Setting a relay host and smart host for external SMTP traffic

12.4.4.10 R4.x vs. R5 configuration The global domain documents that were used by R4 are still used by the R5 router to get information about the local Internet domains for which it will process and route mail.

The foreign SMTP domain document is no longer required by an R5 router. Domain routing restrictions are specified on the Restrictions and Controls tab of the server configuration document. The SMTP connection document is no longer required by an R5 router. Details of the relay host are specified on the Router/SMTP--Basics tab of the server configuration document. The configuration settings specified in the Internet Message Transfer Agent (SMTP MTA) section of the server document are now either superseded by those

266

Lotus Domino for S/390 R5 Installation, Customization and Administration

available on the server configuration document, or are no longer required by the R5 router. For detailed descriptions of the fields used, refer to the document Configuration in R4 vs. R5 in the Lotus Domino R5 Administration Help database.

12.5 Recovering from a failed upgrade


Provided that a full backup of the server is taken prior to any upgrade work being started, to recover from a failure in the upgrade process should be a relatively straightforward task. If, however, for any reason a backup cannot be used to restore the original state of the server, then there are several things to consider. If the compact task was run on the R5 server, then all of the databases will have been converted to the R5 ODS. If the R4.x server software is reinstalled, it will not be able to read the contents of the databases. Prior to reinstalling R4.x, the R5 version of the compact task must be used to revert back to the R4 ODS. To do this, using the Telnet command prompt, do the following: 1. Type whoami and press Enter -- to determine the name of the current user. 2. If the current user is not the user defined to run the Domino server, type su domino1 and press Enter (where domino1 is the user defined to run the Domino server).
Note: To run the su command, you must be logged on as a superuser. Alternatively, you could logon with the Domino Server userid.

3. Enter the users password and press Enter. 4. Type cd /domino1/notesdata and press Enter to move to the Domino data directory for the server. 5. Type compact -r and press Enter to compact the directory database (see Figure 195).

$ whoami domino1 $ su domino1 dominos Password: $ cd /domino1/notesdata $ compact -r

Figure 195. Reverting databases back from R5 to R4 ODS

Upgrading the Domino Server

267

Note

This process will only revert databases, not templates. If any templates have been manually compacted then the following command must be used to revert them back to the R4.x ODS
compact <template>.ntf -r

where <template> is the first part of the template filename. Also, templates on another server still running R4.x could be copied to this server to replace those that have been compacted.

To prevent this from happening unintentionally until confident that the server does not need to be downgraded back to R4.x, the following options may be considered: Disable the automatic running of the compact task. Rename databases to use a .ns4 extension. Disallow the creation of new or replica databases on the server.
Note: The above options limit the risk of a database being automatically changed to an R5 ODS, but they will not prevent administrators with sufficient access rights from manually compacting from their workstation client.

Any changes made to the notes.ini file (see 12.1.3.6, Modifying the NOTES.INI file on page 240) should be reversed. For more information on how to migrate a Domino environment, refer to http://notes.net/doc and the book Moving to Notes and Domino R5.

268

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 13. HFS data set management


We discussed how Domino data is stored in Hierarchical File System (HFS) data sets in 2.12, Notes directory structure on page 30. This chapter discusses management of the HFS data sets: Creating new HFS data sets Mounting HFS data sets Space management Using DFSMS 1.5 to allocate a multi-volume HFS

13.1 Creating and mounting HFS data sets


The job ALOCPROD provided with the Lotus Domino Server for OS/390 gives an example of allocating a new HFS data set and mounting it on the system. Here we show the tasks as three separate jobs, and discuss the considerations for each one.

13.1.1 Creating a new HFS data sSet


The job shown in Figure 196 could be used to create a new HFS data set called OMVS.SC67.DOMR5.DOMINO1.DATA.HFS.

//DOMINO1 JOB ,D1ANDRE,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A //DOMALL EXEC PGM=IEFBR14 //NOTEPROD DD DSN=OMVS.SC67.DOMR5.DOMINO1.DATA.HFS, // DISP=(NEW,CATLG,DELETE), // DCB=(DSORG=PO), // SPACE=(CYL,(100,50,1)), // STORCLAS=OMVSSC, // DSNTYPE=HFS //
Figure 196. Sample job to create an HFS data set

Notes:

1. HFS data sets must be SMS managed. The storage class STORCLAS tells SMS what facilities this HFS data set requires. It may also be used by the SMS ACS routines to direct the data set to a particular storage group. 2. The DSNTYPE is HFS, which tells OS/390 that this is an HFS data set.

13.1.2 Creating a mount point


A mount point is a path name on which a file system is mounted. We create mount points in the root file system on which to mount our Domino file systems. You create a mount point in the hierarchial file system by using the UNIX

Copyright IBM Corp. 1999

269

command mkdir. This could be run in a number of ways, firstly by using a batch job as shown in Figure 197.
//DOMINOA JOB ,D1ANDRE,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A /*JOBPARM SYSAFF=SC67 //IKJEFT01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * MKDIR '/domino1/notesdata' MODE(7,5,5) /* //
Figure 197. Sample job to create a mount point

Notes:

1. The JOBPARM is required in a multiple system environment to ensure that the job runs on a specific system. The HFS data set can only be mounted onto a single system as we shall mount it in Read/Write mode. 2. Make sure that you have set CAPS OFF in the ISPF editor profile as the directory name is case-sensitive. 3. The MODE parameter sets the access permissions to the directory. (7,5,5) means that the owner has read, write, and execute permissions, and all other users have read and execute permissions. See the chmod command in OS/390 UNIX System Services Command Reference, SC28-1892, for more information. 4. Keep all of the mkdir commands that affect the root HFS data set in a separate file. If you replace the root HFS data set at some time in the future, you will need to rerun these commands to rebuild your directory structure. 5. To create a mount point in the root directory, UNIX superuser (UID=0) authority is required. You can also use the OMVS ISHELL command to create a mount point: 1. Enter the full path of the mount point: /domino1/notesdata. 2. As this is a new file, the Create new file dialog will open. 3. Specify Directory as file type and 755 for permission bits and press Enter. Finally, you can also use the UNIX shell mkdir command or the TSO command MKDIR to make a directory.

13.1.3 Mounting the HFS data sets


Before starting the Lotus Domino Server, you need to mount all of the HFS data sets that it needs. If you run the ALOCPROD job, that should already be done. If not, we recommend that you do this by issuing the mount commands automatically at IPL. One way to do this is by putting the mount commands into BPXPRMxx, as shown in Figure 198.

MOUNT FILESYSTEM('OMVS.SC67.DOMR5.DOMINO1.DATA.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/domino1/notesdata')


Figure 198. HFS mount commands in BPXPRMxx

270

Lotus Domino for S/390 R5 Installation, Customization and Administration

However, our systems ran in a Parallel Sysplex, and therefore we needed to issue different mount commands on each system. We wanted to keep BPXPRMxx common across the systems, so we used a different method to issue the correct mount commands on each system. We did this by adding the Domino server name as the symbolic variable DOMSRV to SYS1.PARMLIB(IEASYMxx) as shown in Figure 199.

SYSDEF

HWNAME(SCZP401) LPARNAME(A2) SYSPARM(R3) SYSNAME(SC67) SYMDEF(&ALLCLST1='WTOR') SYMDEF(&DFHSMHST='HN') SYMDEF(&SRES2='O33RSD') SYMDEF(&OMVSPARM='67') SYMDEF(&DOMSRV='ITSO390R') SYMDEF(&DOMINOLV='DOM50')

<====== Added

Figure 199. Define Notes Server name in SYS1.PARMLIB(IEASYMxx)

We then wrote a procedure for each Domino server to issue the mount commands for that server. So for server ITSO390R we would have member SYS1.PROCLIB(ITSO390R), which would look as in Figure 200.

//DOMIN5 JOB (999,POK),'Domino Mounts',MSGCLASS=T,TIME=1440,REGION=4M /*JOBPARM SYSAFF=SC67 //TSO EXEC PGM=IKJEFT01,REGION=4M //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * MKDIR '/usr/lpp/lotus' MODE(7,5,5) MOUNT FILESYSTEM('OMVS.DOMR5.DOMINO1.PROD.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/usr/lpp/lotus') MKDIR '/domino1' MODE(7,5,5) MKDIR '/domino1/notesdata' MODE(7,5,5) OSHELL 'chown -R DOMINO1:OEDOMINO /domino1' MOUNT FILESYSTEM('OMVS.DOMR5.DOMINO1.DATA.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/domino1/notesdata') MKDIR '/domino1/notesdata/mail' MODE(7,5,5) OSHELL 'chown DOMINO1:OEDOMINO /domino1/notesdata/mail' MOUNT FILESYSTEM('OMVS.DOMR5.DOMINO1.MAIL.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/domino1/notesdata/mail') /*
Figure 200. Procedure to issue the mount commands

This procedure is similar to the last step in the ALOCPROD job; see Figure 19 on page 79. We included the mkdir commands also. Normally the directories already exist, so those commands will fail. However, it is possible that some directories may be lost when upgrading the UNIX environment, in which case the mkdir commands will avoid the mounts failing. If the directories do not exist, it is important to set the appropriate permissions. As you cannot run the job with the userid of the Domino Server (the server will not have the superuser authority required to mount the filesystems), we included a chown command to set owner and group for the mount points. Please keep in mind that the MOUNT command

HFS data set management

271

changes the permission bits of the mountpoint to 700 if the filesystem is mounted for the first time. Each system runs the correct procedure at IPL time by adding the following statement to the relevant SYS1.PARMLIB(COMMNDxx) member for each system. COM='S &DOMSRV.'
Notes:

1. For each server, all of the mounts it needs must be included in the procedure for that server. 2. To mount a file system, UNIX superuser (UID=0) authority is required.

13.1.4 Displaying mounted HFS data sets and mount points


You can display the currently mounted HFS data sets and their mount points by using the OS/390 console command D OMVS,F or the UNIX command df. Appendix C, Useful commands on page 399 shows examples of the output from these commands.

13.1.5 Unmounting and deleting HFS data sets


You can delete HFS data sets in the same way you delete any other OS/390 data set, such as from TSO or batch. You must unmount the data set from the file system first, using a job such as shown in Figure 201.

//DOM67 JOB (999,POK),'Domino Mounts',MSGCLASS=T,TIME=1440,REGION=4M /*JOBPARM SYSAFF=SC67 //TSO EXEC PGM=IKJEFT01,REGION=4M //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * UNMOUNT FILESYSTEM('OMVS.DOMR5.DOMINO1.MAIL.HFS') IMMEDIATE UNMOUNT FILESYSTEM('OMVS.DOMR5.DOMINO1.DATA.HFS') IMMEDIATE UNMOUNT FILESYSTEM('OMVS.DOMR5.DOMINO1.PROD.HFS') IMMEDIATE /*
Figure 201. Job to unmount HFS data sets

Note: We unmount the data sets in reverse order to the mount order.

13.2 Space management


The amount of data in your Domino databases will grow over time. This is especially true for mail databases, where users tend to store additional mail as it is received. It is therefore important to monitor data space use and react to full conditions before they affect the users.

13.2.1 Domino database size


Within Domino you define the maximum size of a database. You can increase the maximum size of the database (database quota) by using the Domino Administrator. Provided there is room in the HFS data set, the database will then be able to expand. DFSMS 1.5 provides some additional capabilities in terms of database size. 13.3, DFSMS 1.5 on page 277 gives an overview of the new features.
272

Lotus Domino for S/390 R5 Installation, Customization and Administration

13.2.2 HFS data set full condition


When an HFS data set becomes full, no more data can be written to files within that HFS data set. Note that an HFS data set is only considered full when it has used up all 123 extents, or there is no free space on the DASD volume (and the HFS has not been allocated as a multi-volume data set). We did some experiments with HFS data sets getting full by allocating small HFS data sets (1 MB, 10 MB) and then using all of the space. The Notes Workstation client then saw the message in Figure 202.

Server Error: Cannot write to file (possibly it is READ-ONLY or the disk is out of space or not ready)

Figure 202. Disk full error message to Notes Workstation

Figure 203 shows the messages of the Domino Server log.


06/18/99 06:49:51 PM Opened session for Notes Admin/Itso (Release 5) 06/18/99 06:50:11 PM Router: Unable to deliver message 007D4DFF, 007D4DFF to Notes Admin/Itso@Itso from Notes Admin/Itso 06/18/99 06:50:11 PM Cannot write to file (possibly it is READ-ONLY or the disk is out of space or not ready) 06/18/99 06:50:16 PM Router: Unable to deliver message 007D7353, 007D4DFF to Notes Admin/Itso from Notes Admin/Itso 06/18/99 06:50:16 PM Cannot write to file (possibly it is READ-ONLY or the disk is out of space or not ready)
Figure 203. Domino Server log when the mail file system is running out of space

When there was insufficient DASD space during server startup, we saw, for example, the messages in Figure 204.

06/19/99 07:40:06 PM Error full text indexing document NT00000000 in database /domino1/notesdata/mtdata/mtstore.ft: Full Text Error - not enough space on disk to build index 06/19/99 07:40:08 PM Database Replicator started 06/19/99 07:40:13 PM Index update process started

Figure 204. Disk full error message on Domino Server console

13.2.3 Monitoring HFS data set utilization


Because of the impact of an HFS data set running out of space, you should monitor the space utilization on a regular basis. Standard OS/390 tools can be used to do that.
13.2.3.1 ISMF data set list The simplest way to monitor all of your HFS data sets is by using the ISMF data set list. You can request a list of all HFS data sets using a data set name qualifier such as **.HFS. The output from this is shown in Figure 205 on page 274.

HFS data set management

273

DATA SET LIST LINE OPERATOR DATA SET NAME ---(1)---- ------------(2)-----------OMVS.SC67.DOMINO5.DOMINO1. DATA.HFS OMVS.SC67.DOMINO5.DOMINO1. MAIL.HFS OMVS.SC67.DOMINO5.DOMINO1. TLOG.HFS OMVS.SC67.DOMINO5.DOMINO2. DATA.HFS OMVS.SC67.DOMINO5.DOMINO3. DATA.HFS OMVS.SC67.DOMINO5.PROD.HFS

ALLOC ALLOC % NOT SPACE USED USED --(3)-- --(4)-- -(5)688932 327257 52 54340 236174 415020 415020 581027 54340 226767 369533 257257 401020 0 3 10 38 30

Figure 205. Monitoring data set utilization from ISMF - 1

By scrolling to the right you can see additional allocation information as shown in Figure 206.

DATA SET LIST LINE OPERATOR DATA SET NAME ---(1)---- ------------(2)-----------OMVS.SC67.DOMINO5.DOMINO1. DATA.HFS OMVS.SC67.DOMINO5.DOMINO1. MAIL.HFS OMVS.SC67.DOMINO5.DOMINO1. TLOG.HFS OMVS.SC67.DOMINO5.DOMINO2. DATA.HFS OMVS.SC67.DOMINO5.DOMINO3. DATA.HFS OMVS.SC67.DOMINO5.PROD.HFS

BLOCK UNUSED -(16)--------

VOLUME SERIAL -(17)TOTSMS

MULT VOL (18) NO

DEVICE TYPE -(19)-3390 3390 3390 3390 3390 3390

------- TSMS16 NO ------- TSMS09 NO ------- TSMS18 NO ------- TSMS25 NO ------- TSMS13 NO

Figure 206. Monitoring data set utilization from ISMF - 2

13.2.3.2 ISPF 3.4 screen By displaying data set information from ISPF 3.4, you can see the current utilization of the data set. Figure 207 on page 275 shows an HFS data set that has 44 extents and is 47 percent utilized.

274

Lotus Domino for S/390 R5 Installation, Customization and Administration

Data Set Information Command ===> Data Set Name . . . . : OMVS.SC67.DOMINO5.DOMINO1.DATA.HFS General Data Management class . . : Storage class . . . : Volume serial . . . : Device type . . . . : Data class . . . . . : Organization . . . : Record format . . . : Record length . . . : Block size . . . . : 1st extent cylinders: Secondary cylinders : Data set name type : Current Allocation Allocated cylinders : 830 Allocated extents . : 44

STANDARD STANDARD TOTSMS 3390 DCPDSE PO U 0 0 200 10 HFS

Current Utilization Used pages . . . . : 70967 % Utilized . . . . : 47

Creation date . . . : 1999/06/08 Expiration date . . : ***None***

Referenced date . . : 1999/06/15

Figure 207. Monitoring data set utilization from ISPF 3.4

13.2.3.3 OMVS You can also see the current utilization of HFS data sets by issuing the UNIX command df from OMVS. The df command displays the amount of free space in the file system. The -Pk option lists complete information on space used in Kilobytes. Figure 208 shows the same data set using the df command. Table 25 defines some common terms.

D1ANDRE @ SC67:/domino1/notesdata>df -Pk /domino1/notesdata Filesystem 1024-blocks Used Available Capacity Mounted on OMVS.DOM11.DATA.HFS 597600 283868 313732 48% /domino1/notesdata D1ANDRE @ SC67:/domino1/notesdata>

Figure 208. Monitoring data set utilization from OMVS Table 25. DASD terms

Term
File system 1024-blocks Used Available Capacity Mounted on

Definition
The file system (HFS) name The total space in the file system, in number of 1KB blocks The space used - number of 1 KB blocks The space available - number of 1 KB blocks The percentage of the total space used The file system mount point for this file

13.2.4 Monitoring DASD volume


One of the reasons that HFS data sets may run out of space is because there is no free space on the DASD volume. So you should monitor DASD volume utilization using standard OS/390 tools such as the ISMF volume list. You can

HFS data set management

275

request a list of all volumes in a storage group. The output from this is shown in Figure 209 on page 276.

VOLUME LIST LINE VOLUME FREE % ALLOC FRAG LARGEST FREE OPERATOR SERIAL SPACE FREE SPACE INDEX EXTENT EXTENTS ---(1)---- -(2)-- --(3)-- (4)- --(5)-- -(6)- --(7)-- --(8)-TOTSMS 12561 0 2758939 561 1660 16 TSMS01 216972 12 1630695 309 45652 26 TSMS02 281826 15 1565841 293 63913 25
Figure 209. Monitoring DASD volume utilization from ISMF

By scrolling to the right you can get additional information on the status of each volume in the storage group, as shown in Figure 210.

VOLUME LIST LINE VOLUME RD CACHE OPERATOR SERIAL STATUS ---(1)---- -(2)-- --(16)-TOTSMS ACTIVE TSMS01 ACTIVE TSMS02 ACTIVE DASD FW STATUS --(17)-ACTIVE ACTIVE ACTIVE CACHE FW STATUS --(18)-ACTIVE ACTIVE ACTIVE DUPLEX OTHER SUBSYS STATUS DEVICE ID --(19)-- -(20)- -(21)SIMPLEX ---0028 SIMPLEX ---000A SIMPLEX ---000A

Figure 210. Monitoring DASD volume status from ISMF

13.2.5 Recovering from space problems


The way in which you recover from space problems depends on the type of problem. For a Domino database that has exceeded its maximum size, you can increase the size with the Domino Administrator. If an HFS data set is full, the recovery action depends on the situation: If the data set has reached its maximum number of extents but there is still space on the volume, you can reduce the number of extents by using DFSMSdss dump/restore or DFSMShsm migrate and recall. If there is no free space on the volume, then you can move the HFS data set to another volume with more space. Use DFSMSdss dump/restore to move the data set. Alternatively, you could move other data sets off the volume. If the HFS data set has reached the maximum size of a volume, and it has not been allocated as a multi-volume data set, then it cannot be made any bigger. You will need to split up the files in this HFS data set. If it only contains a single directory, then you will need to split that directory also. This may affect Notes database names, in which case changes will be needed in your Notes environment. Because this situation is potentially disruptive to your Notes environment, you should plan your file and directory structure carefully to minimize the number of times this occurs. With DFSMS 1.5, the size of an HFS data set is no longer limited to the size of a volume. The next section describes how to utilize DFSMS 1.5 for multi-volume HFS data sets.

276

Lotus Domino for S/390 R5 Installation, Customization and Administration

13.3 DFSMS 1.5


DFSMS 1.5 provides space constraint relief to Domino/390. It also has significant performance improvements which will benefit all applications, including Domino/390. The new features of DFSMS 1.5 are: Multivolume HFS support Performance enhancements: Deferred I/O Significantly reduced CPU time confighfs utility and RMF report NOWRITEPROTECT parameter on mount statement The single volume restriction has been removed for HFS data sets. HFS data sets can now span up to 59 volumes, with up to 255 total extents for all volumes, and up to 123 extents per volume. Therefore, the maximum proofed database size of Domino R5 of 64 GB is also supported on OS/390. With DFSMS 1.4 one HFS is restricted by the size of one volume which is about 2.8 GB for a 3390 model 3 or 8.4 GB for a 3390 model 9.
Note: Previous releases of DFSMS/MVS cannot mount HFS data sets that span more than one volume. Toleration PTFs must be installed on lower-level systems that share HFS data with DFSMS/MVS 1.5 systems to ensure the integrity of multivolume HFS data sets. Single volume HFS data sets created on a DFSMS/MVS 1.5 system are still accessible on previous releases.

In conjunction with OS/390 UNIX System Services, DFSMS/MVS 1.5 includes fundamental changes in the way it writes HFS data to disk. Multiple updates are now batched into a single I/O operation, reducing both I/O and path length and greatly decreasing file access contention. HFS now maintains its own buffer pools and also takes advantage of caching for file data, file attributes, and HFS indexes. A process called sync daemon runs periodically and writes all changes to disk that have occurred since the last time it ran. The PARM field of the FILESYSTYPE statement in parmlib member BPXPRMxx for TYPE(HFS) now supports the following new keyword parameter: PARM(SYNCDEFAULT(t) VIRTUAL(max) FIXED(min)). The value for SYNCDEFAULT specifies the number of seconds to be used as a default for the sync daemon interval. The maximum value is 65535. This value can be overridden by using the SYNC(t) parameter on the mount statement as shown in Figure 211 on page 278. VIRTUAL(max) specifies the number of megabytes that is the maximum amount of virtual storage that HFS data and metadata buffers should consume. FIXED(min) specifies the number of megabytes of virtual storage that will be fixed at HFS initialization time and will remain fixed even if HFS activity drops to zero.

HFS data set management

277

.... MOUNT FILESYSTEM(dsname) TYPE(HFS) MOUNTPOINT(pathname) PARM(SYNC(30) NOWRITEPROTECT) ...


Figure 211. Sample mount statement in BPXPRMxx

Improvements have been made to ensure integrity of the file system due to inadvertent mount for read/write access from multiple systems. This ensures that the file system integrity is not compromised when the serialization across the sharing systems is compromised due to instances like improper use of conversion lists, or if all of the sharing systems are not part of the same GRS serialization mechanism (ring or star), etc. Therefore, the default parameter for mount statements in BPXPRMxx is WRITEPROTECT. If you have a GRS complex defined, the NOWRITEPROTECT parameter should be used to avoid additional overhead (see Figure 211). The shell command confighfs (see Chapter 13.3.2, Using the utility confighfs on page 280) is provided to perform the following tasks: extend HFS, display statistics, and display/change buffer limits. DFSMS 1.5 was delivered with OS/390 2.7, but works also with OS/390 releases 2.5 and 2.6. The redbook HFS Usage Guide, SG24-5482 contains a much more detailed description of the HFS-related functions of DFSMS 1.5.
Note: DFSMS is a key component of the OS/390 operating environment. Many components of the product have been improved. If you want to upgrade to DFSMS 1.5 make sure that you check the PSP upgrade MVSDFSMS150 and order the latest maintenance.

13.3.1 Allocating a multivolume HFS


An HFS has to be allocated explicitly as a multi-volume data set in order to span multiple volumes. Using the UNIX shell command confighfs it is also possible to extend an HFS within one volume. Figure 212 on page 279 shows sample JCL to allocate a multivolume HFS. Allocating a multi-volume HFS is usually done either by coding a volume count subparameter in the JCL that creates it (that is, VOL=(,,,n)) or by dataclass. If the volume count is not sufficient, more volumes can be added by using IDCAMS ALTER ADDVOLS. To use the additional volume, the filesystem must be remounted.

278

Lotus Domino for S/390 R5 Installation, Customization and Administration

//D1ANDRE JOB ,D1ANDRE,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A //DOMALL EXEC PGM=IEFBR14 //MAILHFS DD DSN=OMVS.SC63.DOMR5.MAIL.HFS, // DISP=(NEW,CATLG,DELETE), // DCB=(DSORG=PO), // SPACE=(CYL,(100,50,1)), // STORCLAS=OMVSSC, // VOL=(,,,2,SER=(SBOX17,SBOX16)), // DSNTYPE=HFS
Figure 212. Sample JCL to allocate a multivolume HFS

A multivolume HFS can be identified by a + sign in the column Volume of the ISPF data set list (see Figure 213) or the ISPF data set information output shown in Figure 214.
DSLIST - Data Sets Matching OMVS Command ===> Row 7 of 58 Scroll ===> CSR

Command - Enter "/" to select action Volume ------------------------------------------------------------------------------OMVS.SC63.DOMR5.MAIL.HFS SBOX17+ OMVS.SC63.ETC SBOX06
Figure 213. ISPF data set list for multivolume HFS

Data Set Information Command ===> Data Set Name . . . . : General Data Management class . . : Storage class . . . : Volume serial . . . : Device type . . . . : Data class . . . . . : Organization . . . : Record format . . . : Record length . . . : Block size . . . . : 1st extent cylinders: Secondary cylinders : Data set name type :

OMVS.SC63.DOMR5.MAIL.HFS Current Allocation MCDB22 Allocated cylinders OPENMVS Allocated extents . SBOX17 + 3390 Current Utilization PO Used pages . . . . U % Utilized . . . . 0 0 500 1 HFS

: 745 : 246

: 106986 : 79

Figure 214. ISPF data set information for multivolume HFS

Using the ISMF data set list, the multi volume flag for the HFS data set will be set to yes as shown in Figure 215.
LINE OPTIMAL BLOCK VOLUME MULT OPERATOR DATA SET NAME SIZE UNUSED SERIAL VOL ---(1)---- ------------(2)------------ -(15)-- -(16)-- -(17)- (18) OMVS.SC63.DOMR5.MAIL.HFS 0 ------- SBOX17 YES

Figure 215. Output of ISMF data set list

HFS data set management

279

When the primary allocation of the first volume is consumed the HFS data set is extended to the next volume. Figure 216 shows the ISMF data set list for an HFS after the extension to the next volume.
LINE OPERATOR DATA SET NAME ---(1)---- ------------(2)-----------OMVS.SC63.DOMR5.MAIL.HFS OMVS.SC63.DOMR5.MAIL.HFS ---------- ------ ----------- BOTTOM OPTIMAL SIZE -(15)-0 0 OF DATA BLOCK VOLUME MULT UNUSED SERIAL VOL -(16)-- -(17)- (18) ------- SBOX17 YES ------- SBOX16 YES ----------- ------ ----

Figure 216. Output of ISMF data set list after extension to next volume

If a secondary extent amount was specified at HFS data set creation time, that is, the amount that will be used for data set extends that occur as a result of normal file system operation, the system will attempt to obtain the secondary amount on the last currently allocated volume. If that fails, either due to no space on the last volume or the 123 extent limit for the last volume has already been reached, and there are candidate volumes for the HFS data set, the system will attempt to obtain the secondary amount on a new volume. If no secondary amount was specified at HFS data set creation time, and candidate volumes exist for the HFS data set, then the system will extend the data set to a new volume if more extents are needed as a result of a normal file system operation. The system will attempt to obtain an amount of space that is equal to the amount of space that was allocated on the first volume of the data set when it was mounted. Normally, the extend amount will equal the original primary space allocation, unless dynamic extends via the confighfs utility have occurred, which resulted in additional disk space being allocated to the first volume of the HFS data set.

13.3.2 Using the utility confighfs


DFSMS 1.5 provides the shell command confighfs to manage multi-volume HFS: /usr/lpp/dfsms/bin/confighfs. confighfs gives interactive shell users the ability to invoke vfs_pfsctl HFS functions. The vfs_pfsctl function is used to pass control information to the Physical File System (PFS). confighfs can also be used to extend an HFS with no secondary allocation quantity, or to extend and override the secondary allocation quantity. Table 26 shows the available command line options for confighfs.
Table 26. Options of confighfs

Option -l -v n -f n

Description

Query HFS limits Set virtual storage max to n (where n is in MB). Requires superuser authority. Set fixed storage min to n (where n is in MB). Requires superuser authority

280

Lotus Domino for S/390 R5 Installation, Customization and Administration

Option -x size pathname

Description

Extend the specified file system, where size is the amount to be extended suffixed by the extend unit of M, T, or C (for megabytes, tracks, or cylinders), and the pathname is a full or simple pathname to a file or directory in the file system to extend. Requires superuser authority.

pathname -xn size pathname

Query file system statistics for the file system containing each of the path names specified. Extend the specified file system to a new volume with the same rules as above. Requires superuser authority.

Figure 217 and Figure 218 show examples how to use confighfs for a 47 MB HFS.

D1ANDRE @ SC67:/u/d1andre>confighfs /notesdata Statistics for file system CCW.PROD.NOTES.DATA ( 05/25/99 3:21pm ) File system size:__12096000 _____47250(MB) Used pages: ___5651125 _22074.707(MB) Attribute pages: _______178 ___0.69531(MB) Cached pages: _________0 _________0(MB) Seq I/O reqs: _______________89030 Random I/O reqs: ______________232221 Lookup hit: ______________117726 Lookup miss: ___________________0 1st page hit: ______________114322 1st page miss: ________________2776 Index new tops: ___________________4 Index splits: _________________169 Index joins: ___________________4 Index read hit: ______________123106 Index read miss: ___________________1 Index write hit: ______________105110 Index write miss:___________________0 RFS flags __________________82(HEX) RFS error flags: ___________________0(HEX) High foramt RFN: ______________563AF7(HEX) Member count: __________1446704896 Sync interval: __________________60(seconds)
Figure 217. Using the utility confighfs - part 1

SIMON:/u/simon: 131>confighfs -l HFS Limits Maximum virtual storage: _______740(MB) Minimum fixed storage: _________0(MB)
Figure 218. Using the utility confighfs - part 2

HFS data set management

281

282

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 14. Data backup


When running Lotus Domino, like any other application on OS/390, it is critical to have a well-defined backup strategy in place to ensure fast and effective data recovery. Performing regular backups of your Notes data is critical. Back up your Domino Servers often to ensure against data loss. The data for the Domino Server on S/390 can be backed up in a number of different ways using the following: Notes facilities to replicate databases to another HFS data set or another server ADSTAR Distributed Storage Manager (ADSM), now known as Tivoli Storage Manager, to back up the UNIX files Hierarchical Storage Manager (DFSMShsm) to back up HFS data sets Data Facility Data Set Services (DFSMSdss) to back up HFS data sets or whole DASD volumes RVA based backup options (SnapShot) Tivoli Data Protection for Lotus Domino In this chapter we discuss these different options and give examples.

14.1 Understanding your backup and recovery needs


In general, the characteristics of the data (criticality, rate of change, etc.) will determine the recovery needs, which in turn will impose the backup requirements. The following examples describe some possible scenarios in a Lotus Domino on S/390 environment:
Discardable data: The customer may find the risk/consequences of losing a particular type of data acceptable. For example, there is the customer in the retail business who has rolled out mail to all of the store clerks, but does not consider the mail data worth the cost of backup. In this customer's case, it is perfectly acceptable not to take backups. The recovery process for an individual corrupted database might simply be to delete and recreate the database.

However, this is not a workable plan in a disaster recovery situation where many/all databases must be rebuilt. To avoid recreating a large number of databases, it might be simpler to take low-frequency volume dumps, using a tool such as DFSMSdss. A simple DFSMSdss volume restore could quickly reload all the mailboxes with some previous version of the mail data.
Static data: The Lotus Domino binary directory (/usr/lpp/lotus) is an example of data which is very static. At first glance, it might seem that a post-installation one-time backup would suffice for later recovery. However, the problem is that the content of the directory is not totally static; for example, some updates take place when a new server partition is added. Since these updates are not well documented, it is advisable to base the recovery strategy upon full periodic backups. Since this data is contained in a single HFS, DFSMSdss data set dump might be the option of choice.

Copyright IBM Corp. 1999

283

Noncritical data: The key here is to understand what is meant by noncritical. Data is noncritical when business needs make it acceptable to recover the data to a given point in time in the not too distant past. This requirement could be accomplished through periodic backups and then a restore of the last backup when needed. Any updates that may have taken place after the backup would be lost, but this is acceptable by definition. Again, in certain instances, mail data might fall into this category. Critical data: This category involves databases where the business need dictates that the data must be recovered to its state immediately preceding the failure. The only way to accomplish this type of recovery is with periodic backups combined with some journal-based forward recovery system. The new transaction log in Lotus Domino R5 will allow for solutions in this arena (see 14.8, Tivoli Data Protection for Lotus Domino on page 306).

A second consideration is the scope of the recovery. In the world of Lotus Domino data, there are three very distinct recovery situations:
Full recovery : Common disaster recovery situations, like failure of a disk subsystem. All databases contained in the subsystem must be restored to an accessible state. Database level recovery : A single database may have been corrupted. Recovery involves restoring the last backup of the database. Document level recovery: One or more documents in a database have been lost, either deleted or corrupted. Normal recovery in this situation involves restoring the backup of the database to a temporary location and from it, copying the required documents to the active version of the database.

A third and last consideration is the ability to take backups without interrupting the service provided by the Lotus Domino Server. In the case of 24 x 7 availability requirements, all backup operations must run concurrently with the server.

14.2 Backup using Notes replication


Notes provides standard facilities to replicate databases. The replicas can exist on the same server with a different file name or on a different server. This provides a very easy way to make backup copies of databases. However, it does not meet all of your backup requirements: It is possible that an error is propagated to the replicas before you spot it. In that case the replicas also have the error, and you would not have a valid copy from which to recover. The replicas take up additional disk space. If the replicas are on the same server, you will need to copy those backups to tape to take them off site. If the replicas are on another server, you must transfer the data across a network connection, which is slow and may require additional network capacity. Therefore, while replication can be useful, you should not rely on it as your only backup method.

284

Lotus Domino for S/390 R5 Installation, Customization and Administration

14.3 Backup using UNIX commands


A UNIX command called tar can be used for making backups. This tool is similar to the PC tool PKZIP that can be used to make backup copies of sets of files. To get information on this command, see the appropriate manual or type the command man tar. Make sure that you back up all of the Domino Server files, including the server code in /usr/lpp/lotus and subdirectories, and the files in /notesdata. To restore a whole file system, you would first ensure that you have an empty and error-free file system. Then use the tar command with the -x (extract) option to restore all of the files. To restore a single database, use the same command but restore the files to a different directory. Then copy the backup file that you want over the damaged file. To restore a single database and preserve new documents added since the last backup, restore the backup to a different directory and then move it to the database directory using a new file name. Copy the new documents from the damaged database to the backup copy. Delete the damaged database and rename the backup to the original name. To restore a single damaged or deleted document, you restore the backup of the whole database with a new file name. Then copy the document from the backup to the live database. You can then delete the backup database.

14.4 Backup using Tivoli ADSM


The IBM ADSTAR Distributed Storage Manager (ADSM), now known as Tivoli Storage Manager (TSM), is a tool that allows the backup of data sets from many client platforms to many server platforms. It provides functions similar to DFSMShsm on OS/390 but across a network. The TSM server and UNIX backup-archive client are both available on OS/390. The TSM server executes as a native MVS application; the UNIX backup-archive client executes under OS/390 UNIX services. TCP/IP is required as the communication protocol between the ADSM server and UNIX client even when the client and server execute on the same machine. TSM backs up data at the UNIX file level. Each Notes database is a UNIX file. TSM has an incremental backup capability so that only changed files are backed up. However, if one document in a Notes database is changed then the whole database will be backed up. ADSM (TSM) can back up files while they are open, so there is no need to close the Domino Server down before taking the backups. However, this may result in a fuzzy backup: the backup version of a file may not accurately reflect what is currently in the file because Tivoli Storage Manager backed up the file while it was being modified. To help avoid this problem, TSM will detect if a file was updated during the time it was being backed up, and if so it will retry the backup four times.

Data backup

285

There are four options for backing up files: Static - If being modified, TSM will not back up the file or directory. Shared Static - If being modified, TSM will not back up the file or directory, but will retry the backup a predetermined number of times. Shared Dynamic - If being modified, TSM will not initially back up the file or directory. It will retry the operation a predetermined number of times; it will back up the file on its last attempt, even if the file is being modified. Dynamic - TSM will always back up the file or directory, regardless of whether or not it is being modified. This section discusses how to use the ADSM (TSM) client in the OS/390 UNIX environment. If your OS/390 was installed using ServerPac, the TSM OS/390 UNIX client code is in the /usr/adsm directory. For more information on command usage, see ADSM V3R1 Using the UNIX Backup-Archive Clients , SH26-4075. For more information on installing the TSM UNIX System Services client, see Program Directory for ADSTAR Distributed Storage Manager Client for OS/390 UNIX System Services, GI10-4520. The steps you should go through are as follows: 1. Activate the TSM OS/390 UNIX client. 2. Get the TSM server administrator to register your client system and define the required management class, client node name, client node password, space pools size, copy group, and other parameters. 3. Use incremental or selective backup commands to back up a directory or a single file. 4. Try to restore the files using the restore command.

14.4.1 Activate the ADSM (TSM) OS/390 UNIX client


Once the TSM OS/390 UNIX client code has been installed, do the following: 1. Make updates to the OS/390 UNIX parameters in SYS1.PARMLIB(BPXPRMxx). 2. Set UNIX file permission bits and symbolic links. 3. Set the TSM client options. 4. Start the TSM client.
14.4.1.1 Make updates to OS/390 UNIX parameters Check whether the domain AF_INET is already defined in SYS1.PARMLIB(BPXPRMxx). If you already use Domino Server for OS/390, this action should already be complete. Figure 219 on page 287 shows the definition on our system:

286

Lotus Domino for S/390 R5 Installation, Customization and Administration

FILESYSTYPE TYPE(INET) ENTRYPOINT(EZBPFINI) NETWORK DOMAINNAME(AF_INET) DOMAINNUMBER(2) MAXSOCKETS(64) TYPE(INET) INADDRANYPORT(10000) INADDRANYCOUNT(1000)
Figure 219. Example AF_INET definition in SYS1.PARMLIB(BPXPRMxx)

14.4.1.2 Set UNIX file permission bits and symbolic links You need to set UNIX file permission bits and symbolic links. Two batch jobs should be provided in your SAMPLIB. They are: ANSOJOB2 ANSAJOB2

Invokes the UNIX shell script dsmapi.install in directory /usr/adsm Invokes the UNIX shell script dsmapi.install in directory /usr/adsm/api

You can submit these batch jobs or you can invoke the shell scripts in the OMVS environment as shown in Figure 220. You must have superuser (UID=0) authority to run these scripts.

# cd /usr/adsm # dsm.install Setting file permissions Creating symbolic links # cd api # dsmapi.install Setting file permissions Creating symbolic links
Figure 220. Set UNIX file permission bits and symbolic links

14.4.1.3 Set the TSM client options The files dsm.sys.smp and dsm.opt.smp in the directory /usr/adsm/ are sample client option files. Copy these files to dsm.sys (system options) and dsm.opt (user options) respectively and tailor the option files to your special installation needs. For more information, see ADSM V3R1 Using the UNIX Backup-Archive Clients, SH26-4075.

Figure 221 shows our settings in the dsm.sys file.

SErvername wtscmxa COMMmethod TCPPort TCPServeraddress

TCPip 1500 wtscmxa.itso.ibm.com

Figure 221. Option file dsm.sys

The TSM server that we connect to has the name wtscmxa and the IP name wtscmxa.itso.ibm.com. This is a TSM server running on another OS/390 system. Communication to the server is through a Token-Ring Open System Adapter using the TCP/IP protocol.
Data backup

287

If your TSM client and server run on the same OS/390 system, you will get better data transfer performance because the data does not need to be transmitted across a network.
14.4.1.4 Start the TSM Client To start the TSM client type dsmc in the OS/390 UNIX environment. You will see the TSM client start messages and go into the client shell environment as shown in Figure 222.

# cd / # dsmc ADSTAR Distributed Storage Manager Command Line Backup Client Interface - Version 2, Release 1, Level 0.1 (C) Copyright IBM Corporation, 1990, 1995, All Rights Reserved. dsmc>
Figure 222. Start the TSM client

14.4.2 Get the TSM server administrator to register your client


You have to register your TSM client with the TSM server that you will be using. Ask the TSM server administrator to register your client system. The administrator will define the node name, space pools sizes, client node password, management class, and other parameters. Ask the administrator to set the Copy Serialization value in Copy Group (group name is always called STANDARD) to Shared Dynamic. This will cause files to be backed up even if they are changed while the backup is taking place. If the file is changed during the backup, TSM tries as many as four additional times, depending on the value specified for the CHANGINGRETRIES option in the client system options file, to back up the file. The file is backed up on the last try even if it has changed. For more information on copy serialization, see Chapter 5, "Automating ADSM Tasks" in ADSM V3R1 Using the UNIX Backup-Archive Clients, SH26-4075.

14.4.3 Back up files


You may now wish to back up some files using TSM. Some of the TSM client commands you will use are:
Incremental

Takes an incremental backup of files. It backs up files that have changed since the last backup. You can target individual files, or a directory with its files and subdirectories.
Note: The file or directory must be contained in one mount point. For example, if you use the incremental command to back up the /notesdata directory, all files and subdirectories will be backed up except the /notesdata/mail subdirectory because /notesdata/mail is another mount point since we defined it in a different HFS data set.

Selective Restore

Takes a selective incremental backup of one file, which you specify. Restores files or directories from a backup copy. It can restore them to the original directory or another directory.

288

Lotus Domino for S/390 R5 Installation, Customization and Administration

Query Backup

Queries files and directories to check if they were backed up, and the backup time.

Query Filespace A filespace is the pool where your backup files reside. You will see each mount point as a filespace name. Help Archive

Shows each command's syntax and usage notes. Allows you to store files for a longer time than backup. It has archive version control. The TSM server administrator must define an archive pool for your client. Retrieves archived files.

Retrieve

Figure 223 shows the incremental command and its result. The parameter -Q means quiet. If you do not use it, you will see a list of all files backed up.

# cd /usr/adsm # dsmc dsmc> inc /notesdata -Q Please enter password for node "WTSC52": <== Go to ADSM shell <== Issue incremental command <== Type password

Total number of objects inspected: 468 Total number of objects backed up: 466 Total number of objects updated: 0 Total number of objects rebound: 0 Total number of objects deleted: 0 Total number of objects failed: 0 Total number of bytes transferred: 100.6MB Data transfer time: 69.55 sec Data transfer rate: 1,482.27KB/sec Average file size: 221.2KB Elapsed processing time: 0:03:51
Figure 223. incremental backup example 1

You can use the query filespace command to check whether the filespace was created, as shown in Figure 224.

dsmc> query filespace Num --1 Last Incr Date -------------07/25/1997 11:43:13 Type ---TFS File Space Name --------------/notesdata

Figure 224. query filespace example 1

You can use the query backup command to check which files you backed up, as shown in Figure 225 on page 290.

Data backup

289

dsmc> query backup -sub=yes /notesdata Session established with server ADSM: MVS Server Version 2, Release 1, Level 0.3 Server date/time: 07/29/1997 20:58:36 Last access: 07/29/1997 20:56:4 Size ---0 2 1,114,112 196,096 80,384 Backup Date ----------07/25/1997 11:39:36 07/25/1997 11:39:36 07/28/1997 14:36:56 07/25/1997 11:39:36 07/25/1997 11:39:36 ... DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT A A A A A A A A A A A A /notesdata/domino/ico /notesdata/domino/ico /notesdata/domino/ico /notesdata/domino/ico /notesdata/noteslog/d /notesdata/noteslog/d /notesdata/noteslog/d /notesdata/noteslog/d /notesdata/noteslog/d /notesdata/noteslog/d /notesdata/noteslog/n /notesdata/noteslog/n Mgmt Class ---------DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT A/I --A A A A A File ---/notesdata/.notes4501 /notesdata/.sgf.notes /notesdata/admin4.nsf /notesdata/admin4.ntf /notesdata/alog4.ntf

... lines removed 188 205 194 825 479 3,731 87 613 535 740 258 6,742 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997 07/25/1997

11:43:12 11:43:12 11:43:12 11:43:13 11:43:13 11:43:13 11:43:13 11:43:13 11:43:13 11:43:13 19:29:32 11:43:13

Figure 225. query backup example

Note that: The incremental command backed up all files and subdirectories. The subdirectory called /notesdata/mail is not backed up. The parameter -sub=yes shows all subdirectories. After we backed up the /usr/lpp/lotus and /notesdata/mail directories, we saw the file spaces shown in Figure 226.

dsmc> query filespace Num --1 2 3 Last Incr Date -------------07/25/1997 13:47:21 07/25/1997 14:02:51 07/25/1997 13:56:52 Type ---TFS TFS TFS File Space Name --------------/notesdata /notesdata/mail /usr/lpp/lotus

Figure 226. query filespace example 2

Now let us back up /notesdata again as in Figure 227 on page 291.

290

Lotus Domino for S/390 R5 Installation, Customization and Administration

dsmc> incre /notesdata Incremental backup of file system: '/notesdata' Directory--> 0 /notesdata/bil2.ft Sent Normal File--> 1,114,112 /notesdata/admin4.nsf ............... Sent Normal File--> 240,064 /notesdata/billing.nbf ........ Sent Normal File--> 622,592 /notesdata/billing.nsf ................... Normal File--> 128,000 /notesdata/billing.ntf .... Sent Normal File--> 262,144 /notesdata/bil2.nsf ......... Sent Normal File--> 589,824 /notesdata/cldbdir.nsf ................... Normal File--> 671,744 /notesdata/collect4.nsf .......Sent....... Normal File--> 499,712 /notesdata/doclibl4.ntf .......Sent..... Normal File--> 2,277,376 /notesdata/domguide.nsf .................. ... some lines removed ... Normal File--> 258 /notesdata/noteslog/notes.input . Sent Successful incremental backup of '/notesdata'

Total number of objects inspected: 493 Total number of objects backed up: 54 Total number of objects updated: 0 Total number of objects rebound: 0 Total number of objects deleted: 0 Total number of objects failed: 0 Total number of bytes transferred: 84.5MB Data transfer time: 61.53 sec Data transfer rate: 1,407.13KB/sec Average file size: 1,603.1KB Elapsed processing time: 0:03:16
Figure 227. incremental backup example 2

Note that: We did not use the -Q parameter, so we get a list of the files sent. The total number of objects backed up is 54. This is far less than the total number of objects inspected (493 files). Incremental backup just backs up the files that have changed since the previous backup. Now let us try a selective backup. See Figure 228 on page 292.

Data backup

291

dsmc> sele /notesdata/julin.nsf Selective Backup function invoked. Server Version 2, Release 1, Level 0.3 Server date/time: 07/28/1997 14:45:56

Last access: 07/28/1997 14:45:1

Normal File--> 35,795,968 /notesdata/julin.nsf ..................... ........................................................................ ........................................................................ ........................ Changed Retry # 1 Normal File--> 35,795,968 /notesdata/julin.nsf ..... ........................................................................ ........................................................................ ............................................... Changed Retry # 2 Normal File--> 35,795,968 /notesdata/julin.nsf .......... ........................................................................ ........................................................................ ........................................................................ ................................... Sent Selective Backup processing of '/notesdata/julin.nsf' finished with 0 fai

Total number of objects inspected: 1 Total number of objects backed up: 1 Total number of objects updated: 0 Total number of objects rebound: 0 Total number of objects deleted: 0 Total number of objects failed: 0 Total number of bytes transferred: 102.4MB Data transfer time: 106.90 sec Data transfer rate: 981.11KB/sec Elapsed processing time: 0:03:58
Figure 228. selective backup example 1

Note that the TSM client attempted to back up the file /notesdata/julian.nsf three times. The first two attempts failed because this file was being changed while the backup was taking place. On the third attempt it was backed up. Let us try selective backup on the file julin.nsf again, but this time keep the file open by continuing to open this Notes database from a Notes client workstation. The backup fails after automatically trying four times. This is because the Copy Serialization parameter was set to Shared Static. See Figure 229 on page 293.

292

Lotus Domino for S/390 R5 Installation, Customization and Administration

dsmc> sele /notesdata/julin.nsf Selective Backup function invoked. Normal File--> 35,795,968 /notesdata/julin.nsf ..................... ........................................................................ ........................................................................ ........................................................................ ........................ Changed Retry # 1 Normal File--> 35,795,968 /notesdata/julin.nsf ..... ........................................................................ ........................................................................ ........................................................................ ........................................................................ . . . ........................................................................ ........................................................................ ........................................................................ ........................ Changed Retry # 4 Normal File--> 35,795,968 /notesdata/julin.nsf ..... ........................................................................ ........................................................................ ................................... Changed ANS4228E Send of object '/notesdata/julin.nsf' failed ANS4940E File '/notesdata/julin.nsf' changed during backup. File skipped ANS4677E Selective Backup processing of '/notesdata/julin.nsf' finished w lures.

Total number of objects inspected: 1 Total number of objects backed up: 0 Total number of objects updated: 0 Total number of objects rebound: 0 Total number of objects deleted: 0 Total number of objects failed: 1 Total number of bytes transferred: 170.7MB Data transfer time: 160.76 sec Data transfer rate: 1,087.30KB/sec Elapsed processing time: 0:06:33
Figure 229. selective backup example 2

14.4.4 Restore files


TSM can restore files or directories which have been backed up. The following types of restore scenarios are supported: Restore the current version or a specific backup version of the files Restore files to a directory other than the original directory Restore files to a point-in-time, based upon date and time Replace/not replace the files if they still exist on the client Now we restore the file names.nsf as shown in Figure 230 on page 294.

Data backup

293

dsmc> restore /notesdata/names.nsf Restore function invoked. File /notesdata/names.nsf exists, do you want to replace it? (Yes/No) y Restoring 1,736,704 /notesdata/names.nsf ............................. ................. Done Restore processing finished. dsmc>
Figure 230. restore example

To restore a directory, type the directory's name, such as sele /notesdata -sub=yes. Remember to add the -sub=yes parameter if you want to restore related subdirectories.
Note: If the restore command replaces a database that is open, it will cause database damage.

14.4.5 TSM disaster recovery


The Disaster Recovery Manager (DRM) is an optional feature. It provides the ability to create a disaster recovery plan which is automated and auditable. Additionally, DRM offers off-site recovery media management and storage of client recovery information (machine location and hardware and software characteristics) in one place, namely the TSM (tracking) database. Disaster recovery may be implemented as follows: 1. Back up the client data to the TSM server. 2. Save the client recovery information in the TSM database. 3. Back up the storage pools and store the media off-site (virtual volumes may be used to accomplish the same thing). 4. Back up the server database to removable media and store it off-site. 5. Generate the disaster recovery plan from TSM system and administrator input. With suitable replacement hardware and software, the TSM server and OS/390 UNIX backup-archive client can be rebuilt on another system using the recovery plan.

14.4.6 TSM performance considerations


Large files should always be backed up directly to tape rather than to disk, and then later staged to tape. Characteristically, most Domino files are considered large (greater than 10 MB). TSM expects to have exclusive use of tape drives; if another application tries to use a drive used by TSM, some of the TSM functions may fail. Although a virtual tape server (VTS) is a supported device, there may be delays on the write during the backup process related to how busy the VTS is, and delays on the restore related to destaging the full virtual tape volume. Compression should be enabled on the tape drive rather than in the backup-archive client to save on memory and CPU cycles.

294

Lotus Domino for S/390 R5 Installation, Customization and Administration

Scalability is achieved through parallel client sessions with the TSM server, which can be implemented by invoking multiple client schedulers (TSM background clients running against a schedule). To avoid contention, client sessions should not access the same device or directory. The commands to initiate multiple sessions can be part of a script file that can be executed or scheduled for execution when backups are required. Sessions to back up directly to tape require one tape drive per session. OS/390 TCP/IP and the UNIX backup-archive client must be appropriately configured to maximize performance. In the TCP/IP profile, the recommended setting for the TCPSENDBFRSIZE and the TCPRCVBUFRSIZE parameters is 256 KB. The TCPWINDOWSIZE in the options file for the client should be set to 64 KB when running with OS/390 2.6 (and DFSMS 1.4), and 256 KB when running with OS/390 2.7 (and DFSMS 1.5). The TSM server and client should be configured to increase communication and device I/O buffers by specifying YES for the options USELARGEbuffer (server) and LARGECOMmbuffers (client). As indicated earlier, compression should always be set to NO for the client.

14.4.7 TSM considerations when backing up Domino


When performing online backups, consider the activity against the databases being backed up before choosing the options for copying open files. For example, Shared Static, which means that backup can only be done as long as the database does not change during the backup, will be unsuccessful against mail databases during peak periods of activity. For the same databases during peak hours, the Dynamic or Shared Dynamic options will allow backups, but at the expense of not having totally up-to-date copies of the files. Consider replicating the database to be backed up, and then backing up the replica using TSM. Consider periodic offline backups of Domino databases. In general, encourage users to keep files small and to archive data. Smaller databases improve the performance of backup and restore. Notes archive files can be backed up separately from mail files.

14.5 Backup using DFSMShsm


DFSMS Hierarchical Storage Manager (DFSMShsm) is an OS/390 product that backs up OS/390 data sets, including HFS data sets. It can take incremental backups. DFSMShsm works at the HFS data set level so the whole HFS data set will be backed up if any of the files within it have changed. Ideally, when a data set is created in the SMS environment, a data management class is assigned to it. The data management class determines the kind of handling the data set will be subject to for the duration of its life. This includes backup frequency, backup retention, number of versions to be kept, etc. DFSMShsm is the agent responsible for executing the actions dictated by the data management class, like taking backups and deleting old backups when obsolete.

Data backup

295

Since DFSMShsm uses DFSMSdss as the data mover, its use has issues similar to the use of DFSMSdss. In addition, there is the consideration of the timing of the backup in relation to the status of the Domino Server. This is particularly critical if the backup is to be taken with the server down.

14.6 Backup using DFSMSdss


DFSMS Data Set Services (DFSMSdss) is another standard OS/390 product that can backup OS/390 data sets, including HFS data sets. DFSMSdss works at the data set or DASD volume level. DFSMSdss is a very fast way to back up a lot of data, and is therefore useful for DASD volume, HFS data set and disaster recovery backups. The DFSMSdss DUMP command can back up HFS data sets in mounted or unmounted state (COPY is not supported for HFS). DFSMS will quiesce activity against the specified HFS data set and then invoke backup processing. When the backup is complete, the file system is unquiesced and user activity is resumed. The file system quiesce process for mounted HFS data sets opens the door for backups to be taken while the Domino Server owner of the data is active. In that scenario, the file system could be quiesced just between writes in the middle of a database update by the Domino Server. The resulting backup would have a database with incomplete data. What would happen if the need to restore arose and the Domino Server was started with the restored database? The startup database consistency check scan would detect the partial update and a subsequent FIX would remove it. This is acceptable if the partial update was the only update performed by the application's logical unit of work. In addition, it is obvious that all other successful updates from the time of the backup would also be lost. There is another scenario, where the quiescing and backup may happen at a clean point, meaning that there are no documents being updated; but if the application's logical unit of work consists of updates to two or more documents, the server may be caught in between updates during the backup. Domino has no externalized concept of logical unit of work, nor the corresponding controls for it like syncpoint, bucket, etc. Under these conditions, the backup would contain logically incomplete data, although not inconsistent from a database structure point of view. This is a serious issue that must be considered. In addition to the previous considerations, the time involved in dumping large HFS files can translate into unacceptable system quiesced times. If you use DFSMSdss without concurrent copy, you must decide whether you should close the HFS data sets first. If you close the data sets you must stop the Domino Server and unmount the related HFS data sets before dumping them. If you want to run DFSMSdss while the Domino Server is running, you must use concurrent copy.

14.6.1 DFSMSdss Concurrent Copy


A possible solution to shorten the quiesce time is the use of DFSMSdss Concurrent Copy (CC).

296

Lotus Domino for S/390 R5 Installation, Customization and Administration

Concurrent Copy (CC) is a 3990 extended function that enables data center operations to take a copy or dump of data while applications are updating that data. Concurrent Copy delivers a copy of the data in a consistent form, as it existed when the process was initiated, before any updates that may occur while the rest of the process takes place. The Concurrent Copy is implemented through a mix of 3990 Licensed Internal Code and DFSMS code. For DFSMSdss, Concurrent Copy is requested by adding the CC keyword to the DUMP or COPY command input. When a CC operation is started, there is a brief initialization phase, during which there is serialized access to the data being dumped. In a matter of seconds, once the CC environment is initialized, the copy operation is logically complete and the data becomes available for application updates. The actual physical copy starts after initialization, moving data from source to output device at normal speeds. The copy is physically completed later on when all the data has actually been moved to the output device. Without getting overly detailed, the mechanism used by Concurrent Copy to provide a frozen data image as of initialization time is as follows. First, at initialization, a table is built identifying the device tracks involved in the backup operation. After that, two I/O filters are set in place for the duration of the physical copy. All writes to the affected tracks are intercepted, inserting a track read to capture the before image, saving it in a side-file kept in storage in a data space. Once this is done, the requested write is performed. The second filter handles all the reads issued by the backup process, determining whether the data should be taken from the side-file track images or from the real device. From a Domino perspective, there are two ways to look at the use of Concurrent Copy:
DFSMSdss dump/cc while the server is up.

The file system will be quiesced for a brief period of time and then released for normal server operation. Although there is a clear advantage over non-CC dumps, the issues related to possible database inconsistency and application data integrity remain a serious concern.
DFSMSdss dump/cc with the Domino Server down .

The advantage is that the server can be kept down for little more than the initialization time, and then restarted while the physical dump takes place. For this to work, it is important to force a single common initialization phase for all the data related to the server by INCLUDEing all of the server's HFS data sets in a single DDSs DUMP command. This option may be very appealing for installations where just full backups of Domino databases are considered acceptable. (An example could be the mail databases, assuming that in a recovery situation the loss of mail since the last backup is acceptable.)

14.6.2 Using DFSMSdss Concurrent Copy


Concurrent Copy allows a data set to be backed up without closing it. The JCL in Figure 231 on page 298 can be used to dump an HFS data set using Concurrent Copy. You do not need to shut down the Domino Server and unmount the HFS data set. For more information, see DFSMS/MVS V1R3 DFSMSdss Storage Administration Reference, SC26-4929.

Data backup

297

//MACFAD6A JOB MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A /*JOBPARM SYSAFF=SC54 //* //************************************* //* BACKUP NOTES FILES ON SC54 //************************************** //* //*********************************************** //* LOGICAL CONCURRENT DUMP FUNCTION OF DFSMSdss //*********************************************** //SU EXEC PGM=ADRDSSU,REGION=6M //SYSPRINT DD SYSOUT=* //OUTDD1 DD DSN=MACFAD6.NOTES.SC54.DUMPCC.D970729, // SPACE=(CYL,(500,50),RLSE), // UNIT=SYSALLDA,VOL=SER=TOTTS5, // DISP=(NEW,CATLG,DELETE) //SYSIN DD * DUMP DATASET( INCLUDE( OMVS.NOTES.LOTUS.V5000.DATA.HFS )) OUTDDNAME( OUTDD1 ) CANCELERROR COMPRESS OPTIMIZE(1) WAIT(2,2) CC NOTIFYCC /*
Figure 231. DFSMSdss DUMP using Concurrent Copy

14.6.3 Back up an HFS data set


The JCL in Figure 232 on page 299 can be used to back up or dump an HFS data set. There are three steps: 1. Unmount the data set. If you do not unmount the data set before you back it up, DFSMSdss will tell you that the data set is in use and the backup will fail. 2. Back up the data set. 3. Mount the data set again. This job does a back p of the data to disk (UNIT=SYSALLDA). You could back up the data setup to tape with a different UNIT= parameter.

298

Lotus Domino for S/390 R5 Installation, Customization and Administration

//LOTUS01A JOB (999,POK),LOTUS01,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A /*JOBPARM SYSAFF=SC54 //************************************* //* UNMOUNT THE HFS DATA SET //************************************* //IKJEFT01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * UNMOUNT FILESYSTEM('OMVS.NOTES.LOTUS.V5000.TEST2.HFS') /* //************************************* //* LOGICAL DUMP USING DFSMSDSS. //************************************* //DUMP EXEC PGM=ADRDSSU,REGION=6M //SYSPRINT DD SYSOUT=* //HFSVOL DD UNIT=SYSALLDA,DISP=SHR,VOL=SER=TSMS02 //HFSOUT DD DSN=OMVS.NOTES.LOTUS.V5000.TEST2.HFS.DMP1, // SPACE=(CYL,(1,1),RLSE), // UNIT=SYSALLDA,STORCLAS=SCCOMP, // DISP=(NEW,CATLG,DELETE) //SYSIN DD * DUMP DATASET(INCLUDE(OMVS.NOTES.LOTUS.V5000.TEST2.HFS)) COMPRESS TOL(ENQF) LOGINDDNAME(HFSVOL) OUTDDNAME(HFSOUT) ALLDATA(*) ALLEXCP /* //************************************* //* MOUNT THE HFS DATA SET AGAIN //************************************* //IKJEFT01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * MOUNT FILESYSTEM('OMVS.NOTES.LOTUS.V5000.TEST2.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/notesdata/test2') /* //
Figure 232. Back up an HFS data set using DFSMSdss

14.6.4 Restore an HFS data set


The JCL in Figure 233 on page 300 can be used to restore the HFS data set backed up in the previous section. There are three steps: 1. Unmount the data set. 2. Restore the data set from the backup copy using the replace option. 3. Mount the data set again.

Data backup

299

//LOTUS01A JOB (999,POK),LOTUS01,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A /*JOBPARM SYSAFF=SC54 //************************************* //* UNMOUNT THE HFS DATA SET //************************************* //IKJEFT01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * UNMOUNT FILESYSTEM('OMVS.NOTES.LOTUS.V5000.TEST2.HFS') /* //************************************* //* RESTORE USING DFSMSDSS. //************************************* //RESTORE EXEC PGM=ADRDSSU,REGION=6M //SYSPRINT DD SYSOUT=* //HFSSEQ DD DSN=OMVS.NOTES.LOTUS.V5000.TEST2.HFS.DMP1,DISP=SHR //HFSOUT DD UNIT=SYSALLDA,DISP=SHR,VOL=SER=TSMS02 //SYSIN DD * RESTORE INDD(HFSSEQ) OUTDD(HFSOUT) TOL(ENQF) DATASET(INCLUDE(OMVS.NOTES.LOTUS.V5000.TEST2.HFS)) STORCLAS(SCCOMP) REPLACE CANCELERROR /* //************************************* //* MOUNT THE HFS DATA SET //************************************* //IKJEFT01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSTSOUT DD SYSOUT=* //SYSTSIN DD * MOUNT FILESYSTEM('OMVS.NOTES.LOTUS.V5000.TEST2.HFS') + TYPE(HFS) MODE(RDWR) + MOUNTPOINT('/notesdata/test2') /* //
Figure 233. Restore an HFS data set using DFSMSdss

14.6.5 Increasing the size of an HFS data set


DFSMSdss can be used to increase or reduce the size of an HFS data set, as follows: 1. Back up the data set as shown. 2. Delete the data set and reallocate it with the new size. This can be done using TSO commands or using the JCL as shown in Figure 234 on page 301. 3. Restore the data set as shown.

300

Lotus Domino for S/390 R5 Installation, Customization and Administration

//MACFAD6D JOB MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A /*JOBPARM SYSAFF=SC54 //* //************************************* //* DELETE AND REALLOC HFS FILES ON SC54 //************************************** //* //DELETE EXEC PGM=IEFBR14 //DD1 DD DSN=OMVS.NOTES.LOTUS.MAIL.HFS,DISP=(OLD,DELETE) //DD2 DD DSN=OMVS.NOTES.LOTUS.DATA.HFS,DISP=(OLD,DELETE) //DD3 DD DSN=OMVS.NOTES.LOTUS.PROD.HFS,DISP=(OLD,DELETE) //************************************* //* RE-ALLOCATE LARGER HFS FILES SPACES //* ON SC54 SYSTEM //************************************** //* //ALLOCP EXEC PGM=IEFBR14,COND=(4,LT) //NOTEPROD DD DSN=OMVS.NOTES.LOTUS.PROD.HFS, // DISP=(NEW,CATLG,DELETE),UNIT=3390, // DCB=(DSORG=PO), // SPACE=(CYL,(250,50,1)), // STORCLAS=SCCOMP, // DSNTYPE=HFS //* //NOTEDATA DD DSN=OMVS.NOTES.LOTUS.DATA.HFS, // DISP=(NEW,CATLG,DELETE),UNIT=3390, // DCB=(DSORG=PO), // SPACE=(CYL,(200,50,1)), // STORCLAS=SCCOMP, // DSNTYPE=HFS //* //MAIL0001 DD DSN=OMVS.NOTES.LOTUS.MAIL.HFS, // DISP=(NEW,CATLG,DELETE),UNIT=3390, // DCB=(DSORG=PO), // SPACE=(CYL,(200,50,1)), // STORCLAS=SCCOMP, // DSNTYPE=HFS //
Figure 234. Delete and Reallocate HFS Data Sets Bigger

14.7 RAMAC Virtual Array-based backup options


The RAMAC Virtual Array (RVA) employs an advanced storage system architecture where logical volumes, called functional volumes , are indirectly mapped to physical storage within the system. RVA configuration is done by defining up to 256 volumes in terms of traditional 3380/3390 DASD. An update to the Licensed Internal Code will bring this number to 1024. Data is dynamically mapped across a collection of physical devices organized into a logical group called an array. Mapping between the RAMAC Virtual Array functional 3380/3390 volumes and the arrays is accomplished with tables of pointers located in the control unit. The RVA is built upon the concept of virtual DASD - to the host, the volumes look like 3380/3390 devices attached to 3990 control units. The RVA with the IBM Extended Facilities Product (IXFP) does not require unallocated or allocated-and-unused capacity to occupy physical disk capacity until data is actually written to it. Neither underutilization nor overallocation

Data backup

301

reserves any actual physical storage space on disk. Only the actual data occupied on a track is stored, using only as much physical capacity as the track needs. Unallocated functional tracks and allocated-but-unused functional tracks do not occupy or reserve any physical space. At any point in time, the RVA physical space is divided into three categories: Used space consists of stored functional tracks of user data and is the main component of the Net Capacity Load (NCL). The NCL is the percentage of the total RVA capacity that is used to hold user data. Uncollected free space are pieces of storage that have been freed, but are not yet available for reuse. Since it is unusable, it is considered part of the NCL although it is not reported by IXFP. Collected free space is the space available for write operations. A common recommendation for most workloads is for you to operate the RVA at 75 percent NCL, which typically would leave 15 to 20 percent collected and 5 to 10 percent uncollected. Another feature of the RVA is that through dynamic mapping, all updates are written to new locations. Through caching, physical writes take place in sequential mode over large contiguous areas of free space, effectively converting random logical writes into physical sequential ones. The old record becomes uncollected free space. Free space collection moves data from locations in the arrays in which significant amounts of free space are available to create larger areas of contiguous free space. Free space collection is a low-priority background task, transparent to the host. With the proper support in place, deletion of a data set causes the corresponding virtual/physical space to be released and marked available for free space collection. This may seem trivial, but note that the difference with conventional devices is that the space is not returned as free space for the volume but as physical space at the whole storage system level. The RAMAC Virtual Array achieves additional savings by using compaction and a proprietary hardware compression algorithm to compress data at the channel interface in a mode transparent to the host. Typical data can achieve average compression ratios of 3.6 to 1.

14.7.1 SnapShot function


IBM RAMAC SnapShot is an advanced function made possible by the virtual architecture of the RAMAC Virtual Array. SnapShot, which consists of both host software and an added RAMAC Virtual Array feature, makes it possible to quickly create duplicate virtual copies of either volumes or data sets that may be accessed just like traditional copies. Yet the copy function requires no CPU time to complete and requires no storage space for the virtual copies until changes are made to the data. Most significantly, the elapsed time normally associated with creating copies of data is eliminated. With SnapShot, actual data is not moved but rather pointers to the data are duplicated (snapped), taking seconds rather than minutes or hours. Furthermore, physical disk space is not required to accommodate the snap until data at either the source or the target is updated.

302

Lotus Domino for S/390 R5 Installation, Customization and Administration

From a device perspective, SnapShot is an atomic process: it takes place as the result of a single I/O operation during which the data involved cannot be updated, providing the base for consistent point-in-time backup. From the MVS environment, SnapShot can be invoked by means of the SIBBATCH utility or through DFSMDdss which seems to be the preferred interface and will be described later. DFSMSdss offers two levels of SnapShot support: Native SnapShot and CC-compatible SnapShot. SnapShot can duplicate volumes or data sets, but it is important to note that not all data set organizations are supported by SnapShot. In particular, HFS data sets cannot be snapped as separate entities, but by snapping the whole volume where they reside.

14.7.2 RVA considerations for storage of HFS/Domino data


The use of the RAMAC Virtual Array as storage for the Hierarchical File System has characteristic effects that must be understood. Although these effects are not unique to HFS and may be common to other data set organizations (PDS), the reason why they are considered here is because of the dynamics of the Domino data and its sheer volume. A Domino installation with a significant number of mail users may require terabytes of HFS storage, which due to the nature of mail process and the Domino housekeeping (database compaction) can be subject to a high update rate that results in a magnified effect. Proper understanding of the RVA/HFS behavior will help to take advantage of the storage subsystem features. When an HFS data set is allocated, the net effect in the allocation of physical space in the RVA is close to nothing. DFP may create a minimum data structure, but the fact that all the tracks are empty will result in no physical space being used by the data set. Once the HFS is mounted and files are allocated, more structures will be created within the HFS data set, but it is not until when data is actually written into these files that the physical utilization or Net Capacity Load (NCL) of the RVA will be affected. There are three main considerations. Experience indicates that the Domino data tends to yield lower RVA compression ratios than average, causing the RVA to hold comparatively less. In practice, actual compression ratios will depend upon overall usage patterns. For example, widespread use of binary attachments will create denser data with lower compression ratios. Some installations have seen ratios of 2:1 or lower. This presents no problem other than the requirement to plan for the adequate capacity to handle the volume of data. Understanding the characteristics of the user's data and planning accordingly will help to avoid surprises. HFS data sets may cause higher RVA load than it appears they do according to the output of UNIX commands. For example, database housekeeping (compaction) may increase the Net Capacity Load. This could happen because, prior to R5, when Domino compacts a database, it copies the file into a new one and then deletes the original database, renaming the new one--not unlike the process to reorganize VSAM files. If the HFS structure is fairly new, the copy of the file will take place over never-used tracks, increasing the load in the RVA.

Data backup

303

On the other hand, deleting the original file will return unused space to the HFS structure, but not to the RVA. For the RVA, the old data is still there. Over time, the whole HFS will tend to appear to the RVA as fully loaded, although to UNIX services it may show available space. In principle, there is no need to reorganize an HFS, but with the RVA technology it would be advantageous to force the release of unused space at the physical level. The immediate solution is to reorganize the HFS by allocating a new one and copying all the UNIX files from the old one to the new one and then deleting or renaming the HFS data sets; obviously there are mount/unmount considerations. This could be a good option after a weekly compaction process, and obviously it does require stopping the server(s). Note that the use of DFSMSdss to restore or create a new copy of an HFS data set does not reorganize the internal data structures and as such it will not have the desired effect on the RVA; the problem will be perpetuated. An alternative would be to write a utility to create a file with low values, spanning most of the empty space in the HFS, and then subsequently deleting the file. While there would still be data written to the RVA, it would replace denser data and greatly help to decrease the NCL because of the high compression ratio of the low values. The high update activity characteristic of the Domino database compaction process can create a shortage of free collected space, causing temporary performance degradation or even an outage. During compaction, a database is rewritten in another location and the old one is deleted. The effect is that free collected space is consumed and free uncollected space is generated. If this process is repeated over a large number of databases, as would occur on a weekly compaction schedule, and the RVA is operating at a high NCL, the free collected space can be exhausted because it is used at a faster rate than the collection process consolidates uncollected space. If this situation is detected, the background collection process will be given the highest priority in the RVA and production performance will suffer. If the collection process cannot catch up, free collected space will be exhausted, resulting in the RVA not being able to process writes at all, not even a VTOC update to delete a data set to release space. It is an undesirable situation; to prevent it from happening, it is important to understand the specific RVA workload and determine what can be tolerated as the operational NCL. Also, spreading out compaction by servers over different nights will alleviate the problem.

14.7.3 DFSMSdss SnapShot for Domino backups


Assuming there is SnapShot support, DFSMSdss uses Native SnapShot when processing COPY commands for volumes, tracks, or data sets whenever the source and target volumes are on like devices in the same partition of the same RVA subsystem. No JCL changes are needed. Data is quickly copied, or snapped , directly from the source location to the target location; no reblocking or utility is required. DFSMSdss uses this method whether or not the CONCURRENT keyword is specified. With Native SnapShot, the copy of the data is logically and physically complete as soon as the snap is complete.

304

Lotus Domino for S/390 R5 Installation, Customization and Administration

Since SnapShot does not support HFS data set organization, the only option is to use the COPY FULL volume function of DFSMSdss. The following considerations are of interest:
Operational considerations : DFSMSdss requires the COPYVOLID option when performing COPY FULL volume operations. The result is that an identical copy of the source volume will be created and varied off-line. As is, it could be immediately mounted in another LPAR and would appear with the same attributes and content as the source volume, although there are catalog considerations.

With DFSMS 1.5, it is possible to have an HFS file spanning multiple volumes. In that case, all the volumes involved must be snapped at the same time, and special care taken when the data set is recatalogued to properly join all the pieces.
RVA limitations: Until now, the maximum number of volumes that could be defined in an RVA was 256. As an exercise, let's assume an RVA is loaded with 500 GB of Domino data. At 2 GB per volume, it would use 250 addresses, and since each volume snap needs a target volume, the immediate conclusion is that, until now, with 256 maximum volumes, SnapShot was not feasible for large scale Domino installations.

Recent enhancements to the RVA licensed internal code (LIC) have increased the maximum volume count to 1024. In the preceding exercise, the increase in volume capacity would allow up to three snaps of each volume. It is not an issue anymore.
Net Capacity Load: The snap operation does not take any additional NCL. It just creates a new volume table identical to the old one, pointing to the same functional tracks. Over time, as functional tracks are updated in the original volume, new versions are written but the old functional track stays in use by the target snap volume. The net effect is a growth in the NCL proportional to the update rate. Take this to an extreme by going through a compaction cycle of all the databases; since they are rewritten, it would not be unthinkable to see something less than a 100 percent increase in the Net Capacity Load. In the preceding exercise, if the operation required keeping snap volumes through a full compaction, the data would have to be spread over two RVA systems.

There are ways that an installation could make use of SnapShot without incurring a significant increase to NCL. The point is not to let a snap volume set become too different from the live volume set. In an installation with a daily 10 percent data update rate, keeping a nightly snap in the RVA would consume just a 10 percent additional NCL. This assumes discarding the previous snap as soon as a new one is taken. Similarly, keeping a generation of two snaps sets would require a 30 percent additional NCL. In addition, to avoid the surge in NCL caused by a compaction, it would be wise to discard the snap volume set before running compact and taking a new snap afterwards. The whole process could be preceded by a full tape backup of the active volume set.
Data integrity: The considerations for data integrity are similar to the ones presented earlier for DFSMSdss dump. If the volume snap is done with the

Data backup

305

servers running, there is the issue of possible database inconsistency or of incomplete data.

14.7.4 DFSMSdss Virtual Concurrent Copy


When SnapShot is available, DFSMSdss can use it to perform Concurrent Copy. This is referred to as CC-compatible SnapShot or Virtual Concurrent Copy (VCC). During the initialization phase of VCC, the data object of operation is snapped into a work area. This has two advantages. First ,the initialization is very fast. Second, since the physical dump will be done from the snapped data, there is no need to intercept writes to the original data. DFSMSdss DUMP with Virtual Concurrent Copy can be used for HFS data sets. The considerations are similar to the previously discussed DUMP with Concurrent Copy.

14.8 Tivoli Data Protection for Lotus Domino


Tivoli Data Protection for Lotus Domino is a new product that provides full online database backups as well as the capability to archive the Domino transaction log. Because it uses the new backup and recovery APIs provided in Domino R5, the backups are guaranteed to capture a consistent database image even if the databases are in use during the backup. Also, if archival logging is enabled on the Domino Server, changes to logged databases can be captured by archiving the transaction log so that full database backups need not be done as often.
Note: Tivoli Data Protection for Lotus Domino R5 was not available for us to review during the writing of this redbook. To that end, any information about this software in the sections that follow may be subject to change without notice.

For up-to-date information, contact your IBM representative or see the Tivoli Web site at:
http://www.tivoli.com/products/index/data_protect_domino

See also Tivoli Storage Manager Version 3.7: Technical Guide, SG24-5477.

14.8.1 R5 transaction logging, backup, and recovery


With Domino R5, the capabilities for backing up and restoring Lotus Notes databases are significantly improved through transaction logging. With this feature enabled, Domino captures database changes and writes them to the transaction log. If there is a problem with the database, a backup utility, using the new Domino backup and recovery API, can restore the database from a full backup and then apply changes since that back up from the transaction logs. Transaction logging is only valid for databases in the Domino R5 format. R4 format databases can easily be converted to R5 format after the Domino R5 server is installed. Earlier Domino formats do not support logging, requiring backup and recovery to be done at the full database level. In the event of a system failure, Domino automatically performs database recovery against logged R5 databases during restart. The system uses the transaction logs to apply and undo database transactions not written to disk for databases that were open during the failure. Additionally,

306

Lotus Domino for S/390 R5 Installation, Customization and Administration

Domino runs its standard FIXUP utility against R4 databases or R5 databases with transaction logging disabled. In the event that a database becomes corrupted or lost, a backup utility must be invoked to recover the database from a full backup and archived transaction log files. Tivoli Data Protection for Lotus Domino R5 is IBM's solution for this backup utility. The following items summarize some additional features of Domino R5 transaction logging and the backup and recovery API: There is one common transaction log for all databases on a Domino Server; the log may consist of multiple log files, also called extents . Although logging is turned on at a Domino Server level, it can be disabled for an individual database. There are two modes of logging: circular and archival. Circular logging means that the transaction log wraps. Archival logging requires that backups of the log be taken periodically to ensure that the log does not fill up. When backing up a database, Domino continues to allow updates to that database. If any updates should occur, pre-image data buffers are provided to the backup program which contain the data at the point in time that the backup was started. When transaction logging is enabled, Domino assigns a unique instance ID (DBIID) to each database. Transactions recorded in the transaction log include the instance ID, which is used to match transactions to databases during recovery. If the DBIID changes for a database (as a result of a COMPACT with options, FIXU, full backup, or some other action), the database is stamped with the logid and log number of the initial transaction log extent that can contain transactions against the database. This information identifies the initial log file to be searched during database recovery. Databases can be recovered to a specific point in time. The backup/recovery utility must execute on the Domino Server whose databases are being backed up or restored.

14.8.2 Description of Tivoli Data Protection


TIvoli Data Protection for Lotus Domino R5 (referred to as TDP for the remainder of this chapter) is a new backup/recovery utility for Lotus Domino databases. It exploits the backup and recovery API available with Domino R5. If archival transaction logging is specified on the Domino Server, TDP archives transaction log files and retrieve them as needed for database recovery, decreasing the frequency of doing full backups. Database backups and archived logs are stored on the Tivoli Storage Management (formerly ADSM) server. Offline database backups taken by other products (for example SnapShot, DFSMS, etc. on OS/390) cannot be rolled forward with updates from the Domino transaction log. At a high level, the following functions are provided with TDP (this list is not all-inclusive): Full backup of online databases in the Notes data directory or databases symbolically linked to the Notes data directory via database or directory links Online backup of the transaction log if archival logging is enabled Management of multiple backup versions of Domino databases

Data backup

307

Conditional backup of databases based upon modification date for unlogged databases or new DBIID for logged databases Restore of databases from any backup version and apply of changes since that backup from the transaction logs Restore of databases into a different file name Restore of logged databases to a specific point in time Restore of databases to a different Domino Server of the same platform type Expiration of database backups based upon version limit and retention period Expiration of transaction log backups when no longer needed to recover databases Expiration of database backups for deleted and excluded from backup databases Automation of scheduled backups TDP does not back up Domino executable or configuration files, only Domino databases. These other file types may be backed up using the TSM UNIX backup-archive client. TDP also does not restore an individual Notes document. To restore a Notes document, the entire database must be restored to an alternate name and the document then copied from the recovered database to the original database. TDP is implemented as a stand-alone program, not integrated into the Notes GUI. It communicates with the TSM server using the TSM API. Like the TSM UNIX backup-archive client, TDP requires TCP/IP to communicate with the TSM server and supports only a command line interface on OS/390.

14.8.3 TDP backup


TDP performs two types of backup: incremental and selective. Incremental backup, which is somewhat different from the TSM UNIX client incremental backup, does full online backup of Domino databases under the following conditions: If the database is within the Notes data directory or symbolically linked to the Notes data directory (database or directory links are not backed up) If the database is not excluded from backup by exclude statements in the TSM options (configuration) file If the database instance ID (DBIID) has changed for logged files If the database has been modified since the last backup for unlogged files. If the database is new or newly included in the backup A selective backup unconditionally backs up explicitly specified databases, unless they already are excluded from backup through exclude statements. Backups expire as dictated by retention parameters and version limits which are specified in the management class of the backups on the TSM server. TDP also archives transaction logs if transaction logging is enabled in archival mode on the Domino Server. Transaction logs must be archived frequently to ensure that they do not fill up and cause the Domino Server to stop. Transaction logs are not allowed to expire as long as there is a database backup which needs

308

Lotus Domino for S/390 R5 Installation, Customization and Administration

those logs for recovery. If circular logging is enabled, TDP does not archive the transaction log.

14.8.4 TDP restore


The restore function for TDP restores a single database or group of databases to the Domino Server. As indicated earlier, restoring to a different database name, different directory, or different Domino Server is possible. Restore to a specific point-in-time is also supported; this means that the most recent backup before that time is used for the restore. Then, if the database is logged, transactions committed prior to the specified point in time can be applied. Keep in mind that archived transaction logs can be used only by the Domino Server from which they were archived. Since updates to all logged databases on a single Domino Server are written to the same transaction log, TDP's recovery function is a two-step process. The first step is the restore of the database(s) from the appropriate Tivoli Storage Manager backup(s) to the Domino Server. The second step optionally applies all of the changes to the database(s) from the appropriate archived logs. If archival logging is in effect, TDP automatically restores the required archived transaction log files. The separation of the restore and apply functions avoids the need to restore the same transaction logs multiple times if restoring multiple databases. TDP also supports restoring logged databases from their backups without applying any changes from the transaction logs.

14.8.5 TDP performance


On OS/390, the performance of T. However, no benchmarks have been run at this time. Scalability is achieved through parallel backup sessions which can be implemented by invoking multiple instances of TDP. Additionally, the program uses multiple data buffers, whose number and size can be customized, when transferring data between Domino and the Tivoli Storage Management server.

14.8.6 Using Tivoli Data Protection


To recover individual documents, the database containing the documents can be restored to an alternate name and then the Notes client can be used to copy the desired documents from the restored database. TDP supports backup and restore of Domino databases only (including template files) and associated transaction logs. Other Domino files, such as the notes.ini file, must be backed up and restored with the TSM UNIX backup-archive client. Although full online database backup is supported by the TSM UNIX backup-archive client, the only way to guarantee a consistent backup of an online Domino database is through TDP which, through the Domino backup and recovery API, has access to pre-image data buffers if the database is in update status. If circular logging is in effect, forward recovery of restored logged databases can be done if the log has not wrapped since the backup (of the backup version being restored) was taken.

Data backup

309

Archival of transaction logs needs to be scheduled at appropriate intervals to accommodate the size of the log and the change rate for logged databases. Incremental backups of Domino databases need to be scheduled at appropriate intervals to ensure that full backups are taken after DBIIDs change and that potential restore processing times are kept at minimum (applying changes from fewer transaction logs will decrease recovery times). It is more efficient to restore a group of logged databases than individual logged databases because transaction log files required for this operation will only need to be restored once for the entire group of databases. Replicas of Domino databases on the Notes clients are not processed by TDP. Use the TSM backup client on the Notes client for these types of databases.

14.9 Backup recommendations


Our recommendation is to back up critical data (data which needs to be recovered to its state immediately preceding failure) to the TSM server, using Tivoli Data Protection for Lotus Domino R5 for Domino databases and the Tivoli Storage Manager UNIX backup-archive client for other Domino files, such as executables. TSM, together with Tivoli Data Protection (TDP) and transaction logging, provides backup/recovery facilities similar to those found in traditional mainframe transaction processing environments. If the recovery of data is less critical and TDP for R5 is not used then you could establish a replica server. TSM or DFSMSdss could be used to backup the replica server (which would be shutdown for the backup) without impacting the production server. Thus, the backup image would be consistent and, when the replica server is restarted, Domino replication updates the replica databases with the latest changes. There are some customers, with a combination of critical and less-critical data, who may choose to use a combination of tools, like TSM and DFSMSdss. Keep in mind that backups created with DFSMSdss cannot be used in conjunction with the Domino transaction log to provide forward recovery.

310

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 15. OS/390 parameter recommendations for Domino


The Domino S/390 5.0 Install Guide provides you with the latest recommendations for setting OS/390 parameters to run the Domino server. Our recommendation is that you set the parameters exactly as specified in that document. Unless you understand the relationship of all the parameters, you cannot safely choose different values. Some users have not been able to start the server because they did not follow the recommendations exactly. Problem determination can be very time consuming because it may not be clear where the problem lies. If you really do not agree with the recommended settings, we suggest that you set them as we recommend anyway, at least until you have successfully started the server for the first time. Then, using this chapter as an aid, you can change the parameters one at a time to the values you prefer. That way you will know which parameter, if any, causes you a problem. This chapter describes how the Domino server interfaces to OS/390 and gives the reasons for the recommended parameter settings. Before changing any of the recommended values you should use this chapter to help you understand what the implications may be.
Note

This chapter contains the parameter recommendations for Lotus Domino Release 5.0 for S/390 at the time of publication. These recommendations may change in later releases, so see the Domino S/390 5.0 Install Guide for the release you are installing. The parameters that we need to consider are: Overall OS/390 system parameters in SYS1.PARMLIB(IEASYSxx) OS/390 UNIX parameters in SYS1.PARMLIB(BPXPRMxx) Communications Storage Manager parameters in SYS1.PARMLIB(IVTPRMxx) SMF recording parameters in SYS1.PARMLIB(SMFPRMxx) Domino server parameters If you are running in compatibility mode (i.e. if you are using IEAIPS/IEAICS) rather than Workload Manager goal mode you also need to review those parameters to make sure that they will not restrict Domino. For example, Domino uses many address spaces, so make sure that the multiprogramming level (MPL) for Domino is high enough. Also, make sure that Domino can get the storage that it needs. In goal mode the Workload Manager takes care of these things as long as you give Domino a reasonable velocity. For more information on the OS/390 parameters in SYS1.PARMLIB, see OS/390 MVS Initialization and Tuning Reference, SC28-1752.

Copyright IBM Corp. 1999

311

15.1 How Domino uses OS/390 facilities


Before we describe the OS/390 and Domino parameters, it is helpful to understand how the Domino server interfaces with OS/390 and uses OS/390 facilities.

15.1.1 Domino Server tasks


When the Domino server runs on OS/390, it runs in a number of address spaces, as shown in Figure 235.

Main Server Task

Server Tasks as defined in notes.ini


Figure 235. Domino Tasks in OS/390 address spaces

The main server task is always started, as well as an address space for active user connections. In addition, a number of other tasks run, depending on the tasks started in the notes.ini file, plus those started later with a load command. Figure 236 shows part of a notes.ini file with eight additional server tasks being started. On this system you would therefore see 8+3=11 server tasks started when the Domino server starts.

ServerTasks=Replica,Router,Update,Stats,AMgr,Adminp,Sched,Calconn
Figure 236. Server tasks in notes.ini

15.1.2 OS/390 UNIX processes


Each Domino server task runs as a separate UNIX process, as shown in Figure 237 on page 313.

312

Lotus Domino for S/390 R5 Installation, Customization and Administration

ps -ef | grep -i lotus PID TTY TIME CMD 234881050 ttyp0001 0:02 /lpp/lotus/notes/latest/os390/adminp 1392508956 ttyp0001 0:09 /lpp/lotus/notes/latest/os390/server 184549405 ttyp0001 0:03 /lpp/lotus/notes/latest/os390/amgr 318767134 ttyp0001 0:01 /lpp/lotus/notes/latest/os390/update 268435487 ttyp0001 0:01 /lpp/lotus/notes/latest/os390/replica
Figure 237. Domino tasks and UNIX processes

In OS/390, a process maps into an MVS address space and an MVS task environment exists for the process; the terms are a task control block (TCB) and related control blocks. In addition to the TCB, the OS/390 UNIX kernel address space maintains a number of control blocks that represent a process. These control blocks exist within the kernel address space; they are created when an existing standard MVS program begins using OS/390 UNIX System Services (OS/390 UNIX) or when a new process is created by the OS/390 UNIX process creation functions. When an address space begins using OS/390 UNIX services, we say the MVS address space is dubbed as an OS/390 UNIX process. From a UNIX perspective, this means OS/390 UNIX assigns a PID (process ID) to the process. Control blocks in common storage and the kernel address space are built to represent this piece of work. These control blocks build the infrastructure that OS/390 UNIX uses to keep track of all you do. In addition to the process control blocks, task level control blocks are created in the user address space and in the kernel. Each task is treated the same as a UNIX thread. By default, a new process will run as the job step task in an MVS address space. There are situations where more processes may exist within the same MVS address space. In such a case, a process may run as a subtask of the job step task. Processes are created with: The fork() function and BPX1FRK service The spawn() function and BPX1SPN service The exec() function and BPX1EXC service

15.1.3 The Domino processing model


In Domino 4.x, when a client session connected to the server, it would be given a physical thread in an address space (process) for the duration of its connection to the server. One hundred threads could run in a process (address space) before another process was forked. The one hundred and first thread would run in the second process (address space) and so on. In Domino R5, this processing model has changed to use the thread pool model utilizing asynchronous I/O. Instead of running potentially many processes for client connections, Domino 5.0 uses a single process to service all incoming connection requests. Through the use of the notes.ini variable Server_Pool_Tasks the administrator defines the number of physical threads that

OS/390 parameter recommendations for Domino

313

support an almost limitless (within certain architectural limitations) number of virtual threads in an address space.

Note: We recommend that you initially set Server_Pool_Tasks to 100. This appears to be a good starting point for most platforms (including OS/390).

When a user connects to the server, a client session is created with a unique socket descriptor and a virtual thread ID is assigned. When a client performs I/O, a physical thread is associated with the virtual thread and does the associated work on behalf of the clients session. After the work is completed the physical thread is effectively returned to a pool of threads. It is no longer associated with the virtual thread and is available to service another request. The Threadpool model in Domino 5.0 is much more efficient than the processing model in previous releases of Domino. Here are just a few examples of why the Threadpool model is better: The number of processes and address spaces, which consume lots of storage, is much lower. The number of threads for each client session is much lower. This reduces operating system overhead. Socket descriptor handoff from one process to another process is no longer required each time a new client session is created. The frequency of lock and semaphore contention competing for the same resources in both the operating system and Domino application is much lower.

15.1.4 OS/390 UNIX threads


UNIX threads allow a program to work with more dispatchable units of work without the need for the advanced functions of fork or spawn. Application programs create a new thread with the pthread_create() service. For more information on OS/390 UNIX processes and threads see: OS/390 UNIX System Services Planning, SC28-1890 OS/390 UNIX System Services Porting Guide, available at:
http://www.s390.ibm.com/oe/bpxa1por.html

15.1.5 OS/390 address spaces


For Domino, each server task and process runs in a separate OS/390 address space. Therefore, when you run the Domino server, you will see a number of address spaces, as shown in Figure 238 on page 315.

314

Lotus Domino for S/390 R5 Installation, Customization and Administration

D A,L IEE114I 11.40.53 1997.206 ACTIVITY 209 JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM 00015 00019 00006 00029 00055 00006/00030 LLA LLA LLA NSW S JES2 JES2 IEFPROC VTAM44 VTAM44 NET NSW S OSASF OSASF OSASF DFSMSHSM HSMSC53 DFSMSHSM NSW S VLF VLF VLF RMF RMF IEFPROC NSW S APPC APPC APPC ASCH ASCH ASCH NSW S SDSF SDSF SDSF DFRMM DFRMM IEFPROC NSW S OPTSO OPTSO OPTSO TSO TSO STEP1 OWT S IHV IHV PSTEP01 EEQTP000 HCM DONNAS OWT A TCPIP TCPIP TCPIP PORTMAP PORTMAP PMAP OWT S RXPROC RXPROC RXSERVE IOASRV IOASRV SERVER OWT S FTPD1 STEP1 STC INETD1 STEP1 STC OWT AO SC13CMA1 SC13CMA1 CPSM130 DOMINO STEP1 DOMINO OWT AO FTPD4 *OMVSEX STC DOMINO6 STEP1 DOMINO IN AO DOMINO7 STEP1 DOMINO DOMINO8 STEP1 DOMINO IN AO DOMINO9 STEP1 DOMINO DOMINO1 STEP1 DOMINO IN AO DOMINO3 STEP1 DOMINO DOMINO4 STEP1 DOMINO IN AO DOMINO5 STEP1 DOMINO DOMINO6 STEP1 DOMINO IN AO DOMINO7 STEP1 DOMINO SIMONL OWT JACQUES OWT SOREN OWT RODRIGO OWT MACFAD4 IN DONNAS OWT
Figure 238. Address spaces for the Domino Server

OAS 00017 NSW S IN S NSW S NSW S NSW S OWT S IN S NSW SO OWT S OWT AO NSW S OWT A0 IN AO IN AO IN AO IN AO IN AO

You can see the mapping between UNIX processes and OS/390 address spaces with the OS/390 console command D OMVS,A=ALL. See Figure 308 on page 399 for an example.
15.1.5.1 Names of address spaces As you see in Figure 238, all of the Domino address spaces start with DOMINO. DOMINO was the RACF user ID used to start the Domino server. If we started the Domino server from a different RACF user ID, all the address space names would start with that user ID.

OS/390 adds a suffix of one digit, 0 through 9, to the user ID that starts the Domino server to create the address space name. When the count goes above 9, OS/390 wraps back to 0 and uses the same name for a different address space. Thus, each address space name may be used many times, but each address space will have a unique address space ID (ASID). The Display active users panel in SDSF shows the status of each address space for the Domino server, as shown in Figure 239 on page 316. The JOBID shows the unique address space ID for each address space for the Domino server.

OS/390 parameter recommendations for Domino

315

Display Filter View Print Options Help -----------------------------------------------------------------------SDSF DA SC53 SC53 PAG 0 SIO 0 CPU 4/ 3 LINE 1-10 (10) COMMAND INPUT ===> PREF DOMINO* SCROLL ===> PAGE NP JOBNAME STEPNAME PROCSTEP JOBID OWNER C POS DP REAL PAGING SIO DOMINO STEP1 A0000072 DOMINO LO FF 441 0.00 0.00 DOMINO4 STEP1 A0000081 DOMINO IN C4 566 0.00 0.00 DOMINO9 STEP1 A0000086 DOMINO IN C2 674 0.00 0.00 DOMINO7 STEP1 A0000084 DOMINO LO FF 569 0.00 0.00 DOMINO3 STEP1 A0000080 DOMINO IN C7 844 0.00 0.00 DOMINO1 STEP1 A0000088 DOMINO IN C3 637 0.00 0.00 DOMINO6 STEP1 A0000083 DOMINO IN C6 725 0.00 0.00 DOMINO5 STEP1 A0000082 DOMINO LO FF 576 0.00 0.00 DOMINO8 STEP1 A0000089 DOMINO IN C4 592 0.00 0.00 DOMINO6 STEP1 A0000090 DOMINO IN C4 592 0.00 0.00 DOMINO7 STEP1 A0000092 DOMINO LO FF 556 0.00 0.00

F1=HELP F7=UP

F2=SPLIT F8=DOWN

F3=END F9=SWAP

F4=RETURN F10=LEFT

F5=IFIND F11=RIGHT

F6=BOOK F12=RETR

Figure 239. Address space IDs for the Domino Server

15.1.6 Effect of Domino on OS/390 parameters


We have seen that Domino uses threads, processes, and address spaces on the OS/390 operating system. You need to review your OS/390 parameters to ensure that your system can support the running of Domino.

15.2 Overall system parameters in SYS1.PARMLIB(IEASYSxx)


Table 27 shows the IEASYSxx system parameter that needs reviewing for Domino.
Table 27. IEASYSxx Parameter for Domino

Name
MAXUSER

Description
The value that the system uses to limit the number of jobs and started tasks that can run concurrently.

Value Range
0 to 32,767 Default: 255

Recommendation
Add at least 10 to your current value.

Affects
Capacity

MAXUSER Specifies a value that the system uses to limit the number of jobs and started tasks that can run concurrently during a given IPL. It limits the total number of address spaces that can be created simultaneously across the whole of OS/390, including TSO users, UNIX address spaces, batch jobs, and others.

We saw above that Domino typically runs with at least 10 address spaces, so you may need to increase the value of MAXUSER by at least 10 to ensure you have defined enough address spaces for your system.
Note: Unlike previous releases of Domino, Release 5.0 no longer has any special requirements for the SQA parameter.

316

Lotus Domino for S/390 R5 Installation, Customization and Administration

15.3 OS/390 UNIX parameters in SYS1.PARMLIB(BPXPRMxx)


The SYS1.PARMLIB member BPXPRMxx contains the parameters that control the OS/390 UNIX environment. Table 28 shows the parameters that need to be reviewed for Domino.
Table 28. OS/390 UNIX parameters

Name
MAXFILEPROC

Description
The maximum number of files that a single process can have concurrently active or allocated. The maximum amount of shared storage pages that can be concurrently in use by UNIX functions. This parameter can be used to control the amount of ESQA consumed. The maximum number of MVS tasks that a single process can have concurrently active. The maximum number of threads that a single process can have concurrently active. The maximum number of semaphore sets in the system. The maximum number of operations for each semaphore operation call. The maximum number of unique system-wide shared memory segments. The maximum number of pages for a shared memory segment. This parameter effects Notes_SHARED_DPOOLSIZE. The maximum number of attached shared memory segments for each address space. The maximum number of system-wide shared pages created by calls to fork and shmat functions. How user storage is to be copied from the parent process to the child process during a fork() call. The maximum number of UNIX domain sockets.

Value Range
3 to 65,535 default: 64 0 to 32,768,000 default: 131,072

Recommendation
65535 (maximum)

Affects
Performance

MAXSHAREPAGES

32,768,000 (maximum)

Storage

MAXTHREADTASKS

0 to 32,768 default: 50 0 to 100,000 default: 200 1 to 20,000 default: 500 0 to 32,767 default: 25 1 to 20,000 default: 500 0 to 25,600 default: 256

1,000

Capacity

MAXTHREADS

1,000

Capacity

IPCSEMNIDS IPCSEMNOPS

20,000 (maximum) 32,767 (maximum)

Performance Performance

IPCSHMNIDS

500 (default)

None

IPCSHMMPAGES

25,600 (maximum)

Storage

IPCSHMNSEGS

0 to 1,000 default: 10

1,000 (maximum)

Storage

IPCSHMSPAGES

0 to 2,621,440 default: 262,144

2,621,440 (maximum)

None

FORKCOPY

COW or COPY default: COW 0 to 64,498 default: 100

COPY

Performance

NETWORK DOMAINNAME (AF_UNIX) MAXSOCKETS

10,000

None

OS/390 parameter recommendations for Domino

317

Name
NETWORK DOMAINNAME (AF_INET) MAXSOCKETS MAXASSIZE

Description
The maximum number of IP domain sockets.

Value Range
0 to 64,498 default: 100

Recommendation
35,000

Affects
Capacity

The address space region size that a process receives.

10,485,760 to 2,147,483,647 default: 41,943,040 7 to 2,147,483,647 default: 1,000 Maximum value: 100,000

2,147,483,647 (maximum)

Capacity

MAXCPUTIME

The CPU time that a process can use. The maximum number of queued signals, which are used by Domino whenever asynchronous I/O read/write to a client session completes.

2,147,483,647 (maximum) 100,000

Operation

MAXQUEUEDSIGS

Operation

MAXFILEPROC Specifies the maximum number of files that a single process can have concurrently active or allocated. MAXFILEPROC is the same as the OPEN_MAX variable in the POSIX standard.

We recommend that you set this value asshown in Table 28.


MAXSHAREPAGES Specifies the maximum amount of shared system storage pages that UNIX functions can use. This limits the amount of shared storage reserved in UNIX System Services data spaces for use by all UNIX applications. The control blocks that manage the shared pages are in ESQA.

We recommend that you set this value to the maximum value of 32,768,000 so that you do not limit the use of shared storage. If you do not make enough shared storage available, the Domino server may not start properly.
MAXTHREADTASKS

Speciifies the maximum number of MVS tasks that a single process can have concurrently active for pthread_created threads. For the Domino server we recommend that you set the value to 200. You need to ensure that the value is high enough for any other UNIX applications that you may run. See the notes for MAXTHREADS.
MAXTHREADS Specifies the maximum number of pthread_created threads that a single process can have concurrently active.

The recommendation is to set the value to 200. If the value in MAXTHREADTASKS or MAXTHREADS is too low, it may cause a system hang not only to the Domino server but also to TCP/IP when manipulating the Notes user.
Figure 240. Error message on Notes client for hang of Domino Server

318

Lotus Domino for S/390 R5 Installation, Customization and Administration

You can check how many threads there are in a process by issuing the command D OMVS,A=asid to find a specific address space ID, as in Figure 241.

D OMVS,A=55 BPXO040I 15.19.31 DISPLAY OMVS 995 OMVS 000F ACTIVE USER JOBNAME ASID PID PPID STATE START CT_SECS DOMINO DOMINO7 0055 452984852 436207643 1S 14.41.28 3.051 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/sched
Figure 241. D OMVS,A=asid to find the address space ID

Then you can issue the command D OMVS,PID=process_id for the process ID that you want to check the number of threads for, as in Figure 242.

D OMVS,PID=452984852 BPXO040I 14.47.08 DISPLAY OMVS 983 OMVS 000F ACTIVE USER JOBNAME ASID PID PPID STATE START CT_SECS DOMINO DOMINO7 0055 452984852 436207643 1S 14.41.28 1.928 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/sched THREAD_ID TCB@ PRI_JOB USERNAME ACC_TIME SC STATE 0958303800000000 007E3400 OMVS 1.909 SLP S
Figure 242. D OMVS,PID=process_id to display number of threads

If the current value of MAXTHREADS (or MAXTHREADTASKS) is too low, you can change the value dynamically using the OS/390 command SETOMVS MAXTHREADS=xxx (or SETOMVS MAXTHREADTASKS=xxx) where xxx is the new value.
IPCSEMNIDS Specifies the maximum number of unique system-wide semaphore sets. This value limits the number of semaphore sets that you can have. We recommend that you set it to the maximum value because the Domino server uses semaphores heavily. IPCSEMNOPS Specifies the maximum number of operations for each semaphore call. This value limits the number of operations that can be performed against a semaphore. We recommend that you set it to the maximum value because the Domino server uses semaphores heavily. IPCSHMNIDS Specifies the maximum number of unique system-wide shared memory segments. The default value is OK for the Domino server. IPCSHMMPAGES Specifies the maximum number of pages for shared memory segments. The default value is 256 4K pages, which is 1 MB of shared memory. That means that a UNIX application can only get at most 1 MB of shared memory for each request.

Domino uses shared memory extensively. To allow it to get more shared memory with each request, and therefore reduce the number

OS/390 parameter recommendations for Domino

319

of requests it has to make, we recommend that you set this parameter to the maximum value of 25,600.
Note: If the value of IPCSHMMPAGES is less than the value of Notes_SHARED_DPOOLSIZE the Domino server will not start properly. See 15.5, Notes_SHARED_DPOOLSIZE parameter on page 321 for further discussion of this. IPCSHMNSEGS Specifies the maximum number of attached shared memory segments for each address space. We recommend that you set it to the maximum value so that the Domino server can use enough shared storage. If the value is too low, the Domino server will not start. IPCSHMSPAGES Specifies the maximum number of system-wide shared pages created by calls to fork and shmat functions. Set this parameter to the maximum value. FORKCOPY Specifies how user storage is to be copied from the parent process to the child process during a fork() or spawn() call. The Domino server uses spawn() to create additional processes.

The recommendation is to use FORKCOPY(COPY) to achieve the best performance of the Domino server.
NETWORK DOMAINNAME(AF_UNIX) MAXSOCKETS Represents the maximum number of UNIX domain sockets. Domino uses these for interprocess communication. We recommend that you set this value to 10,000. NETWORK DOMAINNAME(AF_INET) MAXSOCKETS Represents the maximum number of IP domain sockets. All client users of Domino connect through TCP/IP, so we recommend that you set this parameter to 35,000. MAXASSIZE Specifies the address space region size (RLIMIT_AS) resource values that a process receives when it is identified as a process. We recommend that you set it to the maximum value so that the Domino server can get whatever region size it needs. MAXCPUTIME Specifies the RLIMIT_CPU (the CPU time, in seconds, that a process can use) resource values that a process receives when it is identified as a process.

We recommend that you set this value to the maximum value to prevent the server from shutting down because it has used up the allowed processor seconds.
MAXQUEUEDSIGS

The maximum number of queued signals, which are used by Domino whenever asynchronous I/O read/write to a client session completes. Set it to the maximum value.

320

Lotus Domino for S/390 R5 Installation, Customization and Administration

Note: There are no longer specific recommendations for the values of MAXPROCSYS and MAXPROCUSER with Domino 5.0. Ensure your values are high enough to not constrain work in your UNIX System Services environment.

15.4 CSM parameters in SYS1.PARMLIB(IVTPRMxx)


The Communications Storage Manager (CSM) is a component of VTAM that allows authorized host applications to share data with VTAM and other CSM users (such as TCP/IP) without having to physically copy the data. In order for Domino to run smoothly you must ensure that the storage values for CSM as defined in the PARMLIB member IVTPRMxx are as follows:
FIXED MAX(120M) This defines the maximum amount of storage dedicated to fixed CSM buffers. ECSA MAX(30M ) This defines the maximum amount of storage dedicated to ECSA CSM buffers. Note: With eNetwork Communications Server you no longer need to code any POOLSIZE values in the TCP/IP profile dataset.

15.5 Notes_SHARED_DPOOLSIZE parameter


The Domino Server uses the UNIX parameter shown in Table 29.
Table 29. Domino Server UNIX parameter

Name
Notes_SHARED_ DPOOLSIZE

Description
The size of shared storage that the Domino server will ask for in each request

Value Range
Not known

Recommendation
8,388,608

Affects
Performance

Notes_SHARED_DPOOLSIZE Specifies the number of bytes of shared storage that the Domino server will ask for in one request to the OS/390 UNIX services. A small value means that the Domino server has to repeat the memory allocation process more often. We recommend that you leave this parameter at the default value (8 MB) so that the Domino server will get better performance. Note: You need to be careful about the link with the value of the IPCSHMMPAGES parameter in SYS1.PARMLIB(BPXPRMxx). If the value in Notes_SHARED_DPOOLSIZE is greater than the maximum allowed by IPCSHMMPAGES, the Domino server will fail to start,. as shown in Figure 243 on page 322.

OS/390 parameter recommendations for Domino

321

# server CEE3204S The system detected a protection exception. From compile unit ./ospanic.c at entry point Panic at statement 327 at compile unit offset +00000410 at address 083F9E28. [1] + Done(139) server 1593835542 FSUM7746 Segmentation violation /usr/lpp/lotus/notes/latest/os39 0/server #
Figure 243. Server fails to start - Iisufficient IPCSHMMPAGES value

Once you have set IPCSHMMPAGES to the recommended 25,600 (100 MB), we recommend that you set Notes_SHARED_DPOOLSIZE to 8,388,608 (8 MB), which is the default.
Note: This recommendation is different from the 4.6.x value of 32 MB.

You set this parameter as a UNIX environment variable before you start the Domino server. Put the statement export Notes_SHARED_DPOOLSIZE=8388608 in the.profile file in the home directory of the user ID that will start the Domino server. This file will be read automatically when the user ID logs into the UNIX environment.

322

Lotus Domino for S/390 R5 Installation, Customization and Administration

Part 4. Notes administration

Copyright IBM Corp. 1999

323

324

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 16. Simple administration tasks


In this chapter we describe some simple administration tasks, such as creating a new user ID, registering a new server, and accessing the Domino Server console from different interfaces. For most of the administration tasks, you first have to launch the Domino Administration Client.

16.1 Installing the Lotus Domino Administrator client


The Administrator client has a brand new task-oriented interface that brings all of the tools and information required to administer a Domino infrastructure within easy reach. The various areas of concentration are segregated in a tabbed interface to aid in navigation and speed of access. This chapter details the requirements and procedures for the installation of the client on an administrators workstation. Although the new R5 administration client is very different from the administration panel of an R4.x client, backward compatibility was a major design goal to enable the new administration client to be used successfully in a mixed server environment.
Note: Although backward compatibility is achieved, not all of the new features will work when used against an R4.x server, and in some cases errors may be experienced.

16.1.1 System requirements


There is no client provided for the OS/390 platform. So the details given in this chapter will relate to the installation of the Administrator Client on the Win32 platform. The Win32 platform clients require the following machine specification: An Intel Pentium processor or higher Win95/98: 16 MB RAM minimum, 32 MB+ recommended Win NT: 24 MB RAM minimum, 32 MB+ recommended Minimum of 150 MB free disk space for full install

16.1.2 Pre-installation steps


As with any software upgrade, the first and most important step is to back up important client files. The main ones are listed in Table 30.
Table 30. Backing up important client files

Files
Notes configuration (notes.ini) Desktop configuration (desktop.dsk) Personal address book (names.nsf) User ID files (*.id)

Default location
Windows directory - e.g. C:\WinNT or C:\Windows for Windows 9x Notes data directory - e.g. C:\NOTES\DATA Notes data directory - e.g. C:\NOTES\DATA Notes data directory - e.g. C:\NOTES\DATA

Copyright IBM Corp. 1999

325

Files
Local databases (*.nsf) Local templates (*.ntf) Local database directory links (*.dir)

Default location
Notes data directory - e.g. C:\NOTES\DATA Notes data directory - e.g. C:\NOTES\DATA Notes data directory - e.g. C:\NOTES\DATA

16.1.3 Client software installation


The client installation has four options: 1. 2. 3. 4. Install Install Install Install all clients. the Notes client. the Domino Administrator. the Domino Designer.

Before starting to install the client, decide whether to install the single administration client, or all clients on the machine.
Recommendation

In a Win32 server environment, where the administration client can be installed on the server, a Domino Administrator only installation is relevant. In an OS/390 server environment, the administration client must be run from an administrators workstation. Since the administrator is also a user (and will usually require designer capabilities), it is easy to install all clients in one procedure using the Install all clients option. Perform the following steps to install client software: 1. For a client upgrade, move the existing notes.ini file from the Windows directory into the Notes data directory. 2. Click Start -> Run from the Start menu and type x:\.....\setup.exe in the dialog box and then press Enter (where x: is the drive letter of the CD-ROM). 3. Click Next and then click Yes to accept the license agreement. 4. Confirm or type in Name and Company details (see Figure 244 on page 326).

Figure 244. Set or edit User Name and Company details

326

Lotus Domino for S/390 R5 Installation, Customization and Administration

5. This is assumed to be a local install on a workstation, and not a shared file server installation, so ensure the Shared Installation option is not selected and click Next. 6. Set the Notes program and data directories. If they are incorrect, click the appropriate Browse button, choose the required directory, then click Next to continue (see Figure 245).

Figure 245. Choosing client program and data directories

7. Select either All Clients or Domino Administrator (see Figure 246 on page 327).

Figure 246. Choosing the client installation type

Simple administration tasks

327

8. To customize the installation options, click Customize. See 16.1.4, Customizable installation options on page 328 for further details. 9. Click Next to continue. 10.Choose an existing program folder for the application icons or type in a new one and click Next (see Figure 247).

Figure 247. Choosing a folder for the client program icons

11.Click Next to begin the installation of the files. 12.Once installation is complete, restart the workstation if prompted to do so.

16.1.4 Customizable installation options


During the installation, an option is presented to customize the items that will be installed with the clients. The list of customizable options depends on whether the All Clients or Domino Administrator install option is chosen. Figure 248 shows some of these options.

328

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 248. Customizing client installation options

A checkmark in the box to the left of the option name means that the option will be installed. It may be made up of sub-options and when clicking an option, the Change button is either available or greyed-out, depending on whether the current option has customizable sub-options. Clicking the Change button shows a dialog box containing the sub-options that can be selected or de-selected, as required (see Figure 249).

Figure 249. Changing sub-components of an install option

Simple administration tasks

329

A description of the install options and their sub-components is shown in Table 31.
Table 31. Client installation components

Component name
Administration Client Common Data

Sub-component names
<None> Optional Data Files Domino Admin Optional Templates <None> DECS Domino Designer Data Administration Guided Tour Designer Guided Tour Administration Help Client Help Designer Help Client Guided Tour cc:Mail Client Migration Tools cc:Mail Admin Migration Tools Calendar Client Migration Tools Eudora Client Migration Tools Organizer Migration Groupwise 4 Admin Migration Groupwise 4 Client Migration Groupwise 5 Admin Migration Groupwise 5 Client Migration Netscape Admin Migration Netscape Client Migration Exchange Admin Migration Exchange Client Migration MS Mail Admin Migration MS Mail Client Migration LDIF Admin Migration NT Admin Migration Required Data Files Modem Command Scripts Icons Readme <None> Extended Viewers Required Program Files Java Support Network Drivers JIT Debugger Import Export Engine Client Mail MS Office Main Integration Windows System Files Uninstaller System Files

Designer Client DECS Domino Designer Help

Migration Tools

Notes Data Files

Notes Minder Notes Program Files

NT Client Single Logon

330

Lotus Domino for S/390 R5 Installation, Customization and Administration

Component name
Shared Install Spell Checker

Sub-component names
<None> International Directories Chinese Spell Checker English Dictionaries

16.1.5 Client configuration


The installation may have been performed over an existing client configuration, or it may be a brand-new setup where there was no previous Notes client on the machine. There are additional steps that must be carried out if the machine did not have a previous release of the client already installed.

16.1.6 Configuration of a new client


Follow this procedure to perform client setup once the installation of the files is complete: 1. Click Start -> Programs -> Folder Name -> Lotus Domino Administrator. 2. The client will present the Lotus Notes Client Configuration wizard welcome screen (see Figure 250); click Next to continue.

Figure 250. The Client Configuration wizard

3. Select the option I want to connect to a Domino server, then click Next (see Figure 251).

Simple administration tasks

331

Figure 251. Choosing to connect to a Domino Server

4. Select the option Set up a connection to a local area network (LAN) and then click Next ( see Figure 252 on page 332).

Figure 252. Choosing to connect via a LAN

5. Type in the name of the server to make the initial connection (see Figure 253 for an example server domino1/ITSO). Then click Next.

332

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 253. Enter the server name

6. Specify whether the Notes ID file has been provided in a file, as used in this example, or is stored in the Domino Directory. 7. Type in the filename (use the Browse button if necessary to locate the file) or the user name (see Figure 254 on page 333 for an example of user.id). Then click Next.

Figure 254. Specifying the User ID file during client setup

8. Enter the password for the ID file specified in step 6 and click OK . 9. Click Next to continue (see Figure 255).

Simple administration tasks

333

Figure 255. Completed client connection definition

10.Choose whether an Internet mail account is required. See Figure 256 for an example where no Internet account will be set up.

Figure 256. Choosing not to create an Internet mail account

11.The Client Configuration wizard is now complete (see Figure 257). Click Finish to end the wizard and complete the configuration.

334

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 257. Completing the Client Configuration Wizard

12.A progress indicator, shown in Figure 258 on page 335, will be displayed showing percentage complete of setup tasks.

Figure 258. Client setup progress indicator

13.When the setup is complete, click OK to close the last dialog box. The remaining stages of configuration are the same whether you perform a new installation or upgrade an existing client. Refer to the following section for details of these common steps.

16.1.7 Configuration of an upgraded client


All of the settings from a previous notes.ini file will be preserved. When the administration client is started for the first time, it will prompt for the current IDs password, and then the following stages must be completed: 1. A bookmark database will be created automatically to store references to servers in the domain (see Figure 259).

Simple administration tasks

335

Figure 259. Creating the bookmark database

2. The Administration Client Splash screen will be displayed (see Figure 260 on page 336). It has a link called Show me the new R5 Domino Administrator that links to pages of information relating to new functions and features of the administration client.

Figure 260. The Administration Client welcome screen

3. To stop this screen from displaying each time the administration client is started, click the option Dont show this again at the right top corner of the page.
336

Lotus Domino for S/390 R5 Installation, Customization and Administration

4. To close the splash screen, click the cross on the right-hand side of the window tab labelled Welcome to Domino Administrator R5 (see Figure 261).

Figure 261. Closing the Administration Client welcome screen

5. The initial pane of the bookmarks is blank. To see the servers in the domain, click the bookmark tab, as shown in Figure 262 on page 337.

Figure 262. Administration Client servers bookmark icon

6. This will display the main bookmark view of the servers in the domain (see Figure 263).

Figure 263. The Administration Client server bookmarks

7. To populate the Favorites bookmark pane, right-click the mouse on one of the servers displayed. From the pop-up menu, click Add Server to Favorites as shown in Figure 264.

Figure 264. Adding a server to bookmark favorites

8. To customize the administration preferences click File -> Preferences -> Administration Preferences on the client menu (see Figure 265 on page 338).

Simple administration tasks

337

Figure 265. Setting Administration Client preferences

9. As shown in Figure 266 on page 339, the first panel is Basics. It shows details of the domains to be managed. Additional domains (other than the current specified) can be added here, along with specific client locations that should be used for each of those domains. 10.The Directory server field entry determines which server the client will query for directory details about that domain.

338

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 266. Administration Preferences - Basics

11.Click the Files icon to display a panel where the columns of the file display can be customized and ordered as shown in Figure 267.

Figure 267. Administration Preferences - Files

12.Click the Monitoring icon to configure specific monitoring details such as the amount of local memory to use to store monitoring information (see Figure 268). In addition, servers can be defined to be monitored on a per location document basis.

Simple administration tasks

339

Figure 268. Administration Preferences - Monitoring

13.Click the Registration icon to configure standard registration details such as registration server and certifier as shown in Figure 269 on page 340. These will be used as defaults for future registration actions.

Figure 269. Administration Preferences - Registration

Once these preferences are completed, the client is ready for use to manage and monitor the Domino infrastructure.

340

Lotus Domino for S/390 R5 Installation, Customization and Administration

Additional material, such as details of specific settings and features, can be found in the online database entitled Lotus Domino R5 Administration Help.

16.2 Using the Domino Administrator


One of the simplest administration tasks, and one you will perform often, is choosing the server from your Domino Administrator.

16.2.1 Selecting a server


To change the current server, click the icon on the left side of Domino Administrator showing two servers (see Figure 270).

Figure 270. Server icon

A new Window will pop up, showing all servers categorized in different views (see Figure 271 on page 341).

Figure 271. Listing of all servers in the domain

Select the server you want to make changes to in the Domino Directory by clicking the server name.

16.2.2 Refresh server list


If you have added a server and the new server is not in the list, or if the server icon is not shown, you have to refresh the server list. You do this by selecting Administration -> Refresh Server List. You have to choose between Current Domain and All Configured Domains. The server list will now be refreshed and the icon shown.

16.2.3 Registering a user


As in the previous Notes release, you can register one person at a time, or read many user details from a file. In Lotus Domino R5 you can also import users from other directory servers. However, in this section we only describe how to register a single user.

Simple administration tasks

341

To register a person, follow these steps: 1. In Domino Administrator, choose the desired server. 2. Click People & Groups. 3. Open the Menu Tools -> People on the right side and click Register.... 4. Choose certifier and enter the certifier password. 5. There are two options: basic and advanced registrations. In the normal panels, you can enter Name, Password and the groups (see Figure 272).

Figure 272. User Registration

If you select the Advanced checkbox, you have more options for each user (see Figure 273 on page 343).

342

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 273. User Registration - Advanced Options

Because it is most likely that you are using the advanced options, we will only describe these.
Basics section:

a. Check the registration server and change it if needed. b. Enter first and last name. c. Choose the Password Quality. Longer passwords are more secure, and eight characters is a good choice if you want to use the password as the Internet password as well. d. Enter the password. e. Check Set Internet password, if the user will have access to the Domino Server via browser client. f. Enter the Internet address or choose how to create it by pressing the Format... button. First and last name separated by a dot is a widely used mail user name. See Figure 274 on page 344.

Simple administration tasks

343

Figure 274. Set Internet Address Format

Mail section (see Figure 275 on page 345):

a. Choose the Mail system . If you choose Other Internet or Other, you have to enter the forwarding address. b. Choose the Mail server. c. Choose the Mail file template. d. Change the Mail file name. e. Choose the access permissions for the mail file. f. Set the database quotas and warning threshold if you want to use this feature. g. Choose whether to create the mail database during registration or later in the background.

344

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 275. User Registration - Mail Section

ID Info section (see Figure 276 on page 346):

a. Choose the Certifier ID. b. Choose the Security type and the Certificate expiration date. c. Choose where the created ID file should be stored.
Note: If you only want to create a POP3 or IMAP mail user, de-select both locations for storing the user ID. In this case no Notes Certificate will be created for the user ID.

Simple administration tasks

345

Figure 276. User Registration - ID Info section

Groups section:

a. Choose the groups the user should belong to.


Other section (see Figure 277 on page 347):

a. If you have created a User Setup Profile, you can choose it here. b. Enter additional user information such as Location, Local Administrator, and Comment. c. If you have created an alternate name language you can add an alternate name here. For more information about the feature, refer to the Lotus Domino R5 Administration Help database. d. If you have a mixed OS/390 and Windows NT environment, you can register this person in Windows NT by selecting Add this person to Windows NT and entering the Windows NT user name and the Windows NT group.

346

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 277. User Registration - Other section

6. Press Add Person . 7. If you want to add more users, go back to Step 5 on page 342. All user details will be added to the Registration Status window. 8. Press Options to set the Advanced Person Registration Options (see Figure 278 on page 348). These are: Do not continue on registration errors. Keep successfully registered people in the queue. Try to register queued people with error status. Allow registration of previously registered people. Dont prompt for a duplicate person (skip registration or update existing entry). Dont prompt for a duplicate mail file (skip registration, generate unique mail file name, or replace existing mail file).

Simple administration tasks

347

Figure 278. Advanced Person Registration Options

9. Press Register if you want to register only the selected person, or press Register All if you want to register all persons listed in the registration queue. The dialog box shown in Figure 279 should signal the end of the registration process.

Figure 279. Person Registered Successfully dialog box

16.2.4 Registering a Domino Server


If you want to install an additional Domino Server in an existing domain, you have to register it first (see Figure 280 on page 349). Follow these steps to register a new Domino Server: 1. Start Domino Administrator. 2. Choose the desired registration server. 3. Choose the Configuration tab. 4. Select Server in the left column.

348

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 280. Prepare for Domino Server registration

5. Choose Tools -> Registration -> Server. 6. Enter the password for the current certifier ID. 7. Verify the Registration Server. 8. Select the correct Certifier ID if the current one is not correct. 9. Select the Security Type. 10.Enter the Certificate expiration date (see Figure 281).

Figure 281. Register a Domino Server

11.Press Continue.

Simple administration tasks

349

12.In the Basics section (see Figure 282): Enter the Server Name. Set the password and the password quality. Enter the Domain name. Enter the Administrator name.

Figure 282. Register a Domino Server - Basics section

13.In the Other section (see Figure 283): Enter the server title. Enter the network name. Enter the local administrator. Select whether to store the ID file in the Domino Directory or in the local file system. Storing the ID file in the local file system is more secure, but you have to give the ID file to the user for setup.

Figure 283. Register a Domino Server - Other section

14.If you want to register another server press Next and repeat the process, starting from Step 12 on page 350.
350

Lotus Domino for S/390 R5 Installation, Customization and Administration

15.Press Register. 16.After successfully registering the new Domino Server, a dialog box will be shown (see Figure 284). Press No to end the registration process.

Figure 284. End of registration process

Now you can install another Domino server in the same domain.

16.3 Access the Domino Server with DOMCON


DOMCON (Domino Console) is a program that lets the Domino operator interact with the server using the OS/390 operator console system. It is a free "as is" package that can be downloaded from the Web. For more information how to use DOMCON, refer to 9.1.5, IOS/390 operator console: DOMCON on page 129.

16.4 The Domino Character Console


The Domino Character Console is a new Domino feature. It is only available on UNIX platforms. The TSO OMVS interface is not supported for the Character Console. You have sign in via a Telnet or a rlogin session. For details see 9.1.3, Workstation using rlogin or Telnet on page 128.

16.4.1 Starting the Domino Character Console


The Domino Character Console is started by changing the current directory to the Notes data directory and running /usr/lpp/lotus/bin/cconsole. Figure 32 shows the command line switches.
Table 32. Domino Character Console command line switches

Switch -f -i -l

Result Enter the path and filename of the Notes ID to be used Allow warnings to be ignored, no response required Start console with live display already activated

For example, to start the console and specify the admin.id as the user ID file so that there is no prompt, type in:
/usr/lpp/lotus/bin/cconsole -f /domino1/notesdata/admin.id

Then press Enter. Make sure that the ID file has appropriate file permission. Your Notes user has to have read and write permissions.

Simple administration tasks

351

16.4.2 Character Console Commands


In addition to the usual Domino Server console commands, the Character Console supports a few extra commands (see Figure 33).
Table 33. Domino Character Console commands

Command done live on live off

Result Exit the console and leave server running Enable live display of console activity Disable live display of console activity

16.5 Domino R5 Web Administrator


You can administer your Lotus Domino R5 server using a normal Web browser by accessing the Web Administrators database (webadmin.nsf). Lotus Domino R5 creates this database the first time the HTTP task is started. Domino assigns a unique replica ID to this database; it therefore cannot be replicated between servers. The Web Administrator uses several system databases. If one database is missing, the Web Administrator does not show the associated command.
Note: In an OS/390 environment: To successfully use Web administration, an environment variable called Notes_Directory must be set to the location of the notes data directory in the .profile file of the Domino servers user ID.

Example: Notes_Directory=/domino1/notesdata Perform the following setup steps: 1. Add the names of the Lotus Notes users or group going to administer the server to the access control list (ACL) of webadmin.nsf as Managers with the ServerAdmin, ServerMonitor, DatabaseAdmin, FileRead, and FileModify roles. 2. Add the names of the Lotus Notes users or group going to administer the server to the Administer the server from a browser field in the Security tab of the server document in the Domino Directory. 3. Add the names of the Lotus Notes users going to administer the server to the Run restricted LotusScript agents field in the Agent Manager section of the server document in the Domino Directory. 4. Make sure that each user has an Internet password set in their Person document. 5. You can further refine access to the Web Administration tool by allowing administrators to access only a subset of the available Web Administration commands by modifying the ACL. Figure 285 on page 353 shows an example of what the Web administration pages look like.

352

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 285. Web Administration example

16.5.1 Managing a database ACL with Web Administrator


The Web Administrator lets you add, delete, and modify database ACL entries, change roles, and view the ACL log for all databases on the server. To modify database ACLs, you must: Have at least Editor access in the ACL to use it. Have Manager access in the database ACLs of all the databases you want to modify. By default, Domino system administrators get Manager access in the ACL of the WEBADMIN.NSF when this database is created. If you are not using SSL, set the Maximum Internet name & password access option on the Advanced panel of the Access Control List dialog box to Manager on all the databases you want to modify. This option is set to Manager by default in the WEBADMIN.NSF so you can add more user names to the ACL of the WEBAMDIN.NSF from a browser. Be listed in the Administer the server from a browser field located in the Restrictions section of the HTTP Server Document in the Domino Directory.

Simple administration tasks

353

You can perform the following tasks for Internet or Notes users with the Web Administrator: Add an ACL entry. Remove an ACL entry. Rename an ACL entry. Add, remove, or rename a database role. View the ACL change history. Create a new database on the server based on templates. Create a new copy of the database. Delete a database. Compact a database. Create or update a full-text index of a database. Force manual replication of a database with a remote server.
Note: When entering your user ID in the Web browser authentication window, you have to enter your Common Name, or your fully qualified name, but not your shortname.

For example, our administrative user has been named domino admin. He might authorize as domino admin/ITSO or domino admin, but not as dadmin.

354

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 17. Connecting Domino servers


As part of our testing, we connected two Notes domains and installed additional servers in these domains. Mail routing and replication were enabled efficiently and transparently. The first step in setting up connections between servers and domains is to design the network topology that will be used.

17.1 Choosing a topology for mail routing and replication


We chose a hub and spoke topology. With this method, the hub always initiates the request for replication. Connection documents for replication were created at the hub, and not at the spokes, to ease administration and maintenance. In our scenario we created one hub in each domain with all servers (spokes) in that domain connected to the hub. Each domain hub was then a spoke of the main hub, thus fully connecting all the servers in the network. The topology that we used is shown in Figure 286. Notice that Domino1/ITSO acts both as a domain hub for the ITSO domain and also as the main hub, connecting all domains together.

SC67
OS/390 R 2.6
DFSMS 1.4

SC63
OS/390 R 2.7
DFSMS 1.5

CTC
TCPIPMVS 9.12.14.58
Domino3/ITSO2

TCPIPOE
t en um oc ion D on at cti lic ne ep on for R C

9.12.2.35

Domino4/ITSO2

TCPIPOE

9.12.2.28
HUB

Domino1/ITSO

TOT105
Co

Domino2/ITSO

Windows NT
nn ec t M ionD ail o ro cu ut m ing en t

4.0
9.12.2.164
fo r
TOT105/ITSO2

TR

Notes clients

Notes clients

Notes clients

Figure 286. Our test environment

Copyright IBM Corp. 1999

355

17.2 Mail routing


This section describes how to set up mail routing between servers in different domains.

17.2.1 Introduction to mail routing


For mail to be routed between two servers in different domains, a Connection document has to exist in the Domino Directory of both servers. No Connection document for mail routing is required if the servers are in the same Notes named network and in the same domain. For database replication, a connection document on one of the two servers would suffice. The single Connection document for mail routing can also be used for replication, but it is recommended that a separate Connection document be set up for database replication. Separate Connection documents for mail routing and replication give the system flexibility in a production environment.

17.2.2 Setting up mail routing Connection documents


With Domino R5, you need only the Domino Administrator to accomplish administration tasks. For more information how to install the Domino Administrator see 16.1, Installing the Lotus Domino Administrator client on page 325. Initially there will be no Connection documents for routing mail to other domains. Any attempt to route mail across to another domain would result in error messages on the server. In this section we describe how to set up a mail routing Connection document by guiding you through how we set up the connection between the domain hub tot105/ITSO2 and the main hub domino1/ITSO. The procedure for setting up the mail routing Connection document between the two domains is described here. For information about registering another server, refer to Chapter 16, Simple administration tasks on page 325.

356

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 287. New server connection for mail routing

We decided to create one Connection document for mail routing and one for replication. To use this Connection document solely for mail routing, select Mail Routing in the Select Keywords screen that is displayed when you click the pull-down of the Tasks field in the Routing and Replication section of the screen.

Figure 288. Replication/routing tab

Connecting Domino servers

357

Should you wish to disable the Connection document, select Disabled from the pull-down of the Schedule field in the Scheduled Connection section of the screen. The Basics section of the screen (as the name suggests) is trivial. Just make sure that the Source server name is fully qualified with the Source domain name. 6. Save the Connection document (press the Esc key on the keyboard and click Yes in the confirmation window to save the changes). On returning to the Workspace, make sure in the Configuration Tab using the Domino Administrator - the View Server -> Connections is selected to see the Connection document in the Domino Directory. Figure 289 shows the Connection document for domino1/ITSO to tot105/ITSO2 in the Domino Directory (Public Name and Address Book) of the ITSO domain.

Figure 289. Lotus Notes - Connection document in the Domino Directory

The second server (the domain hub) will also need a Connection document to the first server (the main hub). Without it, users on that domain would not be able to send mail or reply to users on other domains via the main hub. The Connection document for the second server is shown in Figure 290 on page 359; we have included two screens in the figure to display the Basics tab and the Replication/Routing tab.

358

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 290. Mail routing Connection document for second server

Now that the Connection documents are in place, we need to authorize the two servers to communicate with each other. This is done by using cross-certificates.

17.2.3 Cross-certification and authentication


Having set up the Connection document, the next step is to cross-certify the Server ID on the servers in the two Notes domains. Without this crosscertification, the Domino servers will not route any mail. The steps for cross-certifying certificates are as follows: 1. Server A creates a Safe Copy of its server ID and makes this file available to the administrator of server B in the other domain. 2. Admin B cross-certifies the server ID for server A.

Connecting Domino servers

359

3. Server B creates a Safe Copy of its Server ID and makes this file available to the administrator of server A in the other domain. 4. Admin A cross-certifies the Certifier ID for server B.
17.2.3.1 Creating a Safe Copy of the Server ID This section outlines how to create a Safe Copy of the Server ID file, with the assumption that there is no intermediary gateway in place for distributing the ID file by mail.

1. In Domino Administrator client choose the Tools - Certification tab to display several options as shown in Figure 289 on page 358. 2. Select the menu Configuration - Certification - ID Properties to display the Choose ID File to Examine dialog box as shown in Figure 291.

Figure 291. Choose ID file to examine

3. Select the Server ID file for this server (in our case, server.id) and click OK . 4. If one exists, enter the password for the server on the Enter Password dialog box and click OK . 5. On the User ID - <server_name> dialog box (Figure 292 on page 361), select the More Options icon, and click the Create Safe Copy... button.

360

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 292. User ID management screen

6. On the Enter Safe Copy ID File Name screen that is presented (Figure 293), either accept the default, or specify the name of the safe copy file in the File Name field.

Figure 293. Name of the Safe Copy ID file

7. Click OK . 8. Give the safe copy's file name and location to the administrator of the server that you wish to cross-certify with.
17.2.3.2 Cross-certifying the Safe Copy of the server ID This section describes how to cross-certify a Safe Copy of an ID file.

Connecting Domino servers

361

1. From the Domino Administrator, select Tools-> Certification -> Cross Certify. You are now in the administration control panel. Click the Certifiers icon and select Cross Certify ID File to display the Choose Certifier ID screen (Figure 294).

Figure 294. Choose Certifier ID screen

2. Choose the server's own Certifier ID file, and click OK. 3. Enter the password for the ID file, and click OK . 4. In the Choose ID to be Cross-Certified dialog box (Figure 295 on page 363), select the other server's Safe Copy ID file (in this scenario, safe54.id), and click OK.

362

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 295. Choose ID to Cross-Certify screen

5. In the Cross Certify ID dialog box (Figure 296), click Cross Certify.

Figure 296. Cross Certify

6. Enter the password for the ID file (if required), and click OK . 7. Click No to exit the screen prompting for more ID files to be cross-certified.

Connecting Domino servers

363

17.3 Replication
This section discusses what needs to be set up for replication of databases to occur between servers and how to do the setup and customization for replication.

17.3.1 Introduction to replication


Replication is Notes' way of ensuring that all users on a global network can have access to the latest version of a database. If the database is updated on one server, then that update is made available to all connected servers. The Notes administrator can control how frequently databases (or parts of databases) are replicated.

17.3.2 Creating the Connection document for replication


We will use a different Connection document for replication. To do this, follow these steps: 1. Click the Domino Directory to select it, and then select Create->Server->Connection to display the Lotus Notes - New Server Connection screen (Figure 297 on page 365).

364

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 297. Lotus Domino - new LAN connection (for replication)

2. Complete the Basics section of the document first, making sure that you specify the Source server field as the fully qualified name of the server that will act as the hub. In our scenario, this is the domino1/ITSO server. 3. In the Routing and Replication section, select Replication only from the pull-down on the Tasks field, while keeping the Replication Type as Pull Push. (We want the hub to pull changes from the spokes and push changes to the spokes). 4. The Scheduled Connection section of the document is where you specify when and how often replication should take place. 5. When you have filled in all the values, press Esc on your keyboard, and answer Yes to save the document and return to your Domino Administrator.

Connecting Domino servers

365

17.3.3 Required authorizations in Server document


The next step is for the spoke server to authorize the administrator on the hub server to create replica databases. This is done by using the Create replica databases field in the spoke Server document. To ease administration, it is recommended that a Notes Group be set up which lists all the resources allowed to create replicas on the server as follows: 1. In the Domino Administrator, select the Domino Directory and then select the People & Groups tab to display available Groups. Select Add Group, and the New Group screen will display as shown in Figure 298. 2. Complete the fields on this screen, making sure that you specify the name of the Replicator correctly, and save the document in the Public Address Book.

Figure 298. Lotus Domino - new Group

Once the Group has been set up, we can update the Server document to authorize that Group to create replicas: Select the Domino Administrator. Then select the Configuration tab and choose the view All Server Documents. 3. Select the spoke server that will be replicated to and click Edit Server. 4. Click > Security. 5. Tab down to the Create replica databases field, and type in the Notes Group name that you created for this use. 6. Save the document, and return to your workspace.

366

Lotus Domino for S/390 R5 Installation, Customization and Administration

17.3.4 Creating the replica on the Spoke server


Replication only works when two servers have a database in common. For this reason, before scheduled replication can work, the hub server's administrator must create a replica of the database on the spoke. If you wish to define replication settings for the database, such as specifying the documents or database features the replica can receive, then you must define those settings first. Refer to the Lotus Notes Administrator's Guide for details on what the settings are and how to define them. Once the replication settings are in place, it is then possible to create the replica. 1. By using the Domino Administrator - choose File - Replication - New Replica... Select to display the New Replica <database_title> screen, as shown in Figure 299.

Figure 299. Creating a new replica of a database

2. Type in the name of the spoke server (the server you want to replicate to) in the Server field, or select it, if available, from the pull-down. 3. Enter the title of the replica in the Title field, and give the replica a name in the File name field. The name you specify in this field does not have to be the same as the name of the file on the source server. Notes recognizes replicas using the Replica ID. Refer to 17.3.5, Database Replica IDs on page 368 for more information. 4. If you want to define the replication settings, click Replication Settings. 5. If you want to encrypt the local copy of the database, click the Encryption... key, and specify how you want the database to be encrypted. 6. If you want the database to grow beyond the 1GB default limit, click the Size Limit... key, and select a new value. 7. Select Immediately to create the replica on the destination server while also replicating the documents that the database holds. Or, if you want to create the replica now, and wait for the normal replication process to replicate the documents, then select the Next scheduled replication radio button. 8. Select Copy Access Control List to copy the list from the source server to the destination server. 9. Click OK . 10.Enter your password if prompted, and click OK .

Connecting Domino servers

367

The database will then be replicated to the Spoke server. If you get a message saying that you are not authorized to update the server, restart the Spoke server and then try creating the new replica again because you changed the server document in the Domino Directory. The prerequisites for replication are now in place: A connection document has been created on one of the servers. Authorization has been given for creating replicas. The new replica has been created. The database(s) will now be replicated according to the schedule in the Connection document.

17.3.5 Database Replica IDs


All replicas of a database have the same Replica ID. This ID distinguishes a copy from a replica. When Notes replicates, it checks for common databases using this Replica ID. To check a Replica ID, click once on the icon for the database on the Domino Administrator Files Tab, select the database to open then choose File Database - Properties... Or press ALT + Enter, and then click the Information tab (second tab) to display the Replica ID for the database (Figure 300).

Figure 300. Replica ID

17.3.6 Access Control Lists (ACLs) and replication


The determining factor on exactly what changes a replica receives is the Access Control Level given to the source server on the server where the replica database exists. For example, the replica can only receive changes made to the design and formulas of the database if the source server has at least Designer access to the database.

368

Lotus Domino for S/390 R5 Installation, Customization and Administration

Table 34 illustrates what is replicated according to the access level of the source server to the database replica.
Table 34. Changes that will replicate

Access level

Access Control List (ACL)


Yes

Design & Formulae


Yes Yes

Edited documents
Yes Yes Yes

New documents
Yes Yes Yes

Manager Designer Editor Reader Depositor No Access

Connecting Domino servers

369

370

Lotus Domino for S/390 R5 Installation, Customization and Administration

Chapter 18. Security


In this chapter we discuss the protection features that Domino provides. For OS/390 security protection issues, refer to 4.5.1, OS/390 UNIX security on page 64.

18.1 Domino Server protection


Many of the security features are unchanged in R5. Details are provided regarding changes that have been implemented. After the installation of a Domino Server, you may need to review the security policy. It is up to the Notes administrator to ensure that all necessary precautions are undertaken to strengthen server security before making access available.
Recommendation

To ensure that all security mechanisms are covered, disable all access and then re-enable only the specific areas of access that are known to be required. Having to remember to enable a feature is much less of a risk than having to remember to disable one as security may already have been breached.

18.1.1 Access during Domino Server setup


The http httpsetup task is run to configure the server as part of the installation process. Once the configuration forms have been completed in the setupweb.nsf database, with details such as domain, certifier name, server name and administrator name, they are submitted to the server for the setup task to process.
Important

The field details from the form are sent in clear text format to the server, so ID names and password details are vulnerable during this time. One last concern is that the administrator may use FTP to retrieve copies of newly created certifier, server or administrator ID files. Using an unsecured FTP session means that the contents of the ID files are vulnerable to network sniffers during transit between the server and the receiving machine.

18.1.2 Domino Server access and network connectivity


The following sections of the Security tab of the server document should be reviewed and configured appropriately to limit initial access to the server via Notes or web browser clients or the execution of agents on the server: 1. Security Settings 2. Server Access 3. Web Server Access

Web Server Access is a new configuration setting available on the server document. It contains a field named Web server authentication that allows the

Copyright IBM Corp. 1999

371

administrator to choose what type of names will be accepted during name and password authentication. Figure 301 on page 373 shows this field near the top right of the form beside the Security Settings section. Table 35 describes the options and their meanings:
Table 35. Web server authentication definitions

Settings More name security variations with lower

Results User can enter any of the following and Domino will try to match in the Domino Directory: Last name First Name Short name Alternate name Common name Full hierarchical name Alias names Soundex number Users can enter only one of the following names: Common name Full hierarchical name Alias name Alternate name

Fewer name variations with higher security

By restricting the number of available entries, a hacker is less likely to find a match by guessing a user name. 4. Passthru Use. 5. Agent Restrictions 6. IIOP Restrictions The inclusion of support for CORBA-based application communication between applets and the Web server requires a level of security. This is implemented in a similar fashion to the familiar agent restrictions from previous releases. The options Run restricted Java/Javascript and Run unrestricted Java/Javascript can be found in the IIOP Restrictions section of the Security tab on the server document; see Figure 301.

372

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 301. Restricting server access and execution of Java/Javascript applets

Note: These fields should be populated with appropriate groups to restrict access and provide easy administration.

To restrict access via Internet standard protocols, the following sections of the Ports-Internet Ports tab should be considered: HTTP (Web) SSL It is now possible to specify the SSL ciphers that the server will accept when negotiating an SSL connection with a client. These can be found in the SSL ciphers field of the SSL Security section of the Ports-Internet Ports-Web tab of the server document; see Figure 302.

Security

373

Figure 302. Setting available SSL cipher types

LDAP (Directory) Domino R5 allows authenticated LDAP users to add, delete or modify entries in the Domino Directory provided they have at least author access and are members of the UserCreator and UserModifier roles. However, at this time no popular commercially available LDAP clients are capable of supporting this feature. NNTP (News) IMAP (Mail) POP (Mail) SMTP Inbound/Outbound (Mail) IIOP (Inter-Application Object Communication) The IIOP ports for normal and SSL connectivity can be found on the Ports-Internet Ports-IIOP tab of the server document; see Figure 303.

374

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 303. Setting TCP/IP port information for IIOP communication

18.1.3 Database access controls


Once the actual connections to the server have been restricted, access to the data in the databases and applications on the server must be considered. In R5, all of the familiar database security measures remain unchanged. First of all, the contents of the server should not be visible. To restrict viewing you should disable the Allow HTTP clients to browse databases option on the Internet Protocols-HTTP tab of the server document. The following areas of database access control must then be reviewed and set for all databases and templates on the server: An Anonymous User entry in the ACL with appropriate access level A default ACL access level of No Access Appropriate use of Read public documents and Write public documents in the ACL An appropriate Maximum Internet Name & Password access level As discussed previously in Chapter 10, Lotus Domino R5 and the Internet on page 163, R5 introduces a mechanism for protecting native HTML files that may

Security

375

be served by the HTTP Web server task to browser clients. The user or group entries used in a protection document must belong to the Domino Directory and do not have any correlation with RACF file system security settings. Provided that the RACF user account under which the server executes has appropriate access to the files and directories involved, then the Domino Server exerts control over the remote usage of the files.

18.1.4 Session-based Web client authentication


With Domino R5, Web client access can be session-based, like Notes client sessions, allowing the server to track session details. This allows the server to provide additional functionality not normally available with standard user name and password authentication: Customized HTML login page Default logout time period expiration Programmed logout via URL Maximum Web client user sessions

The implementation of the session tracking uses cookies, so this type of access can only be supported via clients that support the use of cookies. The accepting of cookies must be active.
Note: Servers accessed via round-robin DNS cannot support the use of session-based Web authentication as they cannot maintain the session details in memory.

To enable session-based authentication for browser clients it is necessary to edit the Server document and switch to the Internet Protocols-Domino Web Engine tab and in the HTTP Sessions section set the Session authentication field to Enabled; see Figure 304 on page 377. The Idle session timeout and Maximum active sessions are also configured in this section.

376

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 304. Enabling Web client session-based authentication

18.1.5 Access via the Internet Cluster Manager


One of the main changes in R5 is the support of clustered servers for Web client access, using the Internet Cluster Manager. The ICM supports both standard and SSL connections, and details of the configuration can be found in Chapter 11, Domino Enterprise Server on page 187. It is important to note that the ICM itself accepts only anonymous unauthenticated requests from browser clients and then redirects those requests to one of the available servers. At this point, the target server security settings govern the extent of the access allowed to the browser client and the nature of the authentication options available.
Note: Since the ICM does not authenticate requests, protecting it through controlled access must be achieved with the use of a firewall, especially if it is used to provide access to the Internet.

18.2 Secure Sockets Layer (SSL)


Much of the SSL support in R5 is the same as that for the Domino R4.6 Server. This section will describe only changes or additional functions.

Security

377

18.2.1 SSL and the Internet Cluster Manager


As mentioned previously, the ICM can handle requests for SSL connections to the clustered servers that it serves. Once a client has connected to a server in the cluster subsequent requests will be handled by that server unless the requested information is not available or the server fails. In this case the ICM will redirect requests to another server in the cluster that can provide the necessary resources. If the user had not previously authenticated on the new server, then they will be required to do so. However, if the connection was over SSL and both client and server support SSLv3, then establishing a new SSL connection is automatic.

18.3 Restricting SMTP server access


More and more companies rely on working mail systems, but not every company is aware of the threats caused by the connection of their mail system to the Internet. Unsolicited Commercial Email (UCE), widely known as "spam" mail, could cause a mail server to slow down or even crash. There are two types of spam mail. The first type uses your mail server to send mail to many other mail users, normally not registered at your server. This type could slow down your mail server. If you are paying your Internet Service Provider (ISP) by megabytes of data transferred, this could cost you a lot of money. You should also be aware that the receiver of the spam mail could make your company responsible for the damage caused to their mailing system. This type is also known as mail relaying.
Note: If you want to restrict the mail server access to certain IP address ranges, you have to enclose the IP range in square brackets. For example if you want to enable all IP addresses in the range 9.3.240.0 to 9.3.240.255, you have to enter [9.3.240.*].

The second type is actually receiving these large volumes of mail. A large amount of spam mail could cause your mail system to run out of disk space and therefore prevent it from delivering any other mail. As mentioned, this type of mail is referred as spam mail in this redbook.

18.3.1 Mail relaying


The Domino mailing system has several options you can use to prevent others from using your mail server for mail relaying. But you have to be very careful using these restrictions because you might disable some of your own servers or clients. Figure 305 on page 379 shows how you can restrict sending mail to machines within a DNS domain.

378

Lotus Domino for S/390 R5 Installation, Customization and Administration

Figure 305. Mail relaying - outbound control

18.3.2 Mail spamming


If your company is receiving lots of unwanted mail from a certain mail domain, you can disable this domain. But be aware that you might block mail you want to receive, too. To deny mail from a certain mail domain, follow these steps: 1. Start Domino Administrator. 2. Select the desired server. 3. Click Configuration . 4. Select Messaging > Configuration. 5. Select your mail server. 6. Click Edit Configuration to open the Server document. 7. Choose Router/SMTP > Restrictions and Controls > SMTP Inbound Controls. 8. Enter the SMTP domain you want to prevent sending mail to your server in the field Deny connections from the following SMTP Internet hostnames/IP addresses. Figure 306 shows how to prevent hosts in the DNS domain ehningen.ibm.com from sending mail to Domino1/Itso.

Security

379

Figure 306. SMTP inbound control - deny SMTP domain

18.3.2.1 Is my SMTP server vulnerable? To control your anti-spam settings, enter the following URL:
http://maps.vix.com/tsi/ar-test.html

Enter your hostname and press Enter. You will get this result:
Initiating Third-Party Mail Relay Test ... Target Host = ebfdus1.ebf.de -----------------------------------------------------------Looking up ebfdus1.ebf.de ... Launching rlytest ... Connecting to 193.96.156.252 ... <<< 220 ebfdus1.ebf.de ESMTP Service (Lotus Domino Build v50.a_1) ready at Thu, 17 Jun 1999 15:57:58 +0200 >>> HELO maps1.pa.vix.com <<< 250 ebfdus1.ebf.de Hello maps1.pa.vix.com ([204.152.184.35]), pleased to meet >>> MAIL FROM:<nobody@ebfdus1.ebf.de> <<< 250 nobody@ebfdus1.ebf.de... Sender OK >>> RCPT TO:<nobody@maps1.pa.vix.com> <<< 554 Relay rejected for policy reasons. rlytest: relay rejected - final response code 554 -----------------------------------------------------------Test complete.

380

Lotus Domino for S/390 R5 Installation, Customization and Administration

18.4 Domino Server Character Console


The Domino Server is usually started as a background process on the OS/390 platform, which means that the standard server console window is not visible. As mentioned in 9.4.3, Stopping the server using the character console on page 143, R5 provides a local console access program so that an administrator working locally or from a remote terminal can enter console commands. Making a console available in this way introduces some security issues that must be considered. When the cconsole program is started, the administrator must specify which Notes user ID file to use and must then enter the password for that ID.
Note: The ID used must be listed as an administrator for the server, explicitly or as a member of a group, in the Administrators field of the server document and it must have a password associated with it or cconsole will not run. It must also be available in the UNIX HFS (with read authority). To ensure security of the ID, it should have a strong password with a minimum length of eight characters.
Recommendations

Consider registering a user ID specifically for this purpose, for example CConsole Admin, that does not have access to databases. Should the ID file be copied from the file system and the password compromised, it will be of limited use. If a specific user ID is not created, then consider creating a separate administration group, for example CConsoleAdmin, to contain user IDs allowed to use the UNIX remote console. Then add this group name to the field on the server document, in addition to the existing entries. Relevant users can then be specified as being able to use remote console, but do not obtain the same access privileges to databases that existing administrators may have. Use the Domino Server command Set Secure <password> to increase security of the Domino Server console, especially if remote console access is allowed. The console program also checks to see if the Domino Server is active on the same physical machine. If it is not, the console program shuts down. If the server fails, then the console may not exit automatically. In this case, the administrator must type done and press Enter to close it manually.
Important

The password entered for the user ID will be transmitted to the server over the network in clear text format. The risks can be reduced by using the available tools appropriately.

Security

381

Notes

Only run the character console program locally on the Domino Server. Use the Domino Administration client functions for remote access to the console. For more information about Lotus Domino security, refer to the following redbooks: Lotus Notes and Domino R5.0 Security Infrastructure Revealed , SG24-5341 The Domino Defense: Security in Lotus Notes and the Internet, SG24-4848

382

Lotus Domino for S/390 R5 Installation, Customization and Administration

Part 5. Appendixes

Copyright IBM Corp. 1999

383

384

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix A. Troubleshooting and hints and tips


In this appendix we describe the problems we encountered while installing and using Domino R5 for this redbook. We list the causes and their solutions.
Note: We have found on numerous occasions that the prime cause of problems with the Domino Server is either a) incorrect settings in BPXPRMxx or b) running Domino on a system that did not have all recommended maintenance applied. Before initiating any other problem determination, review these areas. You may find that you are running with incorrect BPXPRMxx settings, or you may not have all of the latest recommended maintenance applied.

A.1 JCL Files Not Uploaded Properly


Problem: On a couple of occasions, after uploading the JCL files from the workstation to MVS data sets, they looked as shown in Figure 307.

//LOTUSA JOB ......... .//********************************************************************* .//* .//* IF THIS SAMPLE IS MODIFIED AND USED, IT WILL DO THE FOLLOWING .//* -ALLOCATE LOTUS DOMINO DATA SETS .//* -MAKE HFS DIRECTORIES .//* -TEMPORARILY MOUNT THE ALLOCATED HFS DATA SETS TO THE HFS .//* DIRECTORIES (BPXPRMxx NEEDS TO BE UPDATED FOR A PERMANENT .//* MOUNT) .//* .//* FOLLOW THE DIRECTIONS BELOW TO MAKE THE APPROPRIATE MODIFICATIONS .//* .//* .//* #1# CHANGE PROC PARM DSNPREF TO NOTES HIGH LEVEL DATASET QUALIF IER .//* DEFAULT: NOTES
Figure 307. Invalid JCL file format after FTP

Cause: This was caused by an incorrect format of the files on the workstation. An extra character was being added to each line. Solution: We preallocated the JCL data set userid.NOTES500.JCL with FB LRECL 81 and 20 directory blocks. We then used FTP to upload the files as follows:

FTP binary put alocprod.b11 //notes500.jcl(alocprod) put mdfybpxp.b11 //notes500.jcl(mdfybpxp) put putinlpa.b11 //notes500.jcl(putinlpa) put s390b101.tar //notes500.tar

A.2 Errors in running ALOCPROD


Problem: We got the following errors when we ran the ALOCPROD job:

Copyright IBM Corp. 1999

385

MKDIR '/usr/lpp/lotus' MODE(7,5,5) RETURN CODE 00000075, REASON CODE 05520038. AN ERROR OCCURRED DURING TH READY MOUNT FILESYSTEM('OMVS.DOMINO.ITSO390B.BETA101.PROD.HFS') TYPE(HFS) MODE RETURN CODE 00000079, REASON CODE 055B005C. THE MOUNT FAILED FOR FILE S READY MKDIR '/notesdata' MODE(7,5,5) RETURN CODE 00000075, REASON CODE 05520038. AN ERROR OCCURRED DURING TH READY MOUNT FILESYSTEM('OMVS.DOMINO.ITSO390B.DATA.HFS') TYPE(HFS) MODE(RDWR) M RETURN CODE 00000079, REASON CODE 055B005C. THE MOUNT FAILED FOR FILE S READY MKDIR '/notesdata/mail' MODE(7,5,5) RETURN CODE 00000075, REASON CODE 05520038. AN ERROR OCCURRED DURING TH READY MOUNT FILESYSTEM('OMVS.DOMINO.ITSO390B.MAIL.HFS') TYPE(HFS) MODE(RDWR) M RETURN CODE 00000079, REASON CODE 055B005C. THE MOUNT FAILED FOR FILE S READY END

Cause: This happened because we ran the job on the wrong system in the sysplex. The directories already existed and HFS data sets were already mounted to them.

Solution: We reran the job on the correct system using the /*JOBPARM card.

A.3 Error when starting the server - 1


Problem: We got the following messages when we tried to start the Domino Server:

# server

CEE3204S The system detected a protection exception. From entry point OSLockReadSem at compile unit offset +00000064 at address 08D95EA4.

Cause: The server had failed to shut down correctly. We had cancelled the MVS address spaces for the server, but not all of the shared memory and semaphores had been cleaned up. Solution: We ran nsd -kill and then started the server again. See 9.6, What to do if the server does not start or stop on page 155.

A.4 Error when starting the server - 2


:Problem: When we tried to start the server, we were returned to the UNIX shell prompt and the server did not start.

386

Lotus Domino for S/390 R5 Installation, Customization and Administration

# server #

Cause: The cause was not obvious as there were no error messages. However, after reviewing our BPXPRMxx settings, we found an error. Solution: Our value for IPCSHMMPAGES in BPXPRMxx was set too low. This value specifies the maximum number of pages for shared memory segments. The default value is only 256 4K pages, which is only 1 MB of shared memory. Domino uses shared memory extensively. We recommend that you set the value of IPCSHMMPAGES to the maximum value (25,600). If the IPCSHMMPAGES is less than the value of Notes_SHARED_DPOOLSIZE, the Domino Server will not start.

A.5 Error when stopping the server


Problem: We got the following messages when we shut down the Domino Server:

> quit 06/17/99 01:38:41 PM Starting Server shutdown Fatal Error signal = 0x00000004 PID/Server-TID/Kernel-TID = 25000013/13010004/ 08b395e0 Freezing all server threads ...

Thread=[620757011:00005-318832644] PANIC: fatal_error signal handler PANIC: decimal errno=0 / hexadecimal errno2=0 CEE3250C The system or user abend U 034 R=00000000 was issued. From compile unit ./ospanic.c at entry point Panic at compile unit offset +000708A6 at address 08E1C06E.

Cause: Shutting down the server while not having all the recommended maintenance applied. Solution: Run nsd -kill to clean up the environment. Apply all recommended maintenance before restarting the server.

A.6 Running the server without notes.ini


Problem: If you try and run the server when notes.ini is unavailable, you will see the following message:

# server Could not find notes.ini in Current Directory or PATH #

Troubleshooting and hints and tips

387

Cause: This message indicates that your notes.ini file is missing. This is either because you are attempting to start the server from a directory where notes.ini does not reside, or you do not have the valid /notesdata directory in your PATH environment variable. Solution: Start the server from the correct directory (i.e. the servers notes data directory).

A.7 mail.box missing on the server


Problem: When trying to send mail from a user in one domain to a user in another domain, the user got a message indicating that the server did not have access to the mail.box file. Cause: There are several causes for this problem. Check the NOTES LOG database, which will give you an indication what is causing this problem. In case your mail.box file is corrupted, you have to stop and start the server. The router task should allocate a new mail.box file.

Another reason might be that the Domain field in the Server document in the Public Address Book is not filled in. This can be caused by not entering a value during server configuration. Refer to the Lotus Notes Administrator's Guide for further advice.
Solution: Update the Domain field in the server with the domain name. Stop and restart the server. Now the router should create a mail.box file and users should be able to transfer mail.

A.8 The remote server is not a known TCP/IP host


Problem: We were not able to access the server from any client. Cause: We set the Domino Servers TCP/IP host name to be different from the OS/390 servers TCP/IP host name. Solution: Ensure youve updated your Domain Name Server (DNS) with an entry for the Domino Server. If this administrative task takes time to complete at your installation, you could add a connection document in your Name and Address Book, using the IP address of the OS/390 server as the connection address. Alternate Solution: Install a new client and add a pointer to the server using a location document in the clients directory.

A.9 Error message server: FSUM7351 Not Found


Cause: Most of the time this message indicates that the system could not find the server module. Solution: Check PATH and LIBPATH using the echo command to verify that they are set correctly. If not, set them again. To prevent this problem, you could include these commands to set these variables in an UNIX System Services .profile file.
ECHO $PATH ECHO $LIBPATH

388

Lotus Domino for S/390 R5 Installation, Customization and Administration

A.10 Mount error return code 0000009C, reason code 0507014D


Problem: Received return code 9C, a dynamic allocation error. Cause: The user ID from which the mount command was issued had an incorrect default path defined in RACF. The return code is for the allocation of the user's default directory, not for the data set that is being mounted. Solution: Issue the RACF command ALU userid OMVS(HOME('/u')) to set the user's home directory back to a directory that exists.

A.11 Gaining access to the USER.ID file after configuration


Problem: During the configuration process, when creating a new server in a new domain, the cert.id and server.id files are stored in the notes data directory. The new administrator ID file, however, is stored in the administrators Person document in the NAB. In order to detach this ID file from the Person document, the installer must start the Domino Server HTTP task (which listens on port 80). In most production environments, port 80 is already being listened on (and thus reserved) by an existing Web server. Resolution: You must schedule an outage of your production Web server. Once it has shut down, you can start the Domino R5 HTTP task and detach the ID file. You can then shutdown the HTTP task and restart your production Web server.

If an outage to your Web server that listens on port 80 is unacceptable (and for many customers this will be the case), you can FTP a copy of the NAB to your desktop. You can then open the local copy of the NAB and detach the ID file.

A.12 MAXQUEUEDSIGS
Problem: The MAXQUEUEDSIGS parameter is not documented in current (as of OS/390 V2R7) publications. Resolution: The MAXQUEUEDSIGS parameter will be documented in the appropriate OS/390 V2R8 publications. The maximum value for MAXQUEUEDSIGS is 100,000. You should set the value to 100,00 for use with Domino. You can make this change through the use of the SETOMVS MAXQUEUEDSIGS= console command. Note that to make this setting permanent across IPLs you need to update BPXPRMxx.

A.13 Not enough disk space for installation


Problem: When you run the Domino install program you select directory paths for both the program files (usually /usr/lpp/lotus ) and the notes data files (usually /notesdata or some derivative). If you attempt to install the files into a filesystem or filesystems that do not have enough free space, you will see output like the following when attempting the install.

Troubleshooting and hints and tips

389

Press the Tab key to perform the installation... =============================================================================== Domino Server Installation =============================================================================== Installation settings: Installation type Program directory Data directory UNIX user name UNIX group name : Domino Enterprise Server : : : : /usr/lpp/lotus /notesdata domino4 oedomino

Validating... Error validating installation settings: There is not enough disk space for the program directory at /usr/lpp/lotus 104463k is required, and only 47712k would be available. There is not enough disk space for the data directory at /notesdata 212134k is required, and only 60460k would be available. The installation cannot proceed for the local host.

Resolution: Rerun the install program after you have created adequately sized file systems. The error message (see above) will tell you how much space you require for the installation to succeed.

A.14 Could not backup notes.ini


Problem: When starting the server for the first time you may encounter the following message:

DOMSEW @ SC63:/domsew/notesdata> server Could not backup notes.ini

Resolution: The problem is not obvious. If you list filesystems using a df -Pk command, you will not see a space problem. When we encountered this problem, it transpired that the Domino Server had the correct userid (and UID) but was connected to the wrong group. We had previously issued a chown -Rf DOMSEW:OEDOMINO /domsew/notesdata command. However, the RACF userid DOMSEW was actually connected to the group SYS1. After connecting the Domino Server RACF userid to the correct group, we could successfully start the server.

A.15 Server panic errors


Problem: Various server panic errors. Resolution: Apply all corrective service as documented in www.s390.ibm.com/products/domino/dom390.html, and set OS/390 BPXPRMxx parameter values as recommended in installation documentation. We also 390
Lotus Domino for S/390 R5 Installation, Customization and Administration

recommend that you use the PTF checker tool, available on the Internet at:
www.s390.ibm.com/products/domino/

A.16 IOSTREAM not found


Message: CEE3501S The module IOSTREAM was not found More Details: Occurs when accessing server from the Web. Resolution: Include OS/390 C/C++ IBM Open Class Library SCLBDLL in the program search order (for example, in the LINKLIST).

A.17 Java Virtual Machine not found


Messages:
The JVM runtime library could not be found Java Virtual Machine failed to start

More Details: Occurs during server startup. Resolution: Install the recommended level of the OS/390 Java Development Toolkit if you have not already done so. Then include the appropriate path settings in the UNIX Services environment variables (see: 6.6, Verifying path statements on page 99). Note: These messages can be ignored if Java agent support is not required. However, you will most likely need this support.

A.18 Installation failed for local host


Messages:
An unexpected error occurred during post-install processing: Died at (eval 29) line 272. /usr/lpp/lotus/os390/tools/lib/NIC.pm line 768 The installation failed for the local host.

More Details: Target program directory is /usr/lpp/lotus, and target data directory is /domdevl/notesdata. Resolution: This seems to be a problem in the installation script. Install the product in default directories and move it later. Or change the corresponding shell script to match your desired directories.

A.19 Other recommendations


Backup, Backup, Backup Ensure that a complete backup is taken of any server prior to any upgrade. To reverse a software upgrade by restoring from a backup will be significantly easier and less time-consuming than having to re-install and configure the original software.

Troubleshooting and hints and tips

391

Plan the order of your Domino upgrade The recommended order in which to upgrade from Domino 4.6 to Domino R5 is:
Public Name and Address Book (NAB) Hub servers Mail and application servers Other servers Client software Application design

HTTP Web setup It is a good idea to make a backup copy of the file called websetup.nsf (which is located in your servers data directory) after you have finished installing the software from the CD. If there is no backup copy of this file, and the HTTP setup fails for whatever reason, the only course of action is to delete the installation and reinstall. If there is a backup copy of this file, then simply copy the backup over the original file and run the http setup again. The Domino Directory In our testing environment we found it necessary to manually compact the Domino Directory (names.nsf) twice in order to make use of the ODS database format. This was true for upgrades as well as new installations. To compact the Domino Directory, make sure the server has been stopped, change to the Domino data directory (/server1), and use the command compact names.nsf. Do this twice and restart the server. Remember, you must run this command as the Notes user. Do not run the compact command as the root user. Database design Make sure that the design elements of a database that are not to be changed by a design refresh or design replace have the property "Do not allow design refresh/replace to modify" enabled. Transaction logs Since the transaction logs are critical to data integrity and maximum performance, it is strongly recommended that the disk used to contain the Transaction Log Extent be mirrored and if possible connected to a separate disk controller than that used to service the Domino data directory. Partitioned servers When installing partitioned servers we recommend manually specifying the data directories since the file system mount points will already have been created and may not match the default names generated by the install program. Consider associating the name of the server with the mount point of the file system for clarity and ease of administration. Partition number The file used to identify the partition number for the server, .sgf.notespartition, is no longer used in R5. Instead the partition name is based upon the data directory name. For example, a data directory name of /domino1 generates a partition identifier of domino1.

392

Lotus Domino for S/390 R5 Installation, Customization and Administration

A.20 Hints and tips for Lotus Domino and Lotus Notes
A.20.1 Who can I call to find my local reseller and licensing information?

You can call Lotus at 1-800-782-7876 in the United States.


A.20.2 Can you keep multiple versions of Lotus Notes on the same system?

Yes. On an install of a new version, you should do the following: Put the \Notes directory in your PATH. For major revisions (3.x -> 4.x -> 5.x, etc.), keep a separate copy of the \Notes\Data directory because the Notes internal database format changes between each version; new major versions will upgrade old database versions to the latest, which can then no longer be read by the old versions. You can point to the appropriate data directory by editing your notes.ini file; you will only need one per major revision (NoteData.3, NoteData.4, etc.). After the install, move the notes.ini file into the \Notes directory. Before installing a new version, rename the directory of the old version to something else (e.g., \Notes to \Notes.463). Install into the same non-renamed directory (e.g., \Notes), but before doing this, copy your desktop.dsk file into this directory so it can be upgraded if needed. To use a specific version: 1. Make sure you are not running anything from \Notes (e.g., Notes Single Logon (which is nsl.exe), the mail check in R5, the Notes client, etc.). 2. Rename the current \Notes directory to whatever version it was (e.g., \Notes to \Notes.463). 3. Rename the directory with the version you want to \Notes (e.g., \Notes.50 to \Notes). 4. Start Notes. You have to keep the same directory structure because in later versions of Notes, there is information in the registry related to OLE automation. If you use separate directories for each version, OLE automation may not function correctly. Also, you cannot run multiple versions simultaneously. In Notes 5, you can't even run the client and server for the same version simultanously as you could in previous versions.
A.20.3 How do I get rid of the encap2.ond attachment on outgoing mail?

These attachments are used to send Notes rich-text-format messages to other Notes users across the Internet. In the SMTP MTA section of your server document, set the Message Content field to "Users without Lotus Notes"; you probably have this set to "Users with Lotus Notes". Your users can still manually send fully-formatted messages to Notes users via Internet mail by using Actions/SpecialOptions when creating a new mail message.

Troubleshooting and hints and tips

393

A.20.4 Can you run Notes 4.6 and 5.x clients simultaneously?

Yes, you can type these on the command line and change the paths appropriately: SET NOTESPARTITION=1 START c:\notes\program\nlnotes.exe =c:\notes\data\notes.ini Note that this is unsupported by Lotus. Use at your own risk.
A.20.5 How do you bypass Enforce ACL DB security?

You can add Disable_Local_Access_Control=1 to your notes.ini file and restart the server. The server restart is required for the setting to go into effect.
A.20.6 When Are Database Subscriptions Checked?

They are checked according to your mail poll interval.


A.20.7 How do you install the Notes client without user intervention?

1. Create a recording of those answers you want to avoid having users key in during installation. Then create the .iss file by going to a DOS or command prompt and entering the setup command:
setup.exe -r

Note that the -r argument creates the recording of your keystrokes and stores all the choices in a file called SETUP.ISS in the WINDOWS directory. 2. You can now use the .iss file as a parameter to the setup.exe file; it will skip all the questions and refer to the file for the choices. From a DOS or command prompt, enter the setup command:
setup -s setup.iss (in this case -s means Silent)

Its that simple. You can even put this command in a batch file and have the user run the batch file.
A.20.8 Can fields be added to the N&A Book?

There's no problem with adding fields and views, but don't change anything that is pre-existing. Do all your work in a template, and be very careful with the management of that template. There are two dangers: You could lose your modified template due to inadvertent replication from a newly installed server that has a standard PUBNAMES.NTF that is newer than your custom version. If you have two different templates for the NAB on different servers, such that $DESIGN on each server reinherits conflicting designs every night, it will cause a design dtorm that can bring your whole network down. Do not name the template PUBNAMES.NTF, or it may be overwritten by a software upgrade. Make sure that the template name is not the default (StdNotesAddressBook). You can either make it a replica of the original PUBNAMES.NTF, or a copy. If it is a replica, be sure to remove the original, be sure to let it replicate to all servers, and be especially sure that, any time a new Notes version is loaded, you

394

Lotus Domino for S/390 R5 Installation, Customization and Administration

merge any changes in the new version's PUBNAMES.NTF into your template and then delete that PUBNAMES.NTF from your server before you allow the upgraded server to replicate with any other server. If it is a copy instead of a replica, it is best that you uncheck the setting that allows replication of the template name for your NAB and make sure that only one server in your organization is set up to inherit the NAB design from your modified template. Just for insurance it might be a good idea to use the ACL or selective replication to insure that your main hub server never accepts NAB design changes from any other server.
A.20.9 What would change the list of servers in the Database Open dialog?

When you do a File/Database/Open, Notes will show you the servers for any database replica icons on your workspace. If you have renamed a server, it will continue to show up as long as you have an old replica icon from the old server on your workspace. If you select Other..., it will show you all servers known by your home server.
A.20.10 How do you make backup copies of created user IDs?

In Notes 4.x, the Escrow Agent allows the administrator to automatically copy user IDs, server IDs, and certifier IDs to a database whenever they register a user or server or create a certifier. It also stores the password (encrypted) in the document as well. To enable this automatic backup copy function: 1) Create a new person called ID Repository or something more descriptive. 2) Modify the NAB person document (ID Repository) user name field and append Escrow Agent to the field. 3) Restart the server. 4) Set the ID Repository mail file to have multiple passwords (so two administrators need to be present to open the mail file). 5) When you create user IDs, be sure to set the password to something difficult to type in (not something obvious like password) to encourage the user to change it. 6) Remind users that if they create new encryption keys, they should give you back a copy of their ID file with a known password if they want a backup made because the escrowed ID will not have these new keys.
A.20.11 Notes Full Text Search Syntax

The Notes search engine allows complex queries to be built through the use of a set of search keywords. Apart from the obvious logical keywords (AND, OR and NOT), Notes provides some advanced keywords that allow users to create highly sophisticated search queries: ( and ) -- can be used to override precedence and to group operations together. ? -- can be used to match a single character in any position in a word. Example: D?g would find "Dog", "Dig" and "Dug".

Troubleshooting and hints and tips

395

* -- can be used to match zero-to-many characters in any position in a word. Example: D*g would find "Dog", "Dig", "Dug" and "Drag". not or ! -- can be used to imply logical negation. Example: not cat would find documents not containing "cat". and or & -- can be used to imply logical conjunction. Example: cat and dog would find all documents containing both "cat" and "dog". or or | -- can be used to imply logical disjunction. Example: cat or dog would find all documents containing either "cat", "dog" or both words. accrue or -- is similar to the or operator, although documents score more highly, the more instances of either word they contain. Example: cat accrue dog would rate a document with five instances of "cat" more highly than one containing "cat" and "dog" once each. near, sentence and paragraph -- can be used to find documents containing words within a certain proximity of each other. Near has a proximity of eight words, sentence has a proximity of one sentence and paragraph has a proximity of one paragraph. Field -- can be used to restrict the search to a specific field. Example: Field Title contains a will find all documents that have an "a" in their title field. For numeric and date fields, the operators =, >, >=, <, <= are used instead of the contains operator. exact case -- can be used to restrict a search for the next expression to the specified case. Example: exact case dog will find documents containing "dog" but not "Dog". termweight n -- can be used to adjust the relevance ranking of the expression that follows, where n is 0-100. Example: termweight 10 dog or termweight 20 cat will rank documents containing "cat" higher than documents containing "dog". Hyphenated words -- can also be used to find two word pairs that are hyphenated, run together as a single word, or separated with a space. Example: spag-hetti will find documents containing "spaghetti", "spag hetti" and "spag-hetti". To search on a search keyword, the query string must be enclosed in quotation marks. For example, to search for documents containing the word field, the string field must be entered in the query string rather than field, which Notes would interpret as a keyword.

396

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix B. Our testing of the Domino Server on S/390


We installed a number of Domino servers on S/390 servers and tested them working alongside Domino servers on other platforms. This appendix describes what we tested. It shows that Domino on S/390 looks just like any other Domino server, and that you can combine Domino servers on S/390 with Domino servers on other platforms. We also document the few cases where the Domino server on S/390 was different from other platforms.

B.1 Our Test Environment


We created a test environment with a number of Domino servers in different domains. This is shown in Figure 286 on page 355. The domains we used are as follows:
ITSO

This was a new domain containing two Domino servers called Domino1 and Domino2. These both run on OS/390 V 2 Release 6 systems. This was also a new domain containing two Domino/390 servers called Domino3 and Domino4 running on OS/390 R6 and R7 respectively. We also had a Windows NT 4.0 server in this domain, called TOT105.

ITSO2

The Domino1 in the ITSO domain acted as the central hub server for our test environment. This server was connected to the TOT105 server in the ITSO2 domain and also to the Domino4 server in the ITSO2 domain.

B.2 What We Tested


These are some of the things we tested. We found that the Domino server on S/390 worked like any other Domino server. We set up the Notes environment as follows: We registered a number of users and groups in the ITSO and ITSO2 domains. We updated the Server Administrator's field in the Public Address Book to include a group name instead of just the original administrator's name. We created connection and domain documents to enable mail routing and replication between the various domains. We created location documents in the personal address book of the administrators to facilitate easy switching between domains and ID files. We cross-certified domains, servers and administrators. We tested mail transfer between users in the various domains, including the use of ITSO as a pass-through domain between ITSO and ITSO2. We tested replication between the various domains. We tested Domino commands such as load,
server restart

and show tasks.

We tested the Notes remote console function on various servers from one administrator workstation: Webadmin, Cconsole, DomCon, Domino Admin

Copyright IBM Corp. 1999

397

We set up event logging and statistics reporting. We edited the notes.ini file. See D.1, The notes.ini file on page 409.

B.3 Differences We Found


Our testing confirmed that the Domino server on S/390 works the same as on any other server from a function and Notes user viewpoint. We came across a number of differences from an operational viewpoint because of the nature of the S/390 server: On other servers you can set the server clock from the Domino server console. Again, since S/390 runs many applications on a single server, this does not work from the Domino server console on a S/390 server. Only the OS/390 operator console can set the clock. The S/390 server does not have a Notes client. Therefore: Server setup must be run from the UNIX environment, using rlogin or telnet, using the install program and the httpsetup configuration program. You must download the cert.id, the administrator's user.id and the server.id files to your workstation before you can perform administrator activities such as user registration or cross certification. You use Rlogin, Telnet or the OS/390 operator console (DOMCON) to start and monitor the Domino server. If you use Telnet to start the Domino server, closing the Telnet session means that you lose the Domino server console and cannot reconnect to it. Editing the notes.ini file is slightly different than on other platforms. See D.1, The notes.ini file on page 409.

398

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix C. Useful commands


This appendix provides OS/390 MVS and UNIX System Services commands that you may find useful.

C.1 MVS commands


Table 36 lists some UNIX System Services console commands.
Table 36. Useful USS-related MVS console commands

Command
D OMVS,F D OMVS, A=ALL D OMVS, A=asid D OMVS,PID=processid SETOMVS MAXPROCSYS=n

What It Does
Displays information about the HFS data sets that are mounted. Displays information about UNIX System Services address spaces. Displays information about a specific UNIX System Services address space Displays thread information for the process ID that is specified in processid. Specifies the maximum number of processes that UNIX System Services will allow to be active at the same time.

Example
Figure 308 Figure 309 Figure 310 Figure 311 Figure 312

This section shows the MVS console output from these commands.
C.1.1 D OMVS,F

D OMVS,F BPXO041I 14.27.46 DISPLAY OMVS 507 OMVS 000F ACTIVE OMVS=(53) TYPENAME DEVICE ----------STATUS----------- QJOBNAME HFS 9 ACTIVE NAME=OMVS.LOTUS01 PATH=/u/lotus01 HFS 8 ACTIVE NAME=OMVS.SC53.NOTES.LOTUS.MAIL.HFS PATH=/notesdata/mail HFS 7 ACTIVE NAME=OMVS.SC53.NOTES.LOTUS.V5000.DATA.HFS PATH=/notesdata HFS 6 ACTIVE NAME=OMVS.SC53.NOTES.LOTUS.V5000.PROD.HFS PATH=/usr/lpp/lotus HFS 5 ACTIVE
Figure 308. MVS command D OMVS,F sample output

Copyright IBM Corp. 1999

399

C.1.2 D OMVS,A=ALL
BPXO040I 16.26.45 DISPLAY OMVS 650 OMVS 000F ACTIVE USER JOBNAME ASID PID PPID STATE START CT_SECS OMVSKERN BPXOINIT 001F 1 0 MR 07.20.57 3.696 LATCHWAITPID= 0 CMD=BPXPINPR SERVER=Init Process AF= 5 MF=65535 TYPE=FILE STC MVSNFSC 00FB 16777218 1 1R 07.24.48 2.752 LATCHWAITPID= 0 CMD=BPXVCLNY STC TCPIP 001C 3 1 1R 07.21.20 1737.129 LATCHWAITPID= 0 CMD=MVPPCTSK STC MVSNFSC 00FB 16777220 1 1R 07.24.48 2.752 LATCHWAITPID= 0 CMD=GFSCMAIN STC MVSNFSC 00FB 83886085 1 1A 07.24.48 2.752 LATCHWAITPID= 0 CMD=BPXVCMT STC MVSNFSC 00FB 33554438 1 1A 07.24.48 2.752 LATCHWAITPID= 0 CMD=GFSCRPCD OMVSKERN INETD7 0042 7 1 1FI 07.24.41 23.004 LATCHWAITPID= 0 CMD=/usr/sbin/inetd/etc/inetd.conf STC MVSNFSC 00FB 8 1 1A 07.24.48 2.752 LATCHWAITPID= 0 CMD=GFSCRPCD STC MVSNFSC 00FB 13 1 1A 07.24.50 2.752 LATCHWAITPID= 0 CMD=GFSCRPCD STC MVSNFSC 00FB 14 1 1A 07.24.51 2.752 LATCHWAITPID= 0 CMD=GFSCRPCD STC RMFGAT 00FD 117440527 1 1R 13.33.20 15790.116 LATCHWAITPID= 0 CMD=ERB3GMFC OHKUBO OHKUBO3 003E 603979792 1090519058 1S 15.44.42 8.396 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/5000/os390/server STC INETD1 0048 17 1 1FI 17.04.56 .472 LATCHWAITPID= 0 CMD=INETD OHKUBO OHKUBO4 003B 1090519058 1392508956 1K 15.44.04 23.260 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/5000/os390/server LSRVS03 LSRVS03 003D 872415251 1124073492 1CI 11.29.22 11.051 LATCHWAITPID= 0 CMD=sh -L LSRVS03 LSRVS03 003D 1124073492 7 1FI 11.29.04 11.051 LATCHWAITPID= 0 CMD=otelnetd -Y 9.12.14.231 -p lsrvs03 -a vt STC FTPD1 0045 402653205 1 1FI 15.30.34 1.344 LATCHWAITPID= 0 CMD=FTPD OHKUBO OHKUBO 0041 889192470 738197528 1WI 14.36.04 11.144 LATCHWAITPID= 0 CMD=sh -L OHKUBO OHKUBO 0041 738197528 7 1FI 14.35.51 11.144 LATCHWAITPID= 0 CMD=otelnetd -Y 9.12.14.231 -p ohkubo -a vt2 OHKUBO OHKUBO5 0044 1358954521 1090519058 1F 15.44.10 21.942 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/5000/os390/server OHKUBO OHKUBO2 0046 234881050 1090519058 1S 15.44.35 12.723 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/5000/os390/adminp
Figure 309. D OMVS,A=ALL sample output

400

Lotus Domino for S/390 R5 Installation, Customization and Administration

C.1.3 D OMVS,A=asid
D OMVS,A=55 BPXO040I 15.19.31 DISPLAY OMVS 995 OMVS 000F ACTIVE USER JOBNAME ASID PID PPID STATE START CT_SECS DOMINO DOMINO7 0055 452984852 436207643 1S 14.41.28 3.051 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/sched
Figure 310. MVS command D OMVS,AID=asid sample output

C.1.4 D OMVS,PID=processid
D OMVS,PID=452984852 BPXO040I 14.47.08 DISPLAY OMVS 983 OMVS 000F ACTIVE USER JOBNAME ASID PID PPID STATE START CT_SECS DOMINO DOMINO7 0055 452984852 436207643 1S 14.41.28 1.928 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/sched THREAD_ID TCB@ PRI_JOB USERNAME ACC_TIME SC STATE 0958303800000000 007E3400 OMVS 1.909 SLP S
Figure 311. MVS command D OMVS,PID=processid sample output

C.1.5 SETOMVS MAXPROCSYS=n


SETOMVS MAXPROCSYS=1000 BPXO015I THE SETOMVS COMMAND WAS SUCCESSFUL.
Figure 312. MVS command SETOMVS MAXPROCSYS=n sample output

C.2 Some commands for problem determination


A UNIX System Services display command has a number of parameters that can help during problem determination.
C.2.1 D OMVS,U=xxxx

Figure 313 on page 402 shows the output with the userid parameter, specifying the user ID that is running the Domino Server EBBERS1.

Useful commands

401

.
-D OMVS,U=EBBERS1 BPXO040I 14.56.59 DISPLAY OMVS 867 OMVS 000F ACTIVE OMVS=(6C) USER JOBNAME ASID PID PPID STATE START CT_SECS EBBERS1 EBBERS1 0098 134217768 16777238 1F 14.32.58 2.510 LATCHWAITPID= 0 CMD=otelnetd -Y 9.12.14.92 -p ebbers1 -a vt1 EBBERS1 EBBERS1 0098 100663337 134217768 1W 14.33.07 2.510 LATCHWAITPID= 0 CMD=sh -L EBBERS1 EBBERS17 009F 134217770 100663337 1WI 14.33.26 .121 LATCHWAITPID= 0 CMD=sh -L EBBERS1 EBBERS13 002A 117440555 268435500 1S 14.33.49 .733 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/router EBBERS1 EBBERS12 0095 268435500 134217770 HS 14.33.29 14.515 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/server EBBERS1 EBBERS14 00A0 16777261 268435500 1S 14.33.54 .491 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/replic EBBERS1 EBBERS15 00A1 16777262 268435500 1S 14.34.00 1.383 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/update EBBERS1 EBBERS16 00A2 16777263 268435500 1S 14.34.06 1.228 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/amgr EBBERS1 EBBERS17 00A3 16777264 268435500 1S 14.34.11 2.033 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/adminp EBBERS1 EBBERS17 00A4 16777265 16777263 HD 14.34.12 1.341 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/amgr EBBERS1 EBBERS18 00A5 51 268435500 1S 14.34.17 .946 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/sched EBBERS1 EBBERS19 00A6 52 268435500 HS 14.34.22 5.285 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/event EBBERS1 EBBERS11 00A7 53 268435500 1SI 14.34.28 .379 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/stats EBBERS1 EBBERS12 00A8 54 268435500 HS 14.34.34 2.082 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/http EBBERS1 EBBERS13 00A9 55 268435500 HS 14.34.42 2.378 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/ldap EBBERS1 EBBERS14 00AA 56 268435500 HS 14.34.47 2.206 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/nntp EBBERS1 EBBERS15 00AB 57 268435500 1S 14.34.53 .776 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/maps EBBERS1 EBBERS16 00AC 58 268435500 HS 14.34.59 1.465 LATCHWAITPID= 0 CMD=/usr/lpp/lotus/notes/latest/os390/smtp

Figure 313. D OMVS,U=EBBERS1

This is comparable to the UNIX ps -ef command in Figure 314 on page 403.

402

Lotus Domino for S/390 R5 Installation, Customization and Administration

EBBERS1 16777265 atest/os390/amgr -e HAIMO 16777266 EBBERS1 51 atest/os390/sched EBBERS1 52 atest/os390/event EBBERS1 53 atest/os390/stats EBBERS1 54 atest/os390/http EBBERS1 55 atest/os390/ldap EBBERS1 56 atest/os390/nntp EBBERS1 57 atest/os390/maps EBBERS1 58 atest/os390/smtp HAIMO 285212732 HAIMO 16777277 HAIMO 16777278 -p ebbers -a vt100

16777263 - 14:34:13 ttyp0000 0:02 /usr/lpp/lotus/notes/l 1 1 - Oct 10 ? 0:00 GFSCMAIN 268435500 - 14:34:17 ttyp0000 0:02 /usr/lpp/lotus/notes/l 268435500 - 14:34:23 ttyp0000 0:17 /usr/lpp/lotus/notes/l 268435500 - 14:34:29 ttyp0000 0:00 /usr/lpp/lotus/notes/l 268435500 - 14:34:35 ttyp0000 0:02 /usr/lpp/lotus/notes/l 268435500 - 14:34:42 ttyp0000 0:04 /usr/lpp/lotus/notes/l 268435500 - 14:34:48 ttyp0000 0:05 /usr/lpp/lotus/notes/l 268435500 - 14:34:54 ttyp0000 0:01 /usr/lpp/lotus/notes/l 268435500 - 14:34:59 ttyp0000 0:03 /usr/lpp/lotus/notes/l 16777277 16777278 16777238 -t -l -m -D - 15:54:43 - 14:43:11 - 14:42:53 options -D ttyp0001 ttyp0001 ? report -D 0:02 ps -ef 0:02 sh -L 0:02 otelnetd -Y 9.12.14.92 net

Figure 314. ps -ef command output

C.2.2 D OMVS, OPTIONS

Domino for S/390 requires the OMVS environment to be configured according to the recommendations. To verify which BPXPARMS are in effect, issue a D OMVS,OPTIONS command (or D OMVS,O). This information should be included in any SYSLOGS sent to the Support Center. See Figure 315.

RESPONSE=SC67 BPXO043I 15.50.13 DISPLAY OMVS 900 OMVS 000F ACTIVE OMVS=(6C) OPENEDITION MVS CURRENT CONFIGURATION SETTINGS: MAXPROCSYS = 4096 MAXPROCUSER MAXFILEPROC = 256 MAXFILESIZE MAXCPUTIME = 2147483647 MAXUIDS MAXRTYS = 256 MAXPTYS MAXMMAPAREA = 4096 MAXASSIZE MAXTHREADS = 100000 MAXTHREADTASKS MAXCORESIZE = 4194304 MAXSHAREPAGES IPCMSGQBYTES = 1048576 IPCMSGQMNUM IPCMSGNIDS = 20000 IPCSEMNIDS IPCSEMNOPS = 32767 IPCSEMNSEMS IPCSHMMPAGES = 25600 IPCSHMNIDS IPCSHMNSEGS = 1000 IPCSHMSPAGES SUPERUSER = BPXROOT FORKCOPY STEPLIBLIST = USERIDALIASTABLE= /etc/alias PRIORITYPG VALUES: NONE PRIORITYGOAL VALUES: NONE MAXQUEUEDSIGS = 1000

= 32767 = NOLIMIT = 200 = 256 = 2147483647 = 32767 = 131072 = 20000 = 4096 = 32767 = 20000 = 786432 = COW

Figure 315. Display active OMVS options BPXPARMS

Useful commands

403

C.2.3 icps -bom

The ipcs -bom command is useful to determine what shared memory segments exist and how many processes are attached to the segments. When dealing with the support center, the -bom option is very useful, as compared with the plain ipcs command.

EBBERS @ SC67:/>ipcs -bom Shared T m m m Memory: ID KEY MODE OWNER 32292 0xf8000800 --rw-rw---- EBBERS1 32293 0xf8000801 --rw-rw---- EBBERS1 32294 0xf8000802 --rw-rw---- EBBERS1

GROUP SYS1 SYS1 SYS1

NATTCH SEGSZPG 15 1682 15 2048 15 2048

Figure 316. ipcs -bom command showing shared memory segments

C.3 UNIX System Services commands


For those new to OS/390 UNIX System Services, the following is a list of useful commands when using the UNIX System Services shell:
Table 37. Useful UNIX System Services commands

Command
cd chown df

What it Does
Changes the working directory. Change the owner or group of a file or directory. Displays the amount of free space in a file system and the total amount allocated. The -Pk options lists complete information on the space used, in the following order: File system name Total space Space used Space free Percentage of space used File system root Writes its arguments to standard output. Displays the environment variables. Format: export name=value Marks each variable name so that the current shell makes it automatically available to the environment of all commands run from that shell. Converts the characters in a file from code page set to another. Ends a process by sending it a signal.

Example
cd notesdata chown domino1 domino2 See Figure 317 on page 405.

echo env export

echo $LIBPATH See Figure 318 on page 405. export PATH=/usr/lpp:/notesdata:$PATH

iconv kill

See Figure 319 on page 405. kill -9 xxxxxxxxxx Where xxxxxxxxxx process ID (PID)

is

the

ls

Lists files and directories. The -l option displays permissions, links, owner, group, size, time and name.

See Figure 320 on page 406.

404

Lotus Domino for S/390 R5 Installation, Customization and Administration

Command
mkdir ps

What it Does
Creates a new directory Displays information about processes. The -a option displays information on all processes associated with terminals. Sets command line prompt. $LOGNAME is userid. $HOSTNAME is the system name. $PWD is the current directory. Displays the absolute (fully qualified) pathname of the current working directory. Removes a file. Displays trace information when debugging a shell script.

Example
mkdir /usr/lpp/lotus See Figure 321 on page 406.

PS1

export PS1=$LOGNAME $HOSTNAME:$PWD> pwd rm filename

pwd rm set -o xtrace

C.3.1 df command
df -Pk /notesdata Filesystem 1024-blocks Used Available Capacity Mounted on OMVS.NOTES.LOTUS.V5000.DATA.HFS 720000 453792 266208 64% /notesdata
Figure 317. UNIX System Services df command sample output

C.3.2 env command


env MAIL=/usr/mail/OHKUBO_BPX_TERMPATH=OMVS PATH=/bin:. _CXX_WORK_UNIT=SYSALLDA SHELL=/bin/sh _C89_SLIB_PREFIX=SYS1 _C89_CLIB_PREFIX=CBC _CXX_PLIB_PREFIX=CEE _CC_WORK_UNIT=SYSALLDA COLUMNS=80
Figure 318. UNIX System Services env command sample output

C.3.3 iconv command


iconv -f ISO08859-1 -t IBM-1047 sample.txt > sampn.txt This example converts from ISO08859-1(ASCII) to IBM-1047(EBCDIC). The input file is 'sample.txt' and output is re-directioned to the file 'sampn.txt'.
Figure 319. UNIX System Services iconv command sample output

Useful commands

405

C.3.4 ls command
ls -l total 304 drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x -rw-r--r-drwx-----drwxrwxrwx

3 2 5 2 2 1 9 3

STC STC STC STC STC LSRVS04 LSRVS04 LSRVS03

OMVSGRP OMVSGRP OMVSGRP OMVSGRP OMVSGRP OMVSGRP OMVSGRP SYS1

0 0 0 0 0 3177 0 0

Apr Mar Apr Jan Apr May May May

10 5 18 22 9 12 19 15

11:44 10:11 17:39 21:38 17:56 13:15 05:03 08:01

bin dev etc krb5 lib notes.old notesdata notesdatab

Figure 320. UNIX System Services ls command sample output

C.3.5 ps command
ps -a PID 603979792 1090519058 872415251 889192470 1358954521 234881050 1392508956 184549405 318767134 268435487 67108896 83886115 TTY ttyp0001 ttyp0001 ttyp0000 ttyp0001 ttyp0001 ttyp0001 ttyp0001 ttyp0001 ttyp0001 ttyp0001 ttyp0002 ttyp0002 TIME 0:01 0:11 0:11 0:10 0:03 0:02 0:09 0:03 0:01 0:01 0:26 0:00 CMD /lpp/lotus/notes/5000/os390/server /lpp/lotus/notes/5000/os390/server /sh /sh /lpp/lotus/notes/5000/os390/server /lpp/lotus/notes/5000/os390/adminp /lpp/lotus/notes/5000/os390/server /lpp/lotus/notes/5000/os390/amgr /lpp/lotus/notes/5000/os390/update /lpp/lotus/notes/5000/os390/replica /sh /ps

Figure 321. UNIX System Services ps command sample output

C.4 Domino Server Commands


Table 38. Useful Domino Server commands

Command
show tasks show users quit help restart server tell http sh users tell http restart Tell LDAP reloadschema

What It Does
Shows the tasks running on the server. Shows connected users. Shuts down the server. Displays a list of server commands with brief descriptions. Restarts the server. Shows users that authenticated via the Web. Restarts the HTTP task. Updates the directory schema on the LDAP server to reflect changes that result after you customize the Domino Directory. Shows mail held in transfer queues to specific servers.

Tell Router Show Queues

406

Lotus Domino for S/390 R5 Installation, Customization and Administration

Command
Tell Router Delivery Stats tell mtc process Tell Clrepl Log

What It Does
Shows Router delivery statistics. Manually tell the Mail Tracking Collector to collect data for tracking or reports. Records information in the server log (LOG.NSF) immediately, instead of waiting for the next log interval. The log includes information about all cluster replications waiting for retry. Use this command when the Replica.Cluster.Retry.Waiting statistic is non-zero, indicating that some replications could not be completed and are awaiting a retry. After you correct the errors (for example, by restarting the server that was unavailable) the Cluster Replicator will succeed on its next retry and the Replica.Cluster.Retry.Waiting statistic will return to zero. Stops all instances of the Cluster Replicator on a server. To prevent the Clrepl task from running in future sessions, remove all instances of the Clrepl task from the ServerTasks setting in the NOTES.INI file. Disabling the Clrepl task on one server only prevents replication from that server to other servers; it doesn't prevent replication to the server from other cluster servers. Displays (and records in the server's log file) this information: The databases that a particular administration server updates The locations in the database where it updates Reader and Author fields in the databases it updates The databases that don't have an administration server assigned to them

Tell Clrepl Quit

Tell Adminp Show Databases

Tell Adminp Process People

Processes all new and modified requests to update Person documents in the Domino Directory.

C.5 Using the UNIX vi editor


For those new to UNIX's vi editor, Table 39 is a list of useful commands when using vi. Note: Remember that you must use viascii when editing notes.ini and not the standard vi command, which is an EBCDIC editor.
Table 39. Useful vi commands

Command
0 (zero) $ /search_string ?search_string a

What it means
Move to the beginning of line Move to the end of line Search forward for next line containing search_string Search backward for next line containing search_string Append text, in insert mode, after current cursor position

Useful commands

407

Command
^b B b Backspace ^d D dw dd ESC ^f G

What it means
Move up one screen Move to previous space-delimited word Move to previous word Move left one character Move down half a screen Delete until end of line Delete word Delete line Leave insert mode and return to command mode Move forward one screen Move to the last line of the file Move to the nth line of the file Move left one character Insert text before the current character Move down one line Move up one line Move right one character Repeat last search Open a new line for insertion above current line Open a new line for insertion after current line Move to the start of the next line Move up half a page Undo any changes to current line Undo last changes made to file Move forward one space delimited word Move forward one word Delete the current character Quit vi and return to the shell Quit vi and return to the shell without saving any changes made to the file Writes the changed file to disk

nG
h i j k l n O o Return ^u U u W w x :q :q! :w

408

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix D. Editing the notes.ini file


The tasks of a Domino administrator are described in detail in the Lotus Notes Administrator's Guide. For an administrator on a S/390 server, most tasks are the same as in any other environment. However, there are a number of differences, described in B.3, Differences We Found on page 398. As a result of these differences, some administrative activities have to be carried out differently than in other environments. In this appendix we discuss how you can update the notes.ini file.

D.1 The notes.ini file


The notes.ini file is an important configuration file that contains initialization settings for the Domino server. For example, it tells the server which server tasks to run when it starts up. The notes.ini file is located in the notes data directory, which is by default /notesdata on S/390. As with other platforms, the notes.ini file on S/390 is stored in ASCII format and not in EBCDIC. The Domino server uses the first notes.ini file it finds in the path. If you have multiple copies of the notes.ini file on your system, Domino may start with incorrect settings, or it may not even start. It is therefore advisable to have only one notes.ini file accessible to the server. Figure 322 shows a sample notes.ini file on a Domino server:
[Notes] KitType=2 Directory=/notesdata NOTES_SHARED_DPOOLSIZE=8388608 Passthru_LogLevel=0 Console_LogLevel=2 VIEWIMP1=Lotus 1-2-3 Worksheet,0,_IWKSV,,.WKS,.WK1,.WR1,.WRK,.WK3,.WK4, VIEWIMP3=Structured Text,0,_ISTR,,.LTR,.CGN,.STR, VIEWIMP4=Tabular Text,0,_ITAB,,.PRN,.RPT,.TXT,.TAB, VIEWEXP1=Lotus 1-2-3 Worksheet,0,_XWKS,,.WKS,.WK1,.WR1,.WRK, VIEWEXP3=Structured Text,0,_XSTR,,.LTR,.CGN,.STR, VIEWEXP4=Tabular Text,1,_XTAB,,.LTR,.RPT,.CGN,.TAB, EDITIMP1=ASCII Text,0,_ITEXT,,.TXT,.PRN,.C,.H,.RIP, EDITIMP2=MicrosoftWord RTF,0,_IRTF,,.DOC,.RTF, EDITIMP3=Lotus 1-2-3 Worksheet,0,_IWKSE,,.WKS,.WK1,.WR1,.WRK,.WK3,.WK4, EDITIMP4=Lotus PIC,0,_IPIC,,.PIC, EDITIMP5=CGM Image,0,_IFL,,.GMF,.CGM, EDITIMP6=TIFF 5.0 Image,0,_ITIFF,,.TIF, EDITIMP7=BMP Image,0,_IBMP,,.BMP, EDITIMP8=Ami Pro,0,_IW4W,W4W33F/V0,.SAM, EDITIMP17=WordPerfect 5.x,0,_IW4W,W4W07F/V1,.DOC, EDITIMP22=PCX Image,0,_IPCX,,.PCX, EDITIMP28=Binary with Text,0,_ISTRNGS,,.*, EDITIMP29=WordPerfect 6.0/6.1,0,_IW4W,W4W48F/V0,.WPD,.WPT,.DOC, EDITIMP30=Excel 4.0/5.0,0,_IW4W,W4W21F/V4C,.XLS, EDITIMP31=Word for Windows 6.0,0,_IW4W,W4W49F/V0,.DOC, EDITIMP32=GIF Image,0,_IGIF,,.GIF, EDITIMP33=JPEG Image,0,_IJPEG,,.JPG, EDITEXP1=ASCII Text,2,_XTEXT,,.TXT,.PRN,.C,.H,.RIP, EDITEXP2=MicrosoftWord RTF,2,_XRTF,,.DOC,.RTF, EDITEXP3=CGM Image,2,_XCGM,,.CGM,.GMF, EDITEXP4=TIFF 5.0 Image,2,_XTIFF,,.TIF, EDITEXP5=Ami Pro,2,_XW4W,W4W33T/V0,.SAM,

Figure 322. Sample notes.ini file - part 1

Copyright IBM Corp. 1999

409

EDITEXP14=WordPerfect 5.1,2,_XW4W,W4W07T/V1,.DOC, EDITEXP21=WordPerfect 6.0,2,_XW4W,W4W48T/V0,.DOC, EDITEXP22=WordPerfect 6.1,2,_XW4W,W4W48T/V1,.WPD,.WPT,.DOC, EDITEXP23=Word for Windows 6.0,2,_XW4W,W4W49T/V0,.DOC, NAMEDSTYLE0=02004261736963000000000000000000000000000000000000000000000000000000 0000000001010100000A0000000000000100A0050000A00500000000000000000000000000000000 00000000000000000000000000000000000000000000000 0000000000000000000000000 NAMEDSTYLE1=020042756C6C65740000000000000000000000000000000000000000000000000000 0000000001010100000A000000000000000008070000080700000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000400000000000000 00 NAMEDSTYLE2=0200486561646C696E65000000000000000000000000000000000000000000000000 00000000010101010B0C0000000000000100A0050000A00500000000000000000000000000000000 000000000000000000000000000000000000000000000000000000000000000000000000 $$$OpenSpecial=NotesNIC, InterNotes $$$NotesNIC=CN=Home/OU=Notes/O=NET, welcome.nsf, Notes NIC Welcome, Notes Network Information Center on the Internet $$$InterNotes=,web.nsf,Web Navigator, Local InterNotes Web Navigator Database Preferences=32 ServerTasks=Replica,Router,Update,Stats,AMgr,Adminp ServerTasksAt1=Catalog,Design ServerTasksAt2=UpdAll,Object Collect mailobj.nsf ServerTasksAt5=Statlog TCPIP=TCP, 0, 15, 0 $$HasLANPort=1 Ports=TCPIP SPX=SPX, 0, 15, 0 Serial1=XPC,1,15,0, Serial2=XPC,2,15,0, DisabledPorts=SPX,Serial1,Serial2 LOG_REPLICATION=1 LOG_SESSIONS=1 KeyFilename=/notesdata/server.id Timezone=5 DST=1 ZONE_SET=1 CertifierIDFile=/notesdata/cert.id MailSystem=0 MailServer=CN=wtsc53/O=itso390r ServerKeyFileName=server.id Domain=itso390r Admin=CN=boris admin/O=itso390r TemplateSetup=1 ServerSetup=6 FileDlgDirectory=/notesdata PhoneLog=2 Log=log.nsf, 1, 0, 7, 40000

Figure 323. Sample notes.ini file - part 2

D.1.1 Changing settings in the notes.ini file

You may need to change settings in the notes.ini file. There are different ways to do this: By issuing the Set Configuration command at the console By editing a Server Configuration document in the Public Address Book By editing the notes.ini file directly The first two methods are the simplest. However, not all changes can be made in those ways. The following are ways to edit the notes.ini file directly: Edit the file from an OMVS session using the oeditascii editor. Edit the file from an rlogin or Telnet session using the viascii editor. Transfer the file to a workstation, edit there and then transfer it back. Edit the file from a workstation using Network File System (NFS).
410

Lotus Domino for S/390 R5 Installation, Customization and Administration

Convert and copy the file to a sequential data set, edit it in TSO and copy it back into the HFS.
Note: As a precaution you should always copy the notes.ini file to a backup file before you edit it! D.1.2 Edit from an OMVS session using oeditascii

To edit the file from an OMVS session using the oeditascii editor: 1. Logon to TSO using a userid with OMVS access. 2. Issue the OMVS command to enter the UNIX Shell. 3. Change to the notesdata directory, for example cd /notesdata 4. Copy the notes.ini file to a backup, for example cp notes.ini notesold.ini 5. Edit the notes.ini file: /usr/lpp/lotus/bin/tools/oeditascii notes.ini
Note: To use oeditascii you must have made the UNIX System Services TSO/E commands available to ISPF users. For details see: OS/390 V2R6 UNIX System Services Installation and Customization SG24-5178, Chapter 4.6 "Customizing the OpenMVS ISPF shell". D.1.3 Edit from rlogin or Telnet using viascii

To edit the file from an rlogin or Telnet session using the viascii editor: 1. Logon to the S/390 server using rlogin or Telnet from a workstation. You will enter the UNIX Shell. 2. Change to the notesdata directory, for example cd /notesdata 3. Copy the notes.ini file to a backup, for example cp notes.ini notesold.ini 4. Edit the notes.ini file: /usr/lpp/lotus/bin/tools/viascii notes.ini 5. See C.5, Using the UNIX vi editor on page 407 for a list of useful viascii (same as vi) editor commands.
D.1.4 Transfer to a workstation and edit it there

You can transfer the notes.ini file to a workstation using FTP, edit it on the workstation using a familiar editor, and then use FTP to transfer it back to S/390. We have documented the use of FTP in several places, including 5.4.2, Upload the files using FTP on page 74 and 7.3, Running the server configuration program on page 106. The sequence of commands is: 1. Login to FTP. 2. get the file in binary. 3. Edit it on the PC. 4. put the file in binary.
D.1.5 Edit remotely using NFS

You can use the Network File System (NFS) to mount the S/390 HFS on your workstation. For example, you could mount the /notesdata directory of the S/390 server on your PC workstation as your z disk using the command: mount z: wtsc53:/notesdata. Then you can edit the file z:\notes.ini using your favorite PC editor, and when you save the changes, they are saved on the S/390 server.

Editing the notes.ini file

411

For information on how to set up NFS on the S/390 server, see OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization , SG24-5178. You will also need to set up NFS on your workstation. Once you have done that, editing files on the S/390 server is very easy.

412

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix E. Automating the operation of Domino using NetView


In 9.7, DOMCON on page 160, we discuss the DOMCON package, which allows the Domino server to be managed from the OS/390 operator console. With the Domino server commands and messages on the OS/390 operator console, we can automate operation of the Domino server using NetView (or an equivalent automation package). We use the NetView message automation facilities. They monitor the console for specified messages and then take action by running an MVS CLIST or REXX file. We wrote automation for two situations that may occur. You can use these as ideas for your environment. For more information, see NetView Customization: Using Assembler Version 3, SC31-8053.

E.1 Restarting a task


In this example we respond to a task that shuts down, and we use NetView to restart the task. For our testing we closed down the adminp task using the Domino tell command. This command, and the resulting message, are shown in Figure 324.

S DOMINC,CMD='tell adminp quit' +WSC/DOMINO-B TELL ADMINP QUIT +WSC/DOMINO-B > 07/18/97 02:15:57 PM Administration Process shutdown
Figure 324. Console message when task ends

We want to use NetView automation to trap this event and issue the Domino server command load adminp to restart the administration process. To do this we create a new member, DOMPROC, in the NetView procedure library. This procedure looks for the message Administration Process shutdown and responds to it by issuing the OS/390 operator console command S DOMINC,CMD='load adminp'. DOMPROC is shown in Figure 325.

ARG DOMDATA DOMTMP = ''||substr(DOMDATA,39,31) If DOMTMP = 'Administration Process Then "S DOMINC,CMD='load adminp'" Exit
Figure 325. NetView procedure DOMPROC

/* get input argument /* shutdown' /* Adminp terminated? /* Start Administration process /*

*/ */ */ */ */

Now to get DOMPROC to run, we use a NetView AUTOTBL command to activate the IF-THEN statement in Figure 326. This runs DOMPROC whenever a Domino message is detected on the console.

IF MSGID='+WSC/DOMINO-B' & TEXT=DOMTXT THEN EXEC(CMD('DOMPROC' DOMTXT) ROUTE(ONE OPER1))


Figure 326. NetView IF-THEN statement to run DOMPROC

The required automation process is now active.

Copyright IBM Corp. 1999

413

E.2 Highlight resource constraint


In this example we respond to a resource constraint and highlight the problem to the OS/390 operator. We assume that a Notes user tried to connect to the Domino server, but the connection was rejected because there was no memory available to open a new session. The messages in Figure 327 would appear on the OS/390 operator console.

+WSC/DOMINO-B > Error attempting to load or run /usr/lpp/lotus/notes/l atest/os390/server: +WSC/DOMINO-B Unable to invoke program
Figure 327. Console message when not enough resources

We want to use NetView automation to trap this event and notify the OS/390 operator by issuing a Write To Operator (WTO). The OS/390 support staff can then be asked to review the system parameters and take appropriate action. In this case the DOMPROC procedure is shown in Figure 328. It looks for the message Error attempting to load or run and uses the WTO macro to write the message Domino server failure on the OS/390 operator console.

ARG DOMDATA /* get input argument DOMTMP = ''||substr(DOMDATA,17,28) /* If DOMTMP = 'Error attempting to load or run' /* system error? Then 'WTO Domino server failure' /* Let MVS operator know! Exit /*
Figure 328. NetView procedure to issue WTO macro

*/ */ */ */ */

To get DOMPROC to run we again, use a NetView AUTOTBL command to activate the IF-THEN statement in Figure 326 on page 413.
Note: There is currently no published list of error messages and their meanings for the Domino S/390 server. You should monitor your environment and test solutions to problems in order to feel comfortable with implementing any automated responses to error messages.

414

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix F. The ps shell command for threads


Here is a useful command from Clark Goodrich, a Domino for S/390 developer. In OS/390 2.7, the ps shell command displays a lot more information about threads. On a V2R7 system, you can learn more about this command by using the man ps shell command. A sample is shown F.1, The new ps command for OS/390 V2R7 on page 415, with new operands in bold (in blue if you are displaying online). For problem determination, there are fields that display: The last five syscalls (LASTSYSC) Wait time (WTIME) Semaphore (SNUM/SVAL) Short thread ID (STID) TCB address TCBADDR There is also a new hex ASID. Note that the CPU time field (TIME) is process only and does not show CPU time used for each thread. Knowing the CPU time per thread is also useful, and can be obtained by using the MVS console command:
DISPLAY OMVS,PID=xxxxxxxxx

F.1 The new ps command for OS/390 V2R7


Following is the new ps command for R7 and above. It will also work on older releases.
$ ps -A -o pid,ppid,xasid,thdcnt,atime,state,ruser,comm -o THREAD -o xstid,xtcbaddr,wtime,semnum,semval,lsyscall

PID PPID ASID THCNT TIME S WTIME SNUM SVAL LASTSYSC 503316540 318767424 1c 5 0:00 HSI - - 0:00 SU 0:02 - 1SLP1WRT1WRT1PTC1PTC - 0:00 SJ 0:02 - 1SLP1PTX1NOP1NOP1NOP - 0:00 SJ 0:02 - 1SLP1PTX1NOP1NOP1NOP - 0:00 SJ 0:02 - 1SLP1PTX1NOP1NOP1NOP - 0:00 SJ 0:02 - 1SLP1PTX1NOP1NOP1NOP 67109004 16777256 1e8 1 0:08 1R - - 0:00 R 0:00 - 1SEL1WRT1RDV1SEL1WRT

RUSER COMMAND CAGOOD ./thrds - - - - - -

STID TCBADDR 00000001 00000002 00000003 00000004 00000005 8cb580 8cb2f0 8cb158 8d9e88 8d9c68 8e6318

CAGOOD /usr/sbin - -

00000002

Copyright IBM Corp. 1999

415

1124073751 318767424 1e8 1 0:08 1R - - 0:00 R 0:00 - 1GTH1WRT1WRT1SYC1GTH 318767424 67109004 1e8 1 0:08 1W - - 0:00 W 0:00 - 1WAT1SPM1SPM1SPM1TSP
Figure 329. New ps Command

CAGOOD /bin/ps - CAGOOD /bin/sh - -

00000000 00000002

8e6180 8d47b0

F.2 Sample shell script


Here is a sample shell script. It will work will OS/390 V2R7 and above (or below).
OS=$(uname -r) if test $OS > "07.00" | test $OS = "07.00" then ps -A -o pid,xasid,atime,state,ruser,comm -o THREAD xstid,wtime,semnum,semval,lsyscall else ps -A -o pid,ppid,atime,state,ruser,comm fi

-o

Figure 330. Sample Shell Script for OS390 2.7 (also Newer and Older Releases)

F.3 Description of new fields


In this section we provide descriptions of the new fields.
F.3.1 Thread only lpid

Displays the latch pad waited for. [lpid]


lsyscall

Displays the last five syscalls. This is a 20-character string consisting of five 4-character syscalls with no delimiting characters between them. From left to right, the syscalls are ordered from most recent to oldest. In the following example of lsyscall output, 1WAT is the most recent syscall:
1WAT1SPM1SPM1SPM1TSP. [LASTSYSC] semnum

Displays the semaphore number of the semaphore the thread is in a wait state for. (Note: a semaphore number is only available when the thread is in a semaphore wait state (state field value equals d); otherwise, a dash is displayed). [SNUM]
semval

Displays the semaphore value of the semaphore the thread is in a wait state for. (Note: a semaphore value is only available when the thread is in a semaphore wait state (state field value equals D); otherwise, a dash is displayed). [SVAL]

416

Lotus Domino for S/390 R5 Installation, Customization and Administration

sigmask

Displays the signal pending mask as a hexidecimal value. [SIGMASK]


syscall

Displays the current syscall (for example, 1frk for fork). [SYSC]
tagdata

Displays the tag assigned to the thread using pthread_tag_np(). If a tag was not assigned, a dash will be displayed. [TAGDATA]
wtime

Displays waiting time in the form fflffldd"hh"mm:ssffl.xx" where dd is the number of days, hh is the number of hours, mm is the number of minutes, and ss is the number of seconds. [WTIME]
xtcbaddr

Displays the TCB address as a hexadecimal value. A non-hex TCB address is not supported. [TCBADDR]
xstid

Displays the short thread id as a hexidecimal value. This is the low-order word (the sequential value) of the thread ID. A non-hex short thread ID is not supported. [STID]
xtid

Displays the thread ID as a hexidecimal value. A non-hex thread ID is not supported. [TID]
F.3.2 State

This displays the process state [STATE]. Various values can be printed in this field:
1 A B C D E F G J K N O R S U V W X Y Z A single task using assembler callable services Message queue receive wait Message queue send wait Communication system kernel wait Semaphore operation wait Quiesce frozen File system kernel wait MVS Pause wait Pthread created Other kernel wait (for example, pause or sigsuspend) Medium weight thread Asynchronous thread Running (not kernel wait) Sleeping Initial process thread Thread is detached Waiting for a child (wait or waitpid function is running) Creating a new process (fork function is running) MVS wait Canceled and parent has not performed wait (Z for zombie)

The ps shell command for threads

417

418

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix G. Real-life BPX parameters


Table 40 shows BPX parameter values that are working in actual locations. Two are IBM internal systems and two are customer systems. This table does not provide recommendations, but simply shows some values that work. For recommendations, see 15.3, OS/390 UNIX parameters in SYS1.PARMLIB(BPXPRMxx) on page 317.
Table 40. Examples of BPX parameters in production environments

Parameter

IBM Test

IBM Location

Customer A

Customer B

maxprocsys maxprocuser maxfileproc maxfilesize maxcputime maxuids maxrtys maxptys maxmmaparea maxassize maxthreads maxthreadtasks maxcoresize maxsharepages maxqueuedsigs ipcmsgqbytes ipcmsgqmnum ipcmsgnids ipcsemnids ipcsemnops ipcsemnsems ipcshmmpages ipcshmnids ipcshmnsegs

4,096 32,767 256 nolimit 2,147,483,647 200 256 256 4,096 2,147,483,647 100,000 32,767 4,194,304 131,072 1,000 1,048,576 20,000 20,000 4,096 32,767 32,767 25,600 20,000 1,000

3,250 200 65,535

200 50 65,535

32767 32767 65,535 11,000,000

2,147,483,647 40

2,147,483,647 50 256

2,147,483,647 50 256 256 4,096 2,147,483,647 1,000 1,000 4,194,304 32,768,000 100,000 262,144 10,000 500 20,000 32,767 25 524,287 500 20,000

256

256 4,096

2,147,483,647 3,200 3,200

2,147,483,647 200 1,000 4,194,304

32,768,000 100,000 1,048,576 20,000 200 6,000 32,767 32,767 25,600 600 1,000

32,768,000 100,000 262,144 10,000 500 2,000 32,767 25 25,600 500 1,000

Copyright IBM Corp. 1999

419

ipcshmspages

786,432

2,621,440

2,621,440

2,621,440

/*******************************************************************/ /* This member, as specified in IEASYS00, will cause UNIX System */ /* Services to come up with all filesystems mounted. */ /*******************************************************************/ ROOT FILESYSTEM('OMVS.ROOT') /* OS/390 root filesystem */ TYPE(HFS) /* Filesystem type HFS */ MODE(RDWR) /* Mounted for read/write */ /* */ MOUNT FILESYSTEM('OMVS.ETC') /* HFS for /etc directory */ MOUNTPOINT('/etc') TYPE(HFS) /* Filesystem type HFS */ MODE(RDWR) /* Mounted for read/write */ /* */ /* HFS for /tmp directory */ MOUNT FILESYSTEM('OMVS.MVSH.TMP.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/tmp')

MOUNT FILESYSTEM('OMVS.NOTES.PROD.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/usr/lpp/lotus') MOUNT FILESYSTEM('OMVS.NOTES.DATA.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/notesdata') MOUNT FILESYSTEM('OMVS.NOTES.MAIL.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/notesdata/mail')

Figure 331. Sample BPXPRMH0 member for mounting file systems

420

Lotus Domino for S/390 R5 Installation, Customization and Administration

Appendix H. Special notices


This publication is intended to help an OS/390 system programmer and a Lotus Notes administrator install, set up, and administer Lotus Domino for S/390 Release 4.6. The information in this publication is not intended as the specification of any programming interfaces that are provided by Lotus. See the Publications section of the IBM or Lotus Programming Announcement for Lotus Notes Release 4 for more information about what publications are considered to be product documentation. References in this publication to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent program that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program or service. Information in this book was developed in conjunction with use of the equipment specified, and is limited in application to those specific hardware and software products and levels. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The information contained in this document has not been submitted to any formal IBM test and is distributed AS IS. The information about non-IBM ("vendor") products in this manual has been supplied by the vendor and IBM assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Any pointers in this publication to external Web sites are provided for convenience only and do not in any manner serve as an endorsement of these Web sites. Any performance data contained in this document was determined in a controlled environment, and therefore, the results that may be obtained in other operating environments may vary significantly. Users of this document should verify the applicable data for their specific environment.

Copyright IBM Corp. 1999

421

Reference to PTF numbers that have not been released through the normal distribution process does not imply general availability. The purpose of including these reference numbers is to alert IBM customers to specific information relative to the implementation of the PTF when it becomes available to each customer according to the normal IBM PTF distribution process. The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries: OS/390 OS/400 Parallel Sysplex PR/SM Processor Resource/Systems Manager PROFS PR/SM RACF RAMAC RMF

The following terms are trademarks of other companies: Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything. Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli Systems Inc., an IBM company, in the United States, other countries, or both. In Denmark, Tivoli is a trademark licensed from Kjbenhavns Sommer - Tivoli A/S. C-bus is a trademark of Corollary, Inc. in the United States and/or other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries. PC Direct is a trademark of Ziff Communications Company in the United States and/or other countries and is used by IBM Corporation under license. ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States and/or other countries. UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group. SET and the SET logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others.

422

Lotus Domino for S/390 R5 Installation, Customization and Administration

IBM

RS/6000 S/390 SP System/390 VisualAge VM/ESA VTAM WebSphere XT 400

Appendix I. Related publications


The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.

I.1 IBM Redbooks publications


For information on ordering these publications see How to Get ITSO Redbooks on page 427. Deploying Domino in a S/390 Environment , SG24-2182 Porting C Applications to Lotus Domino on S/390, SG24-2092 OS/390 Version 2 Release 6 UNIX System Services Implementation and Customization , SG24-5178 OS/390 eNetwork Communication Server V2R7 TCP/IP Implementation Guide Volume 1: Configuration and Routing, SG24-5227 Lotus Notes Release 4.5: A Developer's Handbook , SG24-4876 Managing a Notes Environment with TME 10 Module for Domino/Notes Version 1.0, SG24-2104 Enterprise Integration with Domino.Connect , SG24-2181 Using ADSM to Back Up Databases , SG24-4335 Using ADSM to Back Up Lotus Notes, SG24-4534 Lotus Solutions for The Enterprise, Volume 1 Lotus Notes: An Enterprise Application Platform , SG24-4837 Lotus Solutions for the Enterprise, Volume 3 Using the IBM CICS Gateway for Lotus Notes, SG24-4512 The Domino Defense: Security in Lotus Notes and the Internet, SG24-4848 Secrets to Running Lotus Notes: The Decisions No One Tells You How to Make, SG24-4875 Lotus Domino Server R5 on IBM RS/6000: Installation Customization and Administration, SG24-5138 Porting Applications to the OpenEdition Platform, GG24-4473 Accessing OS/390 OpenEdition MVS from the Internet , SG24-4721 TCP/IP Tutorial and Technical Overview, published by Prentice Hall, ISBN 0-13-460858-5 or GG24-3376 TCP/IP for MVS Implementation Guide, SG24-3687 Selecting a Server - The Value of S/390 , SG24-4812

I.2 Lotus publications


These books are shipped with the Lotus Domino for S/390 Release 4.5 server code CD-ROM: Lotus Domino for S/390 Install Guide for Servers (part number AB0999) Lotus Domino for S/390 Release 4.51 Release Notes (part number AA0814)

Copyright IBM Corp. 1999

423

The following Lotus Notes Release 4.5 books: Administrator's Guide (part number 12755) Working with Lotus Notes and the Internet (part number 12763) Deployment Guide (part number 12757) Network Configuration Guide (part number 12756) Database Manager's Guide (part number 12751) Migration Guide (part number 12761)
I.2.1 Lotus documentation online

Lotus documentation is available online after the product has been installed. The database name is listed after the title of the documentation. Domino 1.5 User's Guide, domguide.nsf Notes Help, help4.nsf Notes Help Lite, helplt4.nsf Release Notes: Domino/Notes 4.5 , readme.nsf Install Guide for Servers, doc/srvinst.nsf Install Guide for S/390 Server, doc/srvs390.nsf Install Guide for Workstations, doc/wksinst.nsf Lotus Notes and the Internet , doc/internet.nsf Notes Administration Help, doc/helpadmn.nsf Notes Migration Guide, doc/migrate.nsf

I.3 IBM Redbooks collections


Redbooks are also available on the following CD-ROMs. Click the CD-ROMs button at http://www.redbooks.ibm.com/ for information about all the CD-ROMs offered, updates and formats.
CD-ROM Title
System/390 Redbooks Collection Networking and Systems Management Redbooks Collection Transaction Processing and Data Management Redbooks Collection Lotus Redbooks Collection Tivoli Redbooks Collection AS/400 Redbooks Collection Netfinity Hardware and Software Redbooks Collection RS/6000 Redbooks Collection (BkMgr Format) RS/6000 Redbooks Collection (PDF Format) Application Development Redbooks Collection IBM Enterprise Storage and Systems Management Solutions

Collection Kit Number SK2T-2177 SK2T-6022 SK2T-8038 SK2T-8039 SK2T-8044 SK2T-2849 SK2T-8046 SK2T-8040 SK2T-8043 SK2T-8037 SK3T-3694

I.4 Other resources


These publications are also relevant as further information sources: OS/390 An Introduction and Release Guide, GC28-1725 OS/390 Planning for Installation, GC28-1726
424

Lotus Domino for S/390 R5 Installation, Customization and Administration

OS/390 UNIX System Services Planning, SC28-1890 OS/390 UNIX System Services User's Guide, SC28-1891 OS/390 UNIX System Services Command Reference, SC28-1892 OS/390 UNIX System Services Messages and Codes, SC28-1908 OS/390 MVS System Messages, Volume 2 (ASB - EWX), GC28-1785 OS/390 MVS: System Codes, GC28-1780 OS/390 MVS Planning: Workload Management , GC28-1761 OS/390 MVS Initialization and Tuning Reference, SC28-1752 OS/390 Information Roadmap, GC28-1727 Security Server (RACF) System Programmer's Guide, SC28-1913 Processor Resource/Systems Manager Planning Guide, GA22-7123 TCP/IP for MVS: Planning and Migration Guide, SC31-7189 IBM TCP/IP for MVS:Customization and Administration Guide, SC31-7134 IBM TCP/IP Version 3 for UNIX System Services MVS: Application Features Guide, SC31-8069 TCP/IP Performance Tuning Guide, SC31-7188 VTAM AnyNet: Guide to Sockets over SNA , SC31-8371 DFSMSdfp Storage Administration Reference, SC26-4920 DFSMS/MVS V1R3 DFSMSdss Storage Administration Reference, SC26-4929 DFSMS/MVS Network File System User's Guide, SC26-7028 ADSM V2 Using the UNIX Backup-Archive Client , SH26-4052 ADSM V2 Using the Microsoft Windows Backup-Archive Client , SH26-4056 NetView Customization: Using Assembler, SC31-6090 NetView Customization: Using Assembler Version 3, SC31-8053 OS/390 V2R6.0 eNetwork Communications Server IP: Planning and Migration Guide, SC31-8512 OS/390 V2R6.0 eNetwork Communications Server IP: Configuration, SC31-8513 OS/390 eNetwork Communications Server V2R5 TCP/IP Implementation Guide Volume 1: Configuration and Routing, SG24-5227 OS/390 eNetwork Communications Server V2R5 TCP/IP Implementation Guide Volume 2: OpenEdition Applications, SG24-5228 OS/390 eNetwork Communications Server V2R5 TCP/IP Implementation Guide Volume 3: MVS Applications, SG24-5229 These publications are from the International Technology Group: Cost of Messaging: Comparative Study of the S/390 - Lotus Domino Solution Domino for S/390 - The Business Case

Related publications

425

I.5 Referenced Web sites


These Web sites are also relevant as further information sources: IBM site for Lotus Domino for S/390 http://www.s390.ibm.com/products/domino OS/390 UNIX System Services S/390 Partners in Development IBM Home Page Lotus Home Page IBM Networking
http://www.s390.ibm.com/oe/ http://www.s390.ibm.com/products/s390da/ http://www.ibm.com/ http://www.lotus.com/ http://www.networking.ibm.com/

426

Lotus Domino for S/390 R5 Installation, Customization and Administration

How to Get ITSO Redbooks


This section explains how both customers and IBM employees can find out about ITSO redbooks, redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided. Redbooks Web Site http://www.redbooks.ibm.com/ Search for, view, download, or order hardcopy/CD-ROM redbooks from the redbooks Web site. Also read redpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbooks site. Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapters will be published this way. The intent is to get the information out much quicker than the formal publishing process allows. E-mail Orders Send orders by e-mail including information from the redbooks fax order form to: In United States Outside North America Telephone Orders United States (toll free) Canada (toll free) Outside North America 1-800-879-2755 1-800-IBM-4YOU Country coordinator phone number is in the How to Order section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl/

e-mail address usib6fpl@ibmmail.com Contact information is in the How to Order section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl/

Fax Orders United States (toll free) Canada Outside North America 1-800-445-9269 1-403-267-4455 Fax phone number is in the How to Order section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl/

This information was current at the time of publication, but is continually subject to change. The latest information may be found at the redbooks Web site.

IBM Intranet for Employees


IBM employees may register for information on workshops, residencies, and redbooks by accessing the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical professionals; click the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements.

Copyright IBM Corp. 1999

427

IBM Redbook Fax Order Form


Please send me the following:
Title Order Number Quantity

First name

Last name

Company

Address

City

Postal code

Country

Telephone number Invoice to customer number

Telefax number

VAT number

Credit card number

Credit card expiration date

Card issued to

Signature

We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not available in all countries. Signature mandatory for credit card payment.

428

Lotus Domino for S/390 R5 Installation, Customization and Administration

Glossary
ACL. Access control list. A list of database users (individual users, Lotus Domino servers, and groups of users and/or servers) created and updated by the database manager. The ACL specifies which users can access the database and what tasks they can perform. address space. In ESA/390, the range of virtual storage addresses that provide each user with a unique address space and which maintains the distinction between programs and data within that space. ADSM. ADSTAR Distributed Storage Manager, now known as Tivoli Storage Management. A Tivoli product for distributed file backup, restore, archive and more. AIX. Advanced Interactive Executive (One of IBM's implementations of UNIX) APAR. Authorized program analysis report. A report of a problem caused by a suspected defect in a current unaltered release of a program. ASCII. American National Standard Code for Information Interchange. CICS. Customer Information Control System. An IBM licensed program that enables transactions entered at remote terminals to be processed concurrently by user-written application programs. It includes facilities for building, using, and maintaining data bases. CLIST (command list). A data set in which commands and possibly subcommands and data are stored for subsequent execution. control block. A storage area used by a computer program to hold control information. DAS. Domino Advanced Server DASD. Direct access storage device. A device in which access time is effectively independent of the location of the data. DNN. Domino Named Network. DNS. Domain Name System. A function to associate names and addresses on Internet domain servers. Domain. A Domino domain is a collection of Domino servers and users that share a common Domino Directory. The primary function is mail routing. Users' domains are determined by the location of their server-based mail files. DPAR. Domino Partition. Also called a Notes Partition (NPAR), it is another copy of the Domino server running on the same system or LPAR. It uses the same level of code as the other partitioned Domino servers. encryption. The scrambling or conversion of data, prior to transmission, to a secret code that masks the meaning of the data to any unauthorized recipient. FTP. File transfer program HFS. Hierarchical File System (DFSMS/MVS, POSIX 1003.1(a) compliant file system) HTML. Hypertext Markup Language HTTP. Hypertext Transmission Protocol - An Internet protocol used to transfer files from one computer to another. IBM. International Business Machines Corporation. ICM - Internet Cluster Manager - Domino component for failover and load balancing of HTTP clustering. IMAP. Internet Message Access Protocol. A mail protocol that allows clients to retrieve mail from a host mail server. IMAP is similar to POP3 but has additional features. For example, it supports three modes of mailbox access. You can enable IMAP on a Domino server. The latest level to-date is IMAP4. I/O. Input/output IPL. Initial program load. The initialization procedure that causes an operating system to start operation. ITSO. International Technical Support Organization LAN. Local area network. A data network located on the user's premises in which serial transmission is used for direct data communication among data stations. It services a facility without the use of common carrier facilities. LDAP. Lightweight Directory Access Protocol. A set of protocols for accessing information directories. LDAP is based on the X.500 protocol, but supports TCP/IP, which is necessary for Internet access. Because it's a simpler version of X.500, LDAP is sometimes called X.500-lite. You can enable LDAP on a Domino server to allow LDAP clients to access information in Domino Directory, for example, e-mail addresses. LMBCS - Lotus Multibyte Character Set - The format in which Notes stores all internal text, except file attachments and objects. As a result, any user can edit, forward, and mail documents and work with databases in any language. All text leaving the system -- that is, displayed, printed, and exported -- is translated from LMBCS to the appropriate character set. LMBCS supports Western and Eastern European, North American, and Asian languages. Logical partition. In LPAR mode, a subset of the processor unit resources that is defined to support the operation of a system control program (SCP). Logically partitioned mode (LPAR). A mode that allows the operator to allocate hardware resources of the processor unit among several logical partitions. Lotus. Lotus Development Corporation (software developer of Domino and Notes)

Copyright IBM Corp. 1999

429

LotusScript. A version of BASIC that offers not only standard capabilities of structured programming languages, but a powerful set of language extensions that enable object-oriented development within and across products. Its interface to Notes is through predefined object classes. LPAR. Logical Partition. A System/390 capability to divide up the processors, memory and channels so that several operating system images can run independently on the same machine LS:DO. The ODBCConnection, ODBCQuery, and ODBCResultSet classes, collectively called the LotusScript Data Object (LS:DO), provide properties and methods for accessing and updating tables in external databases through the ODBC (Open Database Connectivity) Version 2.0 standard. MIME. Multipurpose Internet Mail Extensions. Software that allows you to attach non-text files to Internet mail messages. Non-text files include graphics, spreadsheets, formatted word-processor documents, and sound files. MTA. Mail transfer agent - A message transfer agent, also called a gateway, is a program that translates messages between mail formats. NAB. Notes Name and Address Book, or Personal Address Book (PAB). Now called the Domino Directory. NetView. An IBM licensed program used to monitor a network, manage it, and diagnose its problems. NFS. Network File System (USA, Sun Microsystems, Inc.) NNN. Notes Named Network. Now DNN or Domino Named Network. NNS. Notes Name Service. Domino service for converting Fully Qualified Domain Names or Host names to a TCP/IP address Notes RPC. Notes remote procedure call. This is the architectural layer of Notes used for all Notes-to-Notes communication. You can set up either the HTTP or the SOCKS proxy to work with RPC NPAR. Notes Partitioned Server. See DPAR. NSF. The file extension for a Notes database file (.NSF). A database file contains the data for an application. Its structure is composed of forms, fields, folders, views, and other presentation features, such as a navigator and a database icon. NTF. The file extension for a Notes template file (.NTF). A template file contains the structure for the database -- that is, forms, folders, and views -- but does not contain documents. Domino Designer comes with a collection of templates that you can use to create system and application databases. NTI . Notes Transport Interface - Component of Domino Server that manages communications.

ODBC. Open Database Connectivity. A standard developed by Microsoft for accessing external data. ODBC has four components: the ODBC-enabled application, the ODBC Driver Manager, ODBC drivers, and data sources. Lotus Notes is an ODBC-enabled application. ODS. On Disk Structure - The format in which a Notes database is physically stored on disk. Also called a database format. In Release 5, the ODS version of a database is listed on the Info tab of the Database Properties box. PAB. Public (Name and) Address Book POP. Post Office Protocol. A mail protocol that allows clients running it to retrieve mail from a host mail server also running the protocol. You can enable POP3 on a Domino server. The latest level to-date is POP3. Processor Resource/Systems Manager (PR/SM). A function that allows the processor unit to operate several system control programs (SCPs) simultaneously in LPAR mode. It provides for logical partitioning of the real machine and support of multiple preferred guests. PTF. Program Temporary Fix. A temporary solution or by-pass of a problem diagnosed by IBM as resulting from an error in a current unaltered release of the program. QMR. Quarterly Maintenance Release - Lotus software upgrade package to get serious or widespread fixes to customers earlier than the next QMU QMU. Quarterly Maintenance Upgrade. Lotus software upgrade package to a given release and designated by a letter, for example 4.5.4a SCIP. Session Control Inbound Processing facility SIMS. Support Information Management System Lotus internal data bases for tracking problems SMF. System Management Facilities. OS/390 facility for recording performance and capacity data. S/MIME - Secure/MIME. A secure version of the MIME protocol that allows users to send encrypted and electronically signed mail messages, even if users have different mail programs. SDSF. Spool Display Search Facility. OS/390 tool for JES2 systems that allows a TSO user to view and route output from the JES2 spool and to view the SYSLOG and issue commands to OS/390 if authorized. SMTP. Simple Mail Transfer Protocol - The Internet's standard host-to-host mail transport protocol. It traditionally operates over TCP, using port 25. SMTP does not provide any mailbox facility, nor any special features beyond basic mail transport. SNA. Systems Network Architecture. The description of the logical structure, formats, protocols, and operational sequences for transmitting information

430

Lotus Domino for S/390 R5 Installation, Customization and Administration

units through, and controlling the configuration and operation of, networks.

SNMP. Simple Network Management Protocol. A TCP/IP protocol to enable managing remote hosts SPR. Software Problem Record. Lotus software problem record tracking record SSL. Secure Sockets Layer. Security protocol for the Internet and intranets that provides communications privacy and authentication for Domino server tasks that operate over TCP. S/390. System/390. A computer system architecture which includes the associated I/O devices and operating system(s). TCB. Task Control Block. An OS/390 construct that represents a dispatchable unit of work. One address space can create multiple tasks. A USS thread creates a TCB in OS/390. TCP/IP. Transmission Control Protocol/Internet Protocol. A public domain networking protocol with standards maintained by US Department of Defense to allow unlike vendor systems to communicate. Tivoli Storage Management. Formerly known as ADSM, it is a set of backup and recovery programs which lets you align storage management policies with business practices. Tivoli Data Protection for Lotus Domino. A program in the Tivoli Storage Management set that allows you to back up and restore Domino databases using the features of transaction logging. TSO. Time Sharing Option. The principal interactive user interface into OS/390. UNIX. An operating system developed at Bell Laboratories (trademark of UNIX System Laboratories, licensed exclusively by X/Open Company, Ltd.) URL. Uniform Resource Locator. VTAM. Virtual telecommunication access method. This program provides for workstation and network control. It is the basis of a System Network Architecture (SNA) network. It supports SNA and certain non-SNA terminals. VTAM supports the concurrent execution of multiple telecommunications applications and controls communication among devices in both single-processors and multiple processors networks.

431

Lotus Domino for S/390 R5 Installation, Customization and Administration

432

Lotus Domino for S/390 R5 Installation, Customization and Administration

Index
$ChargeRead 225, 228 $ChargeWrite 225, 228 .ns4 extension 268 /bin/sh 68 /etc/hosts 194 /etc/inetd.conf 61 /etc/services 61 /notesdata 37

Symbols

Numerics
24-hour access S/390 20 3172 54 3270 44 3390 Model 3 33 3390 Model 9 33 37x5 communications controller 54 37x5 communications controller 54

A
accept newsfeed 177 access 24 hours 20 control database 375 Domino server 371 level 65, 369 Internet name 375 password 375 permission Web 163 rate 20 remote data 24 server 371 Web browser upgrade 244 server 371 access control list 368369 NNTP 179 replication 368 See also ACL accessibility 23 ACL 36, 369 anonymous user 375 default 375 HTTP access 163 read public documents 375 replication 203 See also access control list write public documents 375 active sessions maximum 376 ActiveX Domino Designer 11 add

group to Domino Directory 366 server to cluster 211 third party during upgrade 252 additional server 88 additional services 108 address and port number 84 headers, new in Notes R5 7 IP 190 space Domino 312, 314 ID 315 multiple 62 name of 315 region size 320 admin4.nsf upgrade 252 admin4.ntf directory 248 administration 26 client 127, 144 creating clusters 209 Win32 platform 325 cost 16 easier 4 effort 16, 18 Lotus Notes 14 preparing 26 server 209 upgrade 232 simple tasks 325 webadmin.nsf 352 administration requests database 252 upgrade 252 template 253 Administrator client ID file 371 ID saving 118 identity 111 adminp 413 ADSM 285, 293 backup considerations for Domino 295 backup options dynamic 286 shared dynamic 286 shared static 286 static 286 client 286 Disaster Recovery Manager 294 OS/390 UNIX Client 286 performance considerations 294 ADSTAR Distributed Storage Manager 285 See also Tivoli Data Protection AF_INET 318 address family 54, 320 socket support 320 AF_UNIX 317, 320 agent

Copyright IBM Corp. 1999

433

billing 229 billingclass 225 restrictions 372 agents 52 DIIOP 52 HTTP 52 JAVA 52 AIX available platform 13 alarm interval 254 alias names 372 All-in-1 46 LMS 46 allocating HFS data sets 51 space 51 ALLOCxx 59 ALOCPROD