P. 1
Administering_the_Domino_System_-_Vol._2

Administering_the_Domino_System_-_Vol._2

|Views: 55|Likes:
Published by api-3754071

More info:

Published by: api-3754071 on Oct 15, 2008
Copyright:Attribution Non-commercial

Availability:

Read on Scribd mobile: iPhone, iPad and Android.
download as PDF, TXT or read online from Scribd
See more
See less

05/09/2014

pdf

text

original

software

Lotus Domino 6

Administering the Domino System, Volume 2

Disclaimer THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED “AS IS” WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, IBM DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE. Copyright Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of IBM, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software. © Copyright IBM Corporation 1985, 2002 All rights reserved. Lotus Software IBM Software Group One Rogers Street Cambridge, MA 02142 US Government Users Restricted Rights — Use, duplication or disclosure restricted by GS ADP Schedule Contract with IBM Corp. List of Trademarks 1-2-3, cc:Mail, Domino, Domino Designer, Freelance Graphics, iNotes, Lotus, Lotus Discovery Server, Lotus Enterprise Integrator, Lotus Mobile Notes, Lotus Notes, Lotus Organizer, LotusScript, Notes, QuickPlace, Sametime, SmartSuite, and Word Pro are trademarks or registered trademarks of Lotus Development Corporation and/or IBM Corporation in the United States, other countries, or both. AIX, AS/400, DB2, IBM, iSeries, MQSeries, Netfinity, OfficeVision, OS/2, OS/390, OS/400, S/390, Tivoli, and WebSphere are registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Pentium is a trademark of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. All other trademarks are the property of their respective owners.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . xv Volume 1 1 Deploying Domino . . . . . . . . . . . . 1-1
Starting and shutting down the Domino server . . . . . . . . . . . . . . . . . .

...

3-46

4 Setting Up Server-to-Server Connections . . . . . . . . . . . . . . . . . . . 4-1

. . . . . . . . 1-1 Building the Domino environment . . . . . . 1-14
Guidepost for deploying Domino

2 Setting Up the Domino Network . . . . . . . . . . . . . . . . . . . . . . 2-1

. . . . . . . . . . . 2-1 Network security . . . . . . . . . . . . . . . . . . 2-6 Planning the TCP/IP network . . . . . . . . . 2-10 Planning the NetBIOS network . . . . . . . . 2-26 Planning the IPX/SPX network . . . . . . . . 2-29 Setting up Domino servers on the network . . 2-32 Server setup tasks specific to TCP/IP . . . . 2-43 Server setup tasks specific to NetBIOS . . . . 2-58 Server setup tasks specific to IPX/SPX . . . . 2-61 NOTES.INI settings for networks . . . . . . . 2-64
Lotus Domino and networks

. . . . . 4-1 How a server connects to another server . . . 4-4 Internet connections . . . . . . . . . . . . . . . 4-21 Passthru servers and hunt groups . . . . . . 4-23 Planning the use of passthru servers . . . . . 4-25 Setting up a server as a passthru server . . . 4-27 Setting up a server as a passthru destination . . 4-28 Planning for modem use . . . . . . . . . . . . 4-33 Commands for acquire and connect scripts . . 4-53 Connecting Notes clients to servers . . . . . . 4-55
Planning server-to-server connections

5 Setting Up and Managing Notes Users . . . . . . . . . . . . . . . . . . . 5-1
Setting up Notes users

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

5-1 5-38 5-41 5-54 5-85 5-87

3 Installing and Setting Up Domino Servers . . . . . . . . . . . . . . . . 3-1

Adding an alternate language and name to a user ID . . . . . . . . . . . . . .

... Server installation . . . . . . . . . . . . . . . . . . The Domino Server Setup program . . . . . . .
Installing and setting up Domino servers Using Domino Off-Line Services (DOLS) and iNotes Web Access . . . . . .

3-1 3-3 3-8 3-10 3-17 3-28 3-29 3-34

... Setting up client installation for users . . . . Managing users . . . . . . . . . . . . . . . . . . License Tracking . . . . . . . . . . . . . . . . . Custom welcome page deployment . . . . .

... Using the Domino Server Setup program . . The Certification Log . . . . . . . . . . . . . . . Server registration . . . . . . . . . . . . . . . . Optional tasks to perform after server setup . .

6 Setting Up and Managing Groups . . . . . . . . . . . . . . . . . . . . . . . 6-1

..................... Creating and modifying groups . . . . . . . . . Managing groups . . . . . . . . . . . . . . . . . . Assiging a policy to a group . . . . . . . . . . .
Using groups

6-1 6-2 6-8 6-9

iii

7 Creating Replicas and Scheduling Replication . . . . . . . . . . 7-1

Collecting detailed information from user calendars . . . . . . . . . . . . . . . .

........................ How server-to-server replication works . . . .
Replicas Guidelines for setting server access to databases . . . . . . . . . . . . . Setting up a database ACL for server-to-server replication Table of replication settings

7-1 7-3 7-5

......

. . . . . . . . 7-6 . . . . . . . . . . 7-11
7-17 7-20 7-22 7-23 7-24 7-27 7-28 7-29 7-30 7-31 7-31 7-32 7-33 7-34

Specifying replication settings for one replica . . . . . . . . . . . . . . . .

.... Scheduling server-to-server replication . . . Customizing server-to-server replication . . Specifying replication direction . . . . . . . . Scheduling times for replication . . . . . . . . Replicating only specific databases . . . . . . Replicating databases by priority . . . . . . . Limiting replication time . . . . . . . . . . . . Using multiple replicators . . . . . . . . . . . Refusing replication requests . . . . . . . . . . Forcing immediate replication . . . . . . . . . Disabling database replication . . . . . . . . . Forcing a server database to replicate . . . .
Viewing replication schedules and topology maps . . . . . . . . .

. . 8-20 9 Using Policies . . . . . . . . . . . . . . . 9-1 Policies . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Policy hierarchy and the effective policy . . . 9-3 Planning and assigning policies . . . . . . . . . 9-6 Creating policies . . . . . . . . . . . . . . . . . . 9-7 Mail archiving and policies . . . . . . . . . . . 9-22 Managing policies . . . . . . . . . . . . . . . . 9-35 Viewing policy relationships . . . . . . . . . . 9-37 10 Setting Up Domain Search . . . 10-1 Domain Search . . . . . . . . . . . . . . . . . . . 10-1 Planning the Domain Index . . . . . . . . . . 10-4 Creating and updating the Domain Index . 10-14 Customizing Domain Search forms . . . . . 10-18 Setting up Notes users for Domain Search . 10-19 Setting up Web users for Domain Search . 10-20 Using content maps with Domain Search . 10-21 NOTES.INI settings for Domain Search . . 10-23
11 Setting Up Domino Off-Line Services . . . . . . . . . . . . . . . . . . . . . 11-1
Domino Off-Line Services

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

11-1

......

12 Planning the Service Provider Environment . . . . . . . . . . 12-1
Planning the xSP server environment

8 Setting Up Calendars and Scheduling . . . . . . . . . . . . . . . . . . . . 8-1
Calendars and scheduling Setting up scheduling

.... ..

12-1 12-4 12-16

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

8-1 8-5 8-7

Using Domino features in a hosted server environment . . . . . . . . . . . . . . Example of planning a hosted environment . . . . . .

Setting up the Resource Reservations database . . . . . . . . . . . . . . Creating Site Profile and Resource documents . . . . . . . . . .

.........

13 Setting Up the Service Provider Environment . . . . . . . . . . 13-1
Setting up the service provider environment . Installing the first server or additional servers for hosted environments Setting up a hosted organization

. . . . . . . . 8-9 Editing and deleting Resource documents . . 8-13 Creating Holiday documents . . . . . . . . . . 8-17
iv Administering the Domino System, Volume 2

.

13-1 13-2 13-3

... .......

Setting up the Domino certificate authority for hosted organizations Using policies in a hosted environment

.. ...

13-3 13-4

15 Setting Up the Administration Process . . . . . . . . 15-1

What happens when you register a hosted organization? . . . . . . . . . . . . . . .

. 13-5 Example of registering a hosted organization . . 13-8 Registering a hosted organization . . . . . 13-11
Using Internet and Web Site documents in a hosted environment . . . . . . . . . 13-18 Global Web Settings documents and the service provider environment . . Configuring activity logging for billing hosted organizations . . . . . . .

.......... Setting up the Administration Process . . . .
The Administration Process Administration Process support of secondary Domino Directories

15-1 15-5 15-7 15-8 15-13 15-19 15-29 15-35 15-36

..... ..

Processing administration requests across domains . . . . . . . . . . . . . . . . . Setting up ACLs for the Administration Process . . . . . . . . . . . . . . . . .

..

13-21 13-23

...

14 Managing a Hosted Environment . . . . . . . . . . . . . . . . . 14-1
Maintaining hosted organizations

.. The Administration Requests database . . Customizing the Administration Process . Adminstration Process Statistics . . . . . . . Administration request messages . . . . . .

......

14-1

Adding a hosted organization to an additional server to provide new Web applications . . . . . . . . . Deleting a hosted organization Temporarily disabling services for a hosted organization . . . . . .

16 Setting Up and Using Domino Administration Tools . . . 16-1

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

14-2 14-3 14-4 14-4 14-5 14-10 14-11 14-12 14-12 14-14 14-14 14-15

Enabling anonymous access to a hosted organization’s database . . . . . .

........... Installing the Domino Administrator . . . . Setting up the Domino Administrator . . . . Starting the Domino Administrator . . . . . Navigating Domino Administrator . . . . . .
The Domino Administrator Selecting a server to administer in the Domino Administrator . . . . .

16-1 16-1 16-2 16-2 16-3

Moving a hosted organization to another server . . . . . . . . . . . . . . . . . . . Removing a hosted organization from a backup or load-balancing server . Restoring a hosted environment after a server crash . . . . . . . . . . . . . Using a browser to access a hosted organization’s Web site . . .

..

...

.....

. . . . . 16-4 Setting Domino Administration preferences . . 16-5 Domino Administrator tabs . . . . . . . . . 16-13 Web Administrator . . . . . . . . . . . . . . . 16-17 Setting up the Web Administrator . . . . . 16-17 Starting the Web Administrator . . . . . . . 16-22 Using the Web Administrator . . . . . . . . 16-23
The Server Controller and the Domino Console . . . . . . . . . . . . . . .

Using the Resource Reservations database in a hosted environment . . . . . . .

. Viewing hosted organizations . . . . . . . . Managing users at a hosted organization .
Using the Web Administrator to manage users at a hosted organization . . .

...

16-28

17 Using Domino with Windows Synchronization Tools . . 17-1
Setting up Windows NT User Manager

... ..

17-1 17-6

.

Setting policy-based registration options for use with Notes synchronization

Contents v

Using the Windows NT Performance Monitor to view Domino . . . Setting up Domino Active Directory synchronization . . . . . . . .

Customizing the Directory Profile

.....

19-16

....

17-23

Scheduling replication of the Domino Directory . . . . . . . . . . . . .

. . . . . 17-25 18 Planning Directory Services . . 18-1 Overview of Domino directory services . . . 18-1
Using directory servers in a Domino domain . . . . . . . . . . . . . . .

..... Planning LDAP features . . . . . . . . . . . . . Planning directory access control . . . . . . .
Planning new entries in the Domino Directory . . . . . . . . . . . . .

18-1 18-3 18-7 18-7 18-9 18-10 18-12 18-15 18-18 18-19 18-20

. . . . 19-17 20 Setting Up the LDAP Service . . 20-1 The LDAP service . . . . . . . . . . . . . . . . . 20-1 How the LDAP service works . . . . . . . . . 20-2 Setting up the LDAP service . . . . . . . . . . 20-7 Starting and stopping the LDAP service . . . 20-8
Customizing the LDAP service configuration . . . . . . .

..... .

Planning the management of entries in the Domino Directory . . . . . . . . . . . . Planning directory services for Notes clients . . . . . . . . . . . . . . . Planning directory services in a multiple-directory environment Directory search order

....

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

Planning internationalized directory services . . . . . . . . . . . . . .

.... Planning directory customization . . . . . . Directory services terms . . . . . . . . . . . .

. . . . . . . . . 20-9 Setting up clients to use the LDAP service . 20-34 Using LDAP to search a Domain index . . 20-36 Monitoring the LDAP service . . . . . . . . 20-37 NOTES.INI settings for the LDAP service . 20-41 RFCs supported by the LDAP service . . . 20-42 21 Managing the LDAP Schema . . 21-1 LDAP schema . . . . . . . . . . . . . . . . . . . 21-1 The Domino LDAP schema . . . . . . . . . . . 21-2 The schema daemon . . . . . . . . . . . . . . . 21-5 Domino LDAP Schema database . . . . . . . 21-7 Methods for extending the schema . . . . . 21-10
Extending the schema using the Schema database . . . . . . . . . . . . . . . .

19 Setting Up the Domino Directory . . . . . . . . . . . . . . . . . . . . . 19-1
The Domino Directory

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

19-1 19-2 19-2 19-5

Setting up the Domino Directory for a domain . . . . . . . . . . . . . . . .

.. Schema-checking . . . . . . . . . . . . . . . . Searching the root DSE and schema entry .
NOTES.INI settings related to the schema daemon . . . . . . . . . . . . . . . . .

21-13 21-18 21-19

Using a central directory architecture in a Domino domain . . . . . . . . . . . . Managing Domino Directories in a central directory architecture . . . . . . . . Controlling access to the Domino Directory . . . . . . . . . . . Corporate hierarchies

. 21-21 22 Using the ldapsearch Utility . . 22-1
Using the ldapsearch utility to search LDAP directories . . . . . . . .

. . . . . . . 19-9 . . . . . . . . . . . . . 19-13 .
19-15

..... Table of ldapsearch parameters . . . . . . . . Using search filters with ldapsearch . . . . .
Using ldapsearch to return operational attributes . . . . . . . . . . . . . . Examples of using ldapsearch

22-1 22-2 22-4 22-5 22-6

Setting up Notes clients to use a directory server . . . . . . . . . . . . . . . . . . .

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

vi Administering the Domino System, Volume 2

23 Setting Up Directory Assistance . . . . . . . . . . . . . . . . . . . 23-1

Specifying the Domino Directories for the Dircat task to aggregate . . . . . . . Controlling which information is aggregated into a directory catalog Full-text indexing directory catalogs Planning issues specific to Extended Directory Catalogs . . . . . . . Planning issues specific to condensed Directory Catalogs . . . . . . . Multiple directory catalogs Overview of setting up a condensed Directory Catalog . . . . . . . The Dircat task

.

24-15 24-16 24-25 24-26 24-29 24-33 24-34 24-45

. . . . . . . . . . . . . . . 23-1 How directory assistance works . . . . . . . . 23-2 Directory assistance services . . . . . . . . . . 23-3 Directory assistance concepts . . . . . . . . 23-12 Directory assistance and naming rules . . . 23-12 Directory assistance and domain names . . 23-18
Directory assistance Directory assistance and failover for a directory . . . . . . . . . . . . . . . Directory assistance for an Extended Directory Catalog . . . . . . . .

. .... ....

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

...

23-19 23-22 23-24 23-26 23-29 23-29 23-51 23-60

.... .

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

Directory assistance in conjunction with a condensed Directory Catalog . . . . Directory assistance for the primary Domino Directory . . . . . . .

Opening the configuration document for a directory catalog . . . . . . . . . . . . . 24-48

..... Number of directory assistance databases . Setting up directory assistance . . . . . . . . Directory assistance examples . . . . . . . . Monitoring directory assistance . . . . . . .

. . . . . . . . 24-49 25 Setting Up Extended ACLs . . . 25-1 Extended ACL . . . . . . . . . . . . . . . . . . . 25-1
Monitoring directory catalogs How other database security features restrict extended ACL access settings . . . . . . . . . . . . . . .

24 Setting Up Directory Catalogs . . . . . . . . . . . . . . . . . . . . . 24-1

................. Condensed Directory Catalogs . . . . . . . .
Directory catalogs Directory catalogs on servers compared to directory assistance for individual Domino Directories . . . . . . . . . .

24-1 24-2

.. Extended Directory Catalogs . . . . . . . . . . Overview of directory catalog setup . . . . . Planning directory catalogs . . . . . . . . . . .
Directory catalogs and client authentication . . . . .

24-4 24-5 24-8 24-9 24-9 24-14 24-14

. . . . . 25-2 Elements of an extended ACL . . . . . . . . . 25-3 Extended ACL access settings . . . . . . . . . 25-3 Extended ACL subject . . . . . . . . . . . . . . 25-9 Extended ACL target . . . . . . . . . . . . . . 25-12 Extended ACL examples . . . . . . . . . . . 25-19 Extended ACL guidelines . . . . . . . . . . . 25-22
Setting up and managing an extended ACL . . . . . . . . . . . . . . . . .

...

25-22

26 Overview of the Domino Mail System . . . . . . . . . . . . . . . . . . . . . . 26-1
Messaging overview

..........

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

26-1 26-2 26-5 26-17

Directory catalogs and Notes mail encryption . . . . . . . . . .

...... Picking the server(s) to run the Dircat task .

Supported routing, format, and access protocols . . . . . . . . . . . . . . .

.... The Domino mail server and mail routing . .
Overview of routing mail using Notes routing . . . . . . . . . . . . . . . .

...

Contents vii

Overview of routing mail using SMTP The Domain Name System (DNS) and SMTP mail routing . . . . . . . .

...

26-21

Restricting outbound mail routing Mail journaling

. . . . . 28-98 . . . . . . . . . . . . . . . . . 28-105

. . . 26-25 27 Setting Up Mail Routing . . . . . 27-1 The Domino mail router . . . . . . . . . . . . . 27-1 Planning a mail routing topology . . . . . . . 27-2 Sample mail routing configurations . . . . . 27-9
Creating a Configuration Settings document . . . . . . . . . . . Setting up Notes routing

Setting inbound and outbound MIME and character set options . . . . . . . . .

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

27-18 27-20 27-37 27-42 27-58 27-59

Configuring Domino to send and receive mail over SMTP . . . . . . . . . . . . Setting up how addresses are resolved on inbound and outbound mail . . . . Configuring Domino to send mail to a relay host or firewall . . . . . . .

... Routing mail over transient connections .

28 Customizing the Domino Mail System . . . . . . . . . . . . . . . . . . 28-1

. . . . . . . . . . . . . . . . . 28-1 Controlling messaging . . . . . . . . . . . . . . 28-1 Improving mail performance . . . . . . . . . . 28-2 Controlling message delivery . . . . . . . . . 28-8 Setting server mail rules . . . . . . . . . . . . 28-20 Customizing message transfer . . . . . . . . 28-26 Setting transfer limits . . . . . . . . . . . . . 28-33
Customizing mail Setting advanced transfer and delivery controls . . . . . . . . . . . . . . .

. 28-115 29 Setting Up Shared Mail . . . . . . 29-1 Shared mail overview . . . . . . . . . . . . . . 29-1 Setting up shared mail databases . . . . . . . 29-5 Managing a shared mail database . . . . . 29-11 Disabling shared mail . . . . . . . . . . . . . 29-25 30 Setting Up the POP3 Service . . 30-1 The POP3 service . . . . . . . . . . . . . . . . . 30-1 Setting up the POP3 service . . . . . . . . . . 30-2 Setting up POP3 users . . . . . . . . . . . . . . 30-7 31 Setting Up the IMAP Service . . 31-1 The IMAP service . . . . . . . . . . . . . . . . . 31-1 Setting up the IMAP service . . . . . . . . . . 31-4 Customizing the IMAP service . . . . . . . . 31-5 Setting up IMAP users . . . . . . . . . . . . . 31-22
IMAP settings in the server NOTES.INI file . . . . . . . . . . . . . . . . . . . .

..

31-39

32 Setting Up iNotes Web Access . . . . . . . . . . . . . . . . . . . . . . 32-1

... Customizing Notes routing . . . . . . . . . . Customizing SMTP Routing . . . . . . . . . Changing SMTP port settings . . . . . . . . Restricting SMTP inbound routing . . . . .
Preventing unauthorized SMTP hosts from using Domino as a relay

28-39 28-50 28-57 28-58 28-70 28-75 28-86

. . . . . . . . . . . . . . . . 32-1 iNotes Access for Microsoft Outlook . . . . 32-11 33 Monitoring Mail . . . . . . . . . . . . 33-1 Tools for mail monitoring . . . . . . . . . . . . 33-1 Setting up mail monitoring . . . . . . . . . . . 33-3 Viewing mail usage reports . . . . . . . . . 33-16
iNotes Web Access

34 Setting Up the Domino Web Server . . . . . . . . . . . . . . . . . . . . . . . 34-1
The Domino Web server

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

34-1

.... ..

Enabling DNS blacklist filters for SMTP connections . . . . . . . . . . . . . .

Setting up a Domino server as a Web server . . . . . . . . . . . . . . . . Setting up WebDAV

. . . . . 34-4 . . . . . . . . . . . . . . 34-15

viii Administering the Domino System, Volume 2

................ Web Site rules and global Web settings . . Custom Web server messages . . . . . . . . Improving Web server performance . . . .
Hosting Web sites

34-17 34-34 34-48 34-52

Certificates

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

39-2 39-4

Password-protection for Notes and Domino IDs . . . . . . . . . . . Verifying user passwords during authentication . . . . . . . .

35 Setting Up Domino to Work with Other Web Servers . . . . . . . . 35-1
Setting up Domino to work with other Web servers . . . . . . . . . . . . .

. . . . . . . 39-8 ID recovery . . . . . . . . . . . . . . . . . . . . 39-14 Public key security . . . . . . . . . . . . . . . 39-22
Using cross-certificates to access servers and send secure S/MIME messages Adding cross-certificates to the Domino Directory or Personal Address Book

....

35-1

. .

39-27 39-29

36 Setting Up the Web Navigator . . . . . . . . . . . . . . . . . . . . 36-1

. . . . . . . . . . . . . . . . 36-1 Setting up a Web Navigator server . . . . . . 36-2 Customizing the Web Navigator . . . . . . . 36-6 The Web Navigator database . . . . . . . . . 36-10 Customizing the Web Navigator database . 36-11
The Web Navigator

40 Controlling User Access to Domino Databases . . . . . . . . . . . . 40-1

Volume 2 37 Planning Security . . . . . . . . . . 37-1
Overview of Domino security The Domino security model The Domino security team Security planning checklists

. . . . . . . . . 37-1 . . . . . . . . . . 37-5 . . . . . . . . . . . 37-8 . . . . . . . . . 37-11

. . . . . . . . 40-1 Default ACL entries . . . . . . . . . . . . . . . 40-2 Acceptable entries in the ACL . . . . . . . . . 40-4 Configuring a database ACL . . . . . . . . . 40-11 Access levels in the ACL . . . . . . . . . . . 40-13 Access level privileges in the ACL . . . . . 40-16 User types in the ACL . . . . . . . . . . . . . 40-19 Roles in the ACL . . . . . . . . . . . . . . . . 40-20 Managing database ACLs . . . . . . . . . . . 40-22
The database access control list Using the Administration Process to update ACLs . . . . . . . . . . .

38 Controlling Access to Domino Servers . . . . . . . . . . . . . . . 38-1
Validation and authentication for Notes and Domino . . . . . . . . . . . . . Server access for Notes users, Internet users, and Domino servers . . . Setting up Notes user, Domino server, and Internet user access to a Domino server . . . . . . . . . . .

.... .

40-23 40-24 40-24 40-25 40-28 40-30 40-30

Setting up the Administration Process for database ACLs . . . . . . . . . . . . . Managing database ACLs with the Web Administrator . . . . . . . . . . . . Editing entries in multiple ACLs

...

38-1 38-2

....

. . . . 38-4 Customizing access to a Domino server . . . 38-7 Physically securing the Domino server . . 38-23
39 Protecting and Managing Notes IDs . . . . . . . . . . . . . . . . . . . . 39-1
Domino server and Notes user IDs

.. ...... Enforcing a consistent access control list . Setting up database access for Internet users .
Maximum Internet name-and-password access . . . . . . . . . . . . . . . . . .

..

41 Protecting User Workstations with Execution Control Lists . . . . . 41-1
The execution control list

......

39-1

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

41-1

Contents ix

The administration ECL

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

41-6

Default Domino SSL trusted roots SSL port configuration

42 Setting Up Name-and-Password and Anonymous Access to Domino Servers . . . . . . . . . . . . . . . . . . . . . . 42-1
Name-and-password authentication for Internet/intranet clients . . . . . . Session-based name-and-password authentication for Web clients

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

46-11 46-14 46-20

Managing server certificates and certificate requests . . . .

...

42-1 42-6

Authenticating Web SSL clients in secondary Domino and LDAP directories . . . . . . . . . . . . .

46-25

.....

47 Setting Up Clients for S/MIME and SSL . . . . . . . . . . . . . . 47-1
SSL and S/MIME for clients

Multi-server session-based name-and-password authentication for Web users (single sign-on) . . .

..........

47-1

. Managing Internet passwords . . . . . . . . Anonymous Internet/intranet access . . .
Validation and authentication for Internet/intranet clients . .

42-12 42-24 42-25 42-27

Setting up Notes and Internet clients for SSL authentication . . . . . . . . .

. . . 47-3 Internet certificates for SSL and S/MIME . . 47-5 Setting up Notes clients for S/MIME . . . . 47-13
Dual Internet certificates for S/MIME encryption and signatures . .

......

.... ..

47-17 47-18

43 Encryption and Electronic Signatures . . . . . . . . . . . . . . . . . . . 43-1

Setting up Notes and Internet clients for SSL client authentication . . . . . Using SSL when setting up directory assistance for LDAP directories

..................... Mail encryption . . . . . . . . . . . . . . . . . . Electronic signatures . . . . . . . . . . . . . . .
Encryption

43-1 43-4 43-9

. . . 47-23 48 Rolling Out Databases . . . . . . 48-1
Database design, management, and administration . . . . . . . . .

44 Setting Up a Domino Server-Based Certification Authority . . . . . . . . . . . . . . . . . . . . 44-1
Domino server-based certification authority . . . . . . . . . . . Setting up a server-based Domino certification authority . . .

...... Rolling out a database . . . . . . . . . . . . . . Copying a new database to a server . . . . .
Creating a Mail-In Database document for a new database . . . . . . . . . . . . .

48-1 48-1 48-4 48-5 48-7 48-7

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

44-1 44-5

45 Setting Up a Domino 5 Certificate Authority . . . . . . . . . . . 45-1

.. Adding a database to the Domain Index . . Signing a database or template . . . . . . . .

.... Setting up a Domino 5 certificate authority . .
Using a Domino 5 certificate authority

45-1 45-1

49 Organizing Databases on a Server . . . . . . . . . . . . . . . . . . . . . . . 49-1
Organizing databases on a server

.......

49-1

46 Setting Up SSL on a Domino Server . . . . . . . . . . . . . . . . . . . . . . . 46-1

50 Setting Up and Managing Full-text Indexes . . . . . . . . . . . . . . 50-1
Full-text indexes for single databases

..................... Setting up SSL on a Domino server . . . . . .
SSL security

46-1 46-2

....

50-1

x Administering the Domino System, Volume 2

51 Setting Up Database Libraries and Catalogs . . . . . . . . . 51-1
Database libraries

54 Using IBM Tivoli Analyzer for Lotus Domino . . . . . . . . . . . . . 54-1

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

51-1 51-2 51-3 51-4 51-5

Creating a database library and assigning librarians . . . . . . . . . . . . . . . .

.. Publishing databases in a library . . . . . . . Database catalogs . . . . . . . . . . . . . . . . . Setting up a server’s database catalog . . . .

... Server Health Monitor . . . . . . . . . . . . . . Table of Server Health Monitor statistics . . Table of Server Health Monitor ratings . . . Server Health Monitor configuration . . . . . Using the Server Health Monitor . . . . . . .
IBM Tivoli Analyzer for Lotus Domino Working with Server Health Monitor statistics . . . . . . . . . . . . . .

54-1 54-2 54-3 54-5 54-6 54-8 54-13 54-17 54-18 54-22 54-26 54-27 54-34 54-37 54-48 54-51 54-53 54-61

52 Monitoring the Domino Server . . . . . . . . . . . . . . . . . . . . . . . 52-1

. . . . . . . . 52-1 Monitoring events on the Domino system . . 52-2 Event generators . . . . . . . . . . . . . . . . . 52-3 Event handlers . . . . . . . . . . . . . . . . . . 52-14 Viewing an event report . . . . . . . . . . . . 52-20
Monitoring the Domino system Viewing event messages, causes, and solutions . . . . . . . . . . . . . .

.... Activity Trends . . . . . . . . . . . . . . . . . Setting up Activity Trends . . . . . . . . . .
Activity Trends server and statistics profiles . . . . . . . . . . . . . .

..... Resource balancing in Activity Trends . . .
Setting up resource balancing in Activity Trends . . . . . . . . . . . . . . . . . . Understanding resource-balancing behavior . . . . . . . . . . . . .

....

52-20

.

Customizing the appearance of the Domino server console and Domino Administrator console . . . . . . . .

.....

. Statistics and the Domino system . . . . . . Platform statistics . . . . . . . . . . . . . . . .
Using the Domino Administrator to monitor statistics . . . . . . .

52-21 52-24 52-26 52-31 52-36 52-40 52-43

Analyzing resource-balancing distributions . . . . . . . Domino Change Manager

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

..... Charting statistics . . . . . . . . . . . . . . . . Domino server monitor . . . . . . . . . . . . Profiles and the Domino server monitor .

ACLs for the Domino Change Control database . . . . . . . . . . . . . . . Resource-balancing plans

Setting up plan documents for resource balancing . . . . . . . . . . . . . . .

53 Using the Domino SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . 53-1

55 Transaction Logging and Recovery . . . . . . . . . . . . . . . . . . . . 55-1

........... Configuring the Domino SNMP Agent . . .
The Domino SNMP Agent Using the Domino MIB with your SNMP management station . . . . . . . . . Troubleshooting the Domino SNMP Agent . . . . . . . . . . . . . . .

53-1 53-8 53-21 53-24

............... How transaction logging works . . . . . . . . Planning for transaction logging . . . . . . .
Transaction logging Setting up a Domino server for transaction logging . . .

55-1 55-3 55-4 55-5 55-7

.

.....

......... Changing transaction logging settings . . . .

Contents xi

Disabling transaction logging for a specific database . . . . . . . .

. . . . . . 55-8 View logging . . . . . . . . . . . . . . . . . . . . 55-9 Using transaction logging for recovery . . . 55-9 Fault recovery . . . . . . . . . . . . . . . . . . 55-10 56 Using Log Files . . . . . . . . . . . . 56-1 The Domino server log (LOG.NSF) . . . . . . 56-1
Controlling the size of the log file (LOG.NSF) . . . . . . . . . . The Domino Web server log (DOMLOG.NSF) . . .

59 Maintaining Domino Servers . . 59-1

. . . . . . . . . . . . . . . . . 59-1 Decommissioning a Domain Search server . 59-12 Uninstalling a Domino partitioned server . 59-13
Managing servers

60 Improving Server Performance . . . . . . . . . . . . . . . . . 60-1
Improving Domino server performance Tools for measuring server performance

....... Logging Domino Web server requests . . . .

56-1 56-8

... .. .. . ..

60-1 60-2 60-3 60-5 60-6

Improving basic server performance and capacity . . . . . . . . . . . . . . . . .

. . . . . . . . . . . 56-8 Domino Web server logging to text files . . 56-10
57 Setting Up Activity Logging . . 57-1

Improving partitioned server performance and capacity . . . . . . . . . . . . . . . Improving Agent Manager performance Improving database and Domino Directory performance . . . Tips for tuning mail performance

. . . . . . . . . . . . . . . . . . 57-1 The information in the log file . . . . . . . . . 57-1 Configuring activity logging . . . . . . . . . 57-12 Viewing activity logging data . . . . . . . . 57-13 58 Maintaining Databases . . . . . . 58-1 Database maintenance . . . . . . . . . . . . . . 58-1 The Files tab in the Domino Administrator . . 58-2 Monitoring replication of a database . . . . . 58-6 Replication or save conflicts . . . . . . . . . . 58-8 Monitoring database activity . . . . . . . . . 58-11 Updating database indexes and views . . . 58-14 Managing view indexes . . . . . . . . . . . . 58-23
Activity logging Synchronizing databases with master templates . . . . . . . . . . . . .

. . . . . . . 60-9 . . . . . . 60-11 .. ...
60-13 60-14

Improving Windows NT and Windows 2000 server performance . . . . . Improving UNIX server performance

61 Improving Database Performance . . . . . . . . . . . . . . . . . 61-1
Setting advanced database properties Database properties that optimize database performance . . .

....

61-1

.... Fixing corrupted databases . . . . . . . . . . Using Fixup . . . . . . . . . . . . . . . . . . . Moving databases . . . . . . . . . . . . . . . . Deleting databases . . . . . . . . . . . . . . . Database analysis . . . . . . . . . . . . . . . .

58-24 58-25 58-26 58-33 58-36 58-37

. . . . . . . 61-3 The database cache . . . . . . . . . . . . . . . . 61-9 Controlling database size . . . . . . . . . . . 61-12 Tools for monitoring database size . . . . . 61-13 Monitoring database size . . . . . . . . . . . 61-13 Compacting databases . . . . . . . . . . . . . 61-13 Ways to compact databases . . . . . . . . . . 61-16 Database size quotas . . . . . . . . . . . . . . 61-23 Deleting inactive documents . . . . . . . . . 61-25
Using an agent to delete and archive documents . . . . . . . . . . . . Allowing more fields in a database

.... .....

61-27 61-29

xii Administering the Domino System, Volume 2

62 Using Server.Load . . . . . . . . . . 62-1

..................... Server.Load agents . . . . . . . . . . . . . . . . Server.Load metrics . . . . . . . . . . . . . . .
Server.Load Setting up clients and servers for Server.Load . . . . . . . . .

62-1 62-4 62-7

.. Passthru connections — Troubleshooting . Replication — Troubleshooting . . . . . . .
Partitioned servers — Troubleshooting You see the message “Database is not fully initialized yet” . . . . . .

63-78 63-79 63-80

. . . . . . . 62-12 Idle Workload script . . . . . . . . . . . . . . 62-14 R5 IMAP Workload test . . . . . . . . . . . . 62-15 R5 Simple Mail Routing test . . . . . . . . . 62-20 R5 Shared Database test . . . . . . . . . . . . 62-24 SMTP and POP3 Workload test . . . . . . . 62-26 Web Idle Workload test . . . . . . . . . . . . 62-30 Web Mail test . . . . . . . . . . . . . . . . . . 62-31 63 Troubleshooting . . . . . . . . . . . 63-1 Troubleshooting the Domino system . . . . . 63-1 Troubleshooting tools . . . . . . . . . . . . . . 63-2 Overview of server maintenance . . . . . . . 63-6 Server maintenance checklist . . . . . . . . . . 63-6 Backing up the Domino server . . . . . . . . . 63-7
Administration Process — Troubleshooting . .

. . . . 63-89 Server access — Troubleshooting . . . . . . 63-91 Server crashes — Troubleshooting . . . . . 63-96 Transaction logging — Troubleshooting . 63-102
Web server, Web Navigator, and the Web Administrator — Troubleshooting

. 63-104 Server.Load — Troubleshooting . . . . . . . 63-110 Appendix A Server Commands . . A-1 Appendix B Server Tasks . . . . . . . B-1 Appendix C NOTES.INI File . . . . . C-1
Appendix D System and Application Templates . . . . . . . . . D-1 Appendix E Customizing the Domino Directory . . . . . . . . . . . . . . E-1 Appendix F Administration Process Requests . . . . . . . . . . . . . . F-1 Appendix G Novell Directory Service for the IPX/SPX Network . . G-1 Appendix H Accessibility and Keyboard Shortcuts in Domino Administrator . . . . . . . . . . . . . . . . . H-1 Appendix I Server.Load Command Language . . . . . . . . . . . . I-1 Appendix J Server.Load Scripts . . . J-1 Index . . . . . . . . . . . . . . . . . . . . . . Index-1

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

63-8 63-12 63-16 63-21 63-36 63-45 63-48 63-52 63-55 63-74

Agent Manager and agents — Troubleshooting . . . . .

........ Database performance — Troubleshooting . Directories — Troubleshooting . . . . . . . Mail routing — Troubleshooting . . . . . .
Meeting and resource scheduling — Troubleshooting . . . . . . . . . Modems and remote connections — Troubleshooting . . . . . . . .

....

..... Platform statistics — Troubleshooting . . .
Network connections over NRPC — Troubleshooting . . . . . . . . . Network dialup connections — Troubleshooting . . . . .

....

........

Contents xiii

Preface
The documentation for IBM Lotus Notes, IBM Lotus Domino, and IBM Lotus Domino Designer is available online in Help databases and, with the exception of the Notes client documentation, in print format.

License information
Any information or reference related to license terms in this document is provided to you for your information. However, your use of Notes and Domino, and any other IBM program referenced in this document, is solely subject to the terms and conditions of the IBM International Program License Agreement (IPLA) and related License Information (LI) document accompanying each such program. You may not rely on this document should there be any questions concerning your right to use Notes and Domino. Please refer to the IPLA and LI for Notes and Domino that is located in the file LICENSE.TXT.

System requirements
Information about the system requirements for Lotus Notes and Domino is listed in the Release Notes.

Printed documentation and PDF files
The same documentation for Domino and Domino Designer that is available in online Help is also available in printed books and PDF files. You can order printed books from the IBM Publications Center at www.ibm.com/shop/publications/order. You can download PDF files from the IBM Publications Center and from the Documentation Library at the Lotus Developer Domain at www-10.lotus.com/ldd.

Related information
In addition to the documentation that is available with the product, other information about Notes and Domino is available on the Web sites listed here. • IBM Redbooks are available at www.redbooks.ibm.com.

xv

A technical journal, discussion forums, demos, and other information is available on the Lotus Developer Domain site at www-10.lotus.com/ldd.

Table of conventions
This table lists conventions used in the Notes and Domino documentation.
Convention italics
monospaced type

Description Variables and book titles are shown in italic type. Code examples and console commands are shown in monospaced type. File names are shown in uppercase, for example NAMES.NSF. Hyphens are used between menu names, to show the sequence of menus.

file names hyphens in menu names (File - Database - Open)

Structure of Notes and Domino documentation
This section describes the documentation for Notes, Domino, and Domino Designer. The online Help databases are available with the software products. Print documentation can be downloaded from the Web or purchased separately. Release Notes The Release Notes describe new features and enhancements, platform requirements, known issues, and documentation updates for Lotus Notes 6, Lotus Domino 6, and Lotus Domino Designer 6. The Release Notes are available online in the Release Notes database (README.NSF). You can also download them as a PDF file. Documentation for the Notes client The Lotus Notes 6 Help database (HELP6_CLIENT.NSF) contains the documentation for Notes users. This database describes user tasks such as sending mail, using the Personal Address Book, using the Calendar and Scheduling features, using the To Do list, and searching for information. Documentation for Domino administration The following table describes the books that comprise the Domino Administration documentation set. The information in these books is also found online in the Lotus Domino Administrator 6 Help database (HELP6_ADMIN.NSF). The book Installing Domino Servers ships with Domino. The other books are available for purchase, or for free download as PDF files.

xvi Administering the Domino System, Volume 2

Title Upgrade Guide

Description Describes how to upgrade existing Domino servers and Notes clients to Notes and Domino 6. Also describes how to move users from other messaging and directory systems to Notes and Domino 6. Describes how to plan a Domino installation; how to configure Domino to work with network protocols such as Novell SPX, TCP/IP, and NetBIOS; how to install servers; and how to install and begin using Domino Administrator and the Web Administrator. Describes how to register and manage users and groups, and how to register and manage servers including managing directories, connections, mail, replication, security, calendars and scheduling, activity logging, databases, and system monitoring. This book also describes how to use Domino in a service provider environment, how to use Domino Off-Line Services, and how to use IBM Tivoli Analyzer for Lotus Domino. Describes how to set up, manage, and troubleshoot Domino clusters.

Installing Domino Servers

Administering the Domino System, Volumes 1 and 2

Administering Domino Clusters

Documentation for Domino Designer The following table describes the books that comprise the Domino Designer documentation set. The information in these books is also found online in the Lotus Domino Designer 6 Help database (HELP6_DESIGNER.NSF) with one exception: Domino Enterprise Connection Services (DECS) Installation and User Guide is available online in a separate database, DECS User Guide Template (DECSDOC6.NSF). The printed documentation set also includes Domino Objects posters. In addition to the books listed here, the Domino Designer Templates Guide is available for download in NSF or PDF format. This guide presents an in-depth look at three commonly used Designer templates: TeamRoom, Discussion, and Documentation Library.
Title Application Development with Domino Designer Description Explains how to create all the design elements used in building Domino applications, how to share information with other applications, and how to customize and manage applications.

Domino Designer Programming Introduces programming in Domino Designer and Guide, describes the formula language. Volume 1: Overview and Formula Language continued Preface xvii

Title

Description

Domino Designer Programming Describes the LotusScript/COM/OLE classes for access to databases and other Domino structures. Guide, Volumes 2A and 2B: LotusScript/COM/OLE Classes Domino Designer Programming Provides reference information on using the Java and CORBA classes to provide access to databases Guide, Volume 3: Java/CORBA Classes and other Domino structures. Domino Designer Programming Describes the XML and JSP interfaces for access to Guide, databases and other Domino structures. Volume 4: XML Domino DTD and JSP Tags LotusScript Language Guide Domino Enterprise Connection Services (DECS) Installation and User Guide Lotus Connectors and Connectivity Guide Describes the LotusScript programming language. Describes how to use Domino Enterprise Connection Services (DECS) to access enterprise data in real time. Describes how to configure Lotus Connectors for use with either DECS or IBM Lotus Enterprise Integrator for Domino (LEI). It also describes how to test connectivity between DECS or LEI and an external system, such as DB2, Oracle, or Sybase. Lastly, it describes usage and feature options for all of the base connection types that are supplied with LEI and DECS. This online documentation file name is LCCON6.NSF. Describes how to use the LC LSX to programmatically perform Lotus Connector-related tasks outside of, or in conjunction with, either LEI or DECS. This online documentation file name is LSXLC6.NSF. Describes installation, configuration, and migration information and instructions for LEI. The online documentation file names are LEIIG.NSF and LEIIG.PDF. This document is for LEI customers only and is supplied with LEI, not with Domino. Provides information and instructions for using LEI and its activities. The online documentation file names are LEIDOC.NSF and LEIDOC.PDF. This document is for LEI customers only and is supplied with LEI, not with Domino.

Lotus Connector LotusScript Extensions Guide

IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide

IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide

xviii Administering the Domino System, Volume 2

Security

Chapter 37 Planning Security
This chapter includes information you need to know before setting up security and provides lists to help you plan security at your organization.

Overview of Domino security
Setting up security for your organization is a critical task. Your security infrastructure is critical for protecting your organization’s Domino resources and assets. As an administrator, you need to give careful consideration to your organization’s security requirements before you set up any Domino servers or Notes users. Upfront planning pays off later in minimizing the risks of compromised security. Use the following tasks to guide you through your security planning: • • • • • • Know the business. Identify assets and threats (risk analysis). Develop strategies to protect your computing environment. Develop incident-handling procedures. Plan and deliver employee training. Keep processes current.

Know the business
This is the process of understanding your organization’s business requirements and the service levels that need to be met. Identify all of the components of the business, including those that are not your direct responsibility. Include new acquisitions and any recent spin-offs. As part of this process, identify the trusted network and the non-trusted network. In some cases an extranet may be an extension of a trusted network.

37-1

Once you have an understanding of the business requirements, you can then begin to plan the specifics of your Domino infrastructure, including: • • • • Will more than one Domino domain be needed, or will the new domain need to interact with existing domains? What is the best method to expose Domino data to the Internet? What service levels are needed to support the business? Who should have what level of access to the Domino Directory?

Identify assets and threats (risk analysis)
Identify the value of the assets you are trying to protect. Applications in your organization have different values. For example, in most organizations, the availability of the e-mail infrastructure is essential to business, but instant availability of all previous e-mails is less important. Then identify the threats from an internal as well as external perspective. Make sure you understand the potential loss to your organization in the event that any one of the threats is successful. Finally, determine the probability of the threat. For example, an automated attack from a compromised system is a near certainty, a server room failure from water damage is a distinct possibility, while the theft of a server’s hard drive from the data center is usually not likely. There are many different types of threats to any computing infrastructure: • • • • • • • Environmental destruction Automated attacks or hackers on the Internet Automated attacks from compromised systems in your intranet Interfaces with less secure systems Mistakes made by untrained or poorly trained users and administrators Data interception or alteration for criminal profit Malicious activity by former employees

You should also understand the Domino security model, in order to better understand the Domino assets you need to protect and how they can be protected. For more information, see the topic “The Domino security model” later in this chapter.

37-2 Administering the Domino System, Volume 2

Security

Develop strategies to protect your computing environment
Once you understand the potential threats to your Domino environment, you can create policies to protect each part of your Domino computing infrastructure. This may include developing policies for the following areas: • • • • • • • • Limits on physical access to your servers Network access and protection Messaging infrastructure, through the use of execution control lists and anti-virus products Application security, through encryption and ACL management Encryption key management, including ID recovery Change control, through the use of the Domino Change Manager (or you can build your own) User training for organizational security rules and technology Security incident reporting

For more information on change control, see the chapter “Using IBM Tivoli Analyzer for Lotus Domino.”

Develop incident handling procedures
An incident is an unplanned and unexpected event that requires immediate action to prevent a loss of business, assets, or public confidence. All security plans must have an incident handling component, as well as a feedback component for how incidents have been handled. Feedback helps to keep security plans and policies current. Note One of the best documents that describes the importance of incident handling is the National Institute of Standards and Technology’s Contingency Planning Guide for Information Technology Systems (NIST Special Publication 800-34). Incident handling includes: • • • Incident reporting plans and methods Response procedures for each incident type Incident response tests

Planning Security 37-3

Once you have your incident-handling plans in place, you will be better able to determine your requirements for: • • • • Domino logging Domino HTTP logging Domino backup and restoring Parameters for Domino event monitoring

For more information on the Domino server and Web server logs, see the chapter “Using Log Files.” For information on backing up Domino, see the chapter “Troubleshooting.” For more information on event monitoring, see the chapter “Monitoring the Domino Server.”

Plan and deliver employee training
Make sure that your users know that security is everyone’s responsibility. Based on your business needs, your should train your users on: • • • • • Domino security basics Notes IDs and how to them Notes Execution Control Lists and Execution Security Alerts Use of encryption and how to encrypt a mail message Who to call in the event of a problem or a security incident

Note The National Institute of Standards and Technology published a document about the relationship among security awareness, training, and education, titled Information Technology Security Training Requirements: A Role- and Performance-Based Model (NIST Special Publication 800-16).

Keep processes current
This step is normally the most difficult, but is as critical as any of the other steps. Take the time to establish a program that will review security processes and procedures on a regular basis. Be sure to link the review to employee training. If changes are made, then employee training may need to be updated.

37-4 Administering the Domino System, Volume 2

Security

The Domino security model
The Domino security model is based on the premise of protecting resources, such as the Domino server itself, databases, workstation data, and documents. The resources, or objects, that are being protected are set up to define the rights of users to access and change the object. Information about access rights and privileges are stored with each protected resource. Thus, a given user or server may have different sets of access rights, depending on the resources to which that user or server requires access. The following includes brief descriptions of the various resources that you need to protect in a Domino environment. Some of the topics are not specific to Domino security, but are included here in the interest of thoroughness.

Physical security
Physically securing servers and databases is equally as important as preventing unauthorized user and server access. It is the first line of defense against unauthorized or malicious users, by preventing them from having direct access to your Domino servers. Therefore, we strongly recommend that you locate all Domino servers in a ventilated, secure area, such as a locked room. If servers are not physically secure, unauthorized users might circumvent security features — for example, ACL settings — and access applications directly on the server, use the operating system to copy or delete files, or physically damage the server hardware itself. Physical network security concerns should also include disaster planning and recovery.

Operating system security
Unauthorized or malicious users often take advantage of operating system vulnerabilities. As a system administrator, you should safeguard the operating system on which your Domino server runs. For example, you should limit administrator login/rights, disable FTP (on NT), and avoid the use of mapped directory links to file servers or shared NAS server for Domino servers. Stay informed about your operating system of choice, and keep current with security updates and patches.

Planning Security 37-5

Network security
The goal for securing your network is to prevent unauthorized users from gaining access to servers, users, and data. Physical network security is beyond the scope of this book, but you must set it up before you set up Notes and Domino connection security. Physical network security is established through the use of devices — such as filtering routers, firewalls, and proxy servers — that enable network connections for various network services (such as LDAP, POP3, FTP, and STMP) that you want to provide for your users. Network connection security access is also controlled using these devices, as you can define what connections can be accessed, and who is authorized to used them. Properly configured, these devices prevent unauthorized users from: • • • Breaking through into the network and accessing the server via the operating system and its native services (such as file sharing). Impersonating an authorized Notes user Eavesdropping on the network to collect data

Server security The Domino server is the most critical resource to secure and is the first level of security that Domino enforces after a user or server gains access to the server on the network. You can specify which users and servers have access to the server and restrict activities on the server — for example, you can restrict who can create new replicas and use passthru connections. You can also restrict and define administrator access, by delegating access based on the administrator duties and tasks. For example, you can enable access to operating system commands through the server console for system administrators, and grant database access to those administrators who are responsible for maintaining Domino databases. If you set up servers for Internet/intranet access, you should set up SSL and name-and-password authentication to secure network data transmitted over the network and to authenticate servers and clients. For more information, see the topic “Server security” later in this chapter. ID security A Notes or Domino ID uniquely identifies a user or server. Domino uses the information contained in IDs to control the access that users and servers have to other servers and applications. One of the responsibilities of the administrator is to protect IDs and make sure that unauthorized users do not use them to gain access to the Domino environment.

37-6 Administering the Domino System, Volume 2

Security

Some sites may require multiple administrators to enter passwords before gaining access to a certifier or server ID file. This prevents one person from controlling an ID. In such cases, each administrator should ensure each password is secure to prevent unauthorized access to the ID file. For more information, see the topic “Notes and Domino ID security” later in this chapter. You can also secure Notes user IDs with Smartcards. Smartcards reduce the threat of user ID theft, as a user who has a Smartcard needs their user ID, their Smartcard, and their Smartcard PIN to access Notes. For more information on Smartcards, see Lotus Notes 6 Help. Application security Once users and servers gain access to a Domino server, you can use the database access control list (ACL) to restrict access that specific users and servers have to individual Domino applications on the server. In addition, to provide data privacy, encrypt the database with an ID so unauthorized users cannot access a locally stored copy of the database, sign or encrypt mail messages users send and receive, and sign the database or template to protect workstations from formulas. For more information on database ACLs, see the topic “Application security” later in this chapter. Application design element security Although users may have access to an application, they may not have access to specific design elements in the application — for example, forms, views, and folders. When designing a Domino application, an application developer can use access lists and special fields to restrict access to specific design elements. For more information on securing design elements, see the topic “Application design element security” later in this chapter. Workstation data security Notes users may keep and use important applications and information on their workstations. This information can be protected through the use of an execution control lists (ECL), which defines the access that active content from other users has to the user workstation. For more information on execution control lists, see the topic “Workstation data security” later in this chapter.

Planning Security 37-7

The Domino security team
Every organization should have a security team that is responsible for building, implementing, and managing the security infrastructure. The team provides central security focus, so that everyone is looking at the problems and solutions in the same way. However, departments in your organization also need to be involved in developing the questions and the answers for implementation of your Domino security system.

Getting started
You need to develop a set of security documentation for your organization. There are four basic types of security documents needed for any security implementation: • Policies are the driving documents for the business. These are typically high level statements about the security needs of the business. Your organization probably already has policy documents for the organization as a whole. You build and, if necessary, expand on these to develop the security policies for your Domino environment. Guidelines provide overall guidance on how to support and maintain security in the enterprise. Standards are established rules on what will and will not happen in an enterprise. Audits may cover all four types of documents, but the auditor will really focus on the standards set down by a company. Standards typically cover things like minimum password strength, password expiration intervals, server operating systems and physical environments, Internet and dial-in access controls, background checks for administrators, and auditing requirements. Procedures typically include specific steps on how to implement security within an enterprise. This will be the bulk of your Domino security documentation, covering everything from how to control Domino and X.509 certifiers to what to do when users have forgotten their Notes or Internet passwords to what steps to take when an employee leaves an organization. Procedures are developed after the security framework is in place.

• •

The Domino security team is responsible for initial direction, feedback, and auditing of these documents. The team must include representatives from each department within the enterprise. With this approach, the security documents created will meet the needs of the entire company. This has the added benefit of creating buy-in from the participating departments.

37-8 Administering the Domino System, Volume 2

Security

Most companies will have a matrix of responsibility similar to the one below:
Role CEO Responsibility The CEO needs to be a virtual member of the team. Security must flow from the both the top-down and the bottom-up. All technology officers need to be members of the team. It is appropriate for these members to delegate their role to someone else, as long as the delegate has the authority to make decisions. This person will be the driver of security in the organization.

CIO / CTO

Security officer

Representatives from each These representatives specify business needs and requirements. They must have decision-making functional department authority. Accounting IT Department HR / Training They will provide the information for risk analysis. These team members can translate business needs and requirements into technology. HR needs to assist with user training. HR is also involved with background checks, privacy of personal information, and termination policies and procedures. These team members provide information on the legal implications of anything to do with employees, risk management, or publication of information. This group creates and edits the documents. This team will handle incidents that are not covered by implemented security practices.

Legal

Documentation experts/ technical writers Incident Response Team

Communication specialists Communication to the end users about security is critical. Domino administrators Provide expertise on the Domino computing environment.

Leveraging end users Your users are a critical part of your security implementation. You should communicate to them the importance of your security planning efforts, as well as security guidelines and standards that you develop. Technology alone cannot keep your organization secure. Your users are as important as any firewall or certificate authority in ensuring the success of your security infrastructure.
Planning Security 37-9

One way to involve users in security planning is to conduct a survey to determine the level of enterprise security that users expect, as well as the assets they feel should be protected. An anonymous survey is a good way to discover security issues that users may not be willing to express openly. Note The most respected and commonly used standard source for security policies and procedures is the ISO17799 standard. The National Institute for Standards and Technology has multiple guidelines for developing security policies, standards, and procedures, including information about ISO I7799.

The core team
Once the framework is built, implement the core security team, which should include the following people: Server administrators Server administrators are responsible for managing the overall health and well-being of Domino servers. A major responsibility of a server administrator includes defining and managing server access lists and server restrictions, both for Notes clients and Web users. In large organizations, administration duties may be delegated among several server administrators. In small organizations, a server administrator might serve as the Domino certification administrator and the database manager for system databases, such as the Domino Directory and the log file (LOG.NSF). A server administrator might also be responsible for creating and maintaining File Protection documents for HTTP access and implementing other Web-related security measures. It is a best practice to separate Domino server administration from operating system server administration, if your organization’s IT structure allows this. You can define several levels of administrator for your organization, depending on the access required to various administration resources. For example, you can set up an administrator for remote console access only, or for system administration access only. These levels of administrative access are defined in the Server document on the Domino server. For more information on setting up administrator access to a Domino server, see the chapter “Controlling Access to Domino Servers.”

37-10 Administering the Domino System, Volume 2

Security

Database managers Database managers are responsible for one or more Lotus Notes databases or database applications. A major responsibility of a database manager includes managing database access control lists (ACLs). Some organizations will use the concept of a database owner for management of sensitive data. Certificate authority administrators Certificate authority administrators create and manage Domino server-based certification authorities and Domino 5 certificate authorities. They have access to all certifier ID files. For the server-based certification authority, CA administrators can delegate user registration and certificate approval to registration authorities. Otherwise, they are responsible for approving and issuing Internet server and client certificates. Since certification is the cornerstone of Notes and Domino security, delegate responsibility for it with the utmost care. For more information on the server-based certification authority, see the chapter “Setting Up a Domino Server-Based Certification Authority.” Registration authority administrators The registration authority role is new for Domino 6 and is unique to the server-based certification authority. A registration authority can register new Notes users and Domino servers without requiring access to the certifier ID and password. Registration authorities can also recertifiy users and, for Internet certifiers, approve client certificate requests and revoke certificates. For more information on the registration authority role, see the chapter “Setting Up a Domino Server-Based Certification Authority.”

Security planning checklists
An important aspect of planning security for your Domino environment is understanding the tasks and features involved with securing each type of resource. • • • • • Server security Application security Application design element security Notes and Domino ID security Workstation security

Planning Security 37-11

Server security
To secure Domino servers, you allow and prevent user and server access. In addition, you restrict the activities that users and servers may perform on the server.
Task Choose an internal or external Internet certificate authority Use Set up a certifier that will be used to issue Internet certificates in your organization.

Cross-certify Notes Allow Notes users and Domino servers in different user IDs and Domino hierarchically certified organizations to ascertain the server and certifier IDs identity of users and servers in other Notes organizations. Allow or deny access to Specify which Notes users, Internet clients, and a server Domino servers are authorized to access the server. Allow anonymous server access Give server access to Notes users and Domino servers outside of the organization without issuing a cross-certificate.

Allow anonymous Determine whether Internet/intranet users are Internet/Intranet client allowed to access the server anonymously. access Secure the server with name-and-password authentication Enable session-based authentication Identify Internet and intranet users accessing the server and control access to applications based on the user name. Allow Web browser clients to authenticate and maintain state with the server by using cookies. using session-based name-and-password authentication. Session-based authentication lets administrators provide a customized sign-in form and configure session expiration to log users off the server after a specified period of inactivity. Also provides capability for single single-on between Domino and WebSphere servers, using the same cookie.

Controlling the level of Specify the level of refinement that the server should authentication for Web use when searching for names and authenticating clients Web users. Limit access to create new databases, replicas, or templates Control access to a server’s network port Allow specified Notes users and Domino servers to create databases and replica databases on the server. Limiting this access avoids a proliferation of databases and replicas on the server. Allow specified Notes users and Domino servers to access the server over a port. continued 37-12 Administering the Domino System, Volume 2

Security

Task Encrypt server’s network port Password protect the server console Restrict administrator access Restrict server agents

Use Encrypt data sent from the server’s network port to prevent network eavesdropping. Prevent unauthorized users from entering commands at the server console. Assign different types of administrator access to individuals based on the tasks they need to do on the Domino server. Specify which Notes users and Domino servers are allowed to run which kinds of agents on the server.

Restrict passthru access Specify which Notes users and Domino servers can access the server as a passthru server and specify the destinations they may access. Restrict server access by browser users running Java or JavaScript programs Secure the server with SSL Specify which Web browser users can use Domino ORBs to run Java or JavaScript programs on the server. Set up SSL security for Internet/intranet users to authenticate the server, encrypt data, prevent message tampering, and, optionally, authenticate clients. This is mandatory for e-commerce and secure business-to-business messaging. Restrict mail routing based on Domino domains, organizations, and organizational units. Restrict inbound mail to prevent Domino from accepting unwanted commercial e-mail. Use S/MIME to encrypt outgoing mail. This is often mandatory for secure business-to-business messaging. Enhance SMTP router security. Specify who can access files — for example, HTML, GIF, or JPEG — on a server’s hard drive. Authenticate Web clients who use name-and-password or SSL client authentication in secondary Domino or LDAP Directories marked as “trusted” by your domain. Allow Web users to access a certain drive, directory, or file on a Domino server and prevent Domino from prompting users for a name-and-password for different realms. continued Planning Security 37-13

Set mail router restrictions Set inbound SMTP restrictions Use S/MIME Prevent relaying through MTA Use file protection documents Authenticate Internet clients using a secondary Domino Directory or LDAP directory Authenticate Web clients for a specific realm

Task Locate the server in a secure area Secure the server console with a Smartcard

Use Prevent unauthorized access to unencrypted data and server and certifier IDs that are stored on the server’s hard drive. Prevent unauthorized access to the server console by requiring the use of a Smartcard to log in to Domino.

Use a firewall to protect Control unauthorized access to a private network access to a server from the public Internet.

For more information on securing Domino servers, see the chapter “Controlling Access to Domino Servers.”

Application security
Restrict access to Domino applications to prevent unauthorized users from gaining access to information.
Task Use the ACL to restrict application access Enforce a consistent ACL Use Control Notes and Internet/intranet user and Domino server access to an application. Protects databases and templates on the server by forcing all changes to the ACL at a single location. Prevent unauthorized users from accessing an application locally on a server or workstation. Identify the creator of an application or template. When a user accesses the application, the signature is checked to determined whether the action is allowed. For example, on a Domino server the Agent Manager verifies the signature of an agent and checks whether the signer has the rights to perform the action. On a Notes client, the signature is checked against the signer’s rights in the workstation ECL. Ensure that only the intended recipient can read mail.

Encrypt applications

Sign an application or template

Encrypt incoming and outgoing Notes mail

Electronically sign mail messages Verify that the person who sends the message is the author and that no one has tampered with the data.

For more information on securing Domino applications, see the chapter “Controlling User Access to Databases.”
37-14 Administering the Domino System, Volume 2

Security

For more information on securing Notes mail, see the chapter “Encryption and Electronic Signatures.”

Application design element security
An application developer can further restrict access to design elements within an application using the Domino Designer. Application design security takes effect once users gain access to an application.
Task Create Read access lists for views Create Read and Edit access lists for folders Create Read and Edit access lists for forms Use Specify which Notes and Internet/intranet users can see a view Specify which Notes and Internet/intranet users can see a folder or update the contents of a folder Specify which Notes and Internet/intranet users can create, modify, or read documents created with a form

Create Readers and Authors fields Specify which Notes and Internet/intranet users can create, modify, or read specified documents Create signed fields Verify that the Notes user who originated the data is the author and that no one has tampered with the data Control which Notes users can access a field in a form Control which Notes and Internet/intranet users can access a field in a form Specify which Notes and Internet/intranet users can access a section in a document

Create encrypted fields Create hidden fields Create Read and Edit access lists for sections

For more information on securing application design elements, see the book Application Development with Domino Designer.

Planning Security 37-15

Notes and Domino ID security
To prevent unauthorized access to servers and applications, secure Notes and Domino IDs. These tasks apply only to Notes users and Domino servers.
Task Require a password for all user and server IDs Enforce password quality testing for IDs Assign multiple passwords to server and certifier IDs Use Prevent an unauthorized user from using an illicitly obtained ID to authenticate with a server Prevent unauthorized users from guessing passwords Require multiple users to enter passwords before gaining access to the ID file to prevent one person from controlling a server or certifier ID

Compare a password with Prevent an unauthorized user from using an the password stored in the illicitly obtained ID to authenticate with a server Domino Directory and require users to change their passwords periodically Compare a Domino public key with the public key stored in the Domino Directory Prevent an unauthorized user from using an illicitly obtained ID to authenticate with a server

Recover lost or damaged IDs Regain access to a user ID file instead of issuing a new ID Set up a security settings policy document Lock the user ID after x minutes of inactivity Use F5 to log off Manage Notes and Internet password properties, such as password synchronization and expiration settings, on an organizational level Automatically log off servers to prevent an unauthorized user from using the workstation Immediately log off servers to prevent an unauthorized user from using the workstation

Save user IDs on a disk Physically protect user IDs instead of on the workstation and keep disks in a safe place Locate workstations in a Prevent unauthorized access to the ID files secure area — for example, a locked room Install Smartcard readers on user workstations and have users log in to Notes with Smartcards Physically protect user IDs and private Internet keys

37-16 Administering the Domino System, Volume 2

Security

For more information on execution control lists, see the chapter “Protecting and Managing Notes IDs.”

Workstation data security
To prevent unauthorized access to user workstation information and applications, secure Notes user workstations.
Task Use

Configure the Administration ECL Prevent unauthorized users from gaining and deploy to client workstations. access to data and applications on client workstations, by defining authorized users and authorized actions Set up a security settings policy document Use security settings policy documents to: • Set up and configure one or more administration ECLs • Specify how and when you want workstation ECLs to be refreshed or replaced Encourage users to use operating Discourage unauthorized workstation system and screen saver passwords access Encourage users to shut off workstations before leaving Discourage unauthorized workstation access

For more information on execution control lists, see the chapter “Protecting User Workstations with Execution Control Lists.”

Security policies
Domino policies are a way of distributing administrative settings, standards, and configurations to users, groups, or entire organizations. A policy is a collection of administrative settings that addresses an administrative area, such as security. You then use this document to establish and enforce administrative standards, and to distribute them throughout the organization. In addition, you can easily modify and maintain standards across an organization by simply editing a settings document. You can set up a security settings document to manage and deploy execution control lists (ECLs) and Notes and Internet password settings and synchronization. As these two areas of security are user-specific and are frequently changed by users, you can use a security policy to enforce settings for these areas across the organization, and control the extent to which users can adjust or change these settings. For more information, see the chapter “Using Policies.”
Planning Security 37-17

Setting up an Internet certificate authority
A critical area in security planning is determining whether and how to set up a certificate authority to issue Internet certificates. A certificate authority (CA), or certifier, is a trusted administration tool that issues and maintains digital certificates. Certificates verify the identity of an individual, a server, or an organization, and allow them to use SSL to communicate and to use S/MIME to exchange mail. Certificates are stamped with the certifier’s digital signature, which assures the recipients of the certificate that the bearer of the certificate is the entity named in the certificate. Certifiers can also issue trusted root certificates, which allow clients and servers with certificates created by different CAs to communicate with one another. Note It’s important to distinguish between Notes certifiers and Internet certifiers. When you install and set up the first Domino server in a domain, a Notes certifier is automatically set up to issue Notes certificates to Notes clients. These certificates are essential for Notes clients to authenticate with a Domino server and for Domino servers to authenticate one another. Hence Notes certifiers are important even in an environment with all Web clients. An Internet certifier, such as those discussed here, issues Internet (X.509) certificates, which are required for secure communication over the Internet. You set up Internet certifiers on an as-needed basis. Choosing the right Internet certifier for your organization You have several options for setting up an Internet certifier for your organization (for the rest of this topic, all references to certifier mean “Internet” certifier). You can use a third-party commercial certifier, such as VeriSign, or you can use one of the two types of Domino Internet certifiers. There are advantages and disadvantages involved with each type of certifier; the choice you make should be determined by business requirements of your organization, as well as the time and resources available for managing the certifier.

37-18 Administering the Domino System, Volume 2

Security

Internet certifiers: Domino vs. third-party
Domino certifier • Avoid the expenses that a third-party certifier charges to issue and renew client and server certificates. • Many administrators are already familiar with Domino, they will not require additional training that would be needed to use a third-party certifier. • Easier and quicker to set up and deploy new certificates as needed. Third-party certifier • Can simplify client configuration. If you get certificates from a certifier that is pre-configured as trusted by the (VeriSign, RSA, etc.) browsers you use, it saves a step in client configuration. • Similarly, if the certifier is pre-configured as trusted in the mail clients of the external businesses with which you are exchanging S/MIME mail, it will save them a configuration step.

Domino Internet certifiers: server-based certification authority vs. Domino 5 certificate authority You can choose to set up a Domino certification authority that uses the server-based CA process, or a Domino 5 certificate authority, which uses a CA key ring.
Server-based certification authority • Administrators can manage both Notes and Internet certifiers through the CA process. • Issues Internet certificates that are compliant with security industry standards (such as X.509v3 and PKIX). • Does not require administrator access to the certifier ID and ID password in order to register users and servers. This allows administrators to delegate these tasks without potentially compromising the certifier. • Supports the PKIX registration authority (RA) role, which allows administrators to delegate the certificate approval/denial process. • Issues certificate revocation lists (CRLs), which contain information about revoked or expired Internet certificates. • Required if you plan to use the Web Administrator client to register Notes users. Domino 5 certificate • Provides a simple means by which to set up an authority Internet certifier for testing or demonstration purposes.

Planning Security 37-19

Using both types of Domino Internet CAs in a domain
It is possible to have both types of certifiers — CA process and CA key ring — in a domain. However, you must be careful not to have one certifier that uses both a key ring and the CA process to issue Internet certificates. A CA process-enabled certifier tracks the certificates that it issues in an Issued Certificate List, a database accessible to all servers in a domain. On the other hand, a key ring-style certifier creates logs on whatever workstation on which it is used, so there is no centralized list of issued certificates (just multiple partial lists). Therefore, any certificates issued using the CA process won’t be recognized by a CA key ring, just as any certificates that were created using a CA key ring file won’t be recognized by the CA process. This is a problem for Internet certifiers especially, because it is possible to revoke Internet certificates in server-based certification authorities. To revoke an Internet certificate, however, you must select it in the ICL. If the certificate was initially issued using a key ring, it won’t appear in the ICL, so it cannot be revoked. Therefore, it is strongly advised that you choose one way to operate — CA process or CA key ring — for each certifier.

37-20 Administering the Domino System, Volume 2

Security

Chapter 38 Controlling Access to Domino Servers
This chapter includes information on setting up a Domino server to allow users and other servers to access it.

Validation and authentication for Notes and Domino
Whenever a Notes client or Domino server attempts to communicate with a Domino server to replicate, route mail, or to access a database, two security procedures use information from the client or server ID to verify that the client or server is legitimate. Validation establishes trust of the client’s public key. If validation occurs successfully, authentication begins. Authentication verifies user identity, and uses the public and private keys of both the client and the server in a challenge/response interaction.

Rules that guide trust of public keys
Validation uses these three rules to establish the trust of a public key. Domino validates the client that is trying to access the server and the server that the client is trying to access. 1. Trust the public key of any of the server or client’s ancestors in the hierarchical name tree because the ancestor’s public key is stored in the server or client’s ID file. 2. Trust any public key obtained from a valid certificate issued by any of the server or client’s ancestors in the hierarchical name tree. 3. Trust any public key certified by any trusted certifier and belonging to one of the certifier’s descendants.

How validation and authentication work
This example describes how validation and authentication work together to ensure the security of the system. In this example, user Randi Bowker/Marketing/East/Acme (the client) wants to access Mail-E/East/Acme (the server). 1. Mail-E reads the Acme public key from Mail-E’s ID file. According to the first rule above, Mail-E trusts the public key assigned to Acme.
38-1

2. Randi sends Mail-E information in her user ID. Mail-E reads Randi’s user ID for the certificate issued by Acme to East. Mail-E uses the Acme public key, which it now trusts, to verify that the East certificate is valid. According to the second rule above, if the certificate is valid, Mail-E trusts the public key assigned to East. 3. Mail-E then reads Randi’s user ID for the certificate issued by East/Acme to Marketing. Mail-E uses the East/Acme public key to verify that the Marketing/East/Acme certificate is valid. Again, the second rule states that Mail-E now trusts the public key assigned to Marketing/East/Acme. 4. Mail-E reads Randi’s user ID for the certificate issued by Marketing/East/Acme to Randi. Mail-E uses the Marketing/East/Acme public key, which it now trusts, to verify that Randi’s certificate is valid. According to the third rule above, if the certificate is valid, Mail-E trusts the public key assigned to Randi. 5. After Mail-E establishes trust of Randi’s public key, the authentication process begins. 6. Mail-E sends a random number challenge to Randi. 7. Randi’s workstation encrypts the challenge with her private key and sends the newly encrypted number back to Mail-E. 8. Mail-E uses Randi’s public key to decrypt the response. If this yields the original challenge, Mail-E knows Randi is who she claims to be. 9. The process is then reversed. Randi’s workstation validates Mail-E’s public key by processing Mail-E’s certificates and then uses the challenge/response procedure just described to authenticate the server.

Server access for Notes users, Internet users, and Domino servers
To control user and server access to other servers, Domino uses the settings you specify on the Security tab in the Server document as well as the rules of validation and authentication. If a server validates and authenticates the Notes user, Internet user, or server, and the settings in the Server document allow access, the user or server is allowed access to the server. Grant server access to users and servers who need to access resources stored on the server. Deny access to prevent specified users and servers from having access to all applications on the server.

38-2 Administering the Domino System, Volume 2

Security

Access settings in the Server document control server access for both Notes and Internet users. By default, the Server access settings apply only to Notes clients. You can enable these settings for each of the Internet protocols through the Ports tab of the Server document. For more information, see the topic “Setting up Notes user, Domino server, and Internet user access to a Domino server” later in this chapter.

Types of server access controls
Server access list The server access list controls the access that Notes users, Domino servers, and users who access the server using Internet protocols (HTTP, IMAP, LDAP, POP3) have to that server. Keep in mind that using a server access list activates an additional security code and can, therefore, increase the time required to access the server. For more information, see the topic “Setting up Notes user, Domino server, and Internet user access to a Domino server” in this chapter. Deny access list The deny access list denies access to Notes users and Internet clients you specify. For example, use a deny access list to prevent access by users who no longer work for your company but who may still have their Notes user IDs, or who still have a Person document in the Domino Directory with a legitimate Internet password and would otherwise be able to access the server using an Internet protocol. For more information, see the topic “Setting up Notes user, Domino server, and Internet user access to a Domino server” in this chapter. Notes ID lock out Notes ID lock out denies access to Notes users you specify. Like a deny access list, Notes ID lock out prevents access by users who no longer work for your company but who may still have their user IDs. Using Notes ID lock out is useful when you want to prevent other users from looking at a deny access list to see a list of users who have been terminated from your organization. For more information, see the topic “Denying Notes users access to all servers in a domain” later in this chapter. Anonymous access Anonymous access lets Notes users and Domino servers access the server without having the server validate and authenticate them. Use anonymous access to provide the general public with access to servers for which they are not cross-certified. When you set up anonymous
Controlling Access to Domino Servers 38-3

server access, Domino does not record the names of users and servers in the log file (LOG.NSF) or in the User Activity dialog box. When users attempt to connect to a server set for anonymous access and the server can’t authenticate them, they see this message: Server X cannot authenticate you because the server’s Domino Directory does not contain any cross-certificates capable of authenticating you. You are now accessing the server anonymously. You can also set up Internet clients to access servers anonymously. For more information on setting up anonymous access for Internet/intranet clients, see the chapter “Setting Up Name-and-Password and Anonymous Access to Domino Servers.” Network port access Network port access allows or denies access to specified Notes users and Domino servers, based on the network port they try to use. For example, you can deny access to Alan Jones/Sales/East/Acme when he dials into the server but allow access when he uses TCP/IP to connect to the server. For more information, see the topic “Controlling access to a specific server port” later in this chapter.

Setting up Notes user, Domino server, and Internet user access to a Domino server
You can specify Notes users and Domino servers that are allowed to access the server, as well as users who access the server using Internet protocols (HTTP, IMAP, LDAP, POP3). If your system uses multiple Domino Directories, Domino searches only the first Domino Directory specified in the Names setting in the NOTES.INI file for Notes users. If you have enabled the server access settings for Internet protocols, you can also specify users from secondary Domino directories and external LDAP directories in the Allow or Deny access lists. Note It is not necessary to specify Anonymous for the “Access server” and “Not access server” fields. Anonymous access for Notes users is enabled through the “Allow anonymous Notes connections” field, and anonymous access for Internet users is enabled in the Internet Site document for each Internet protocol (or the Server document if you are not using Internet Sites to configure Internet protocols).

38-4 Administering the Domino System, Volume 2

Security

Tip To improve log-in performance for a group of frequent users and still allow access to everyone listed in the Domino Directory, create a group named Frequent Users and then enter that group name first in the “Access server” field. If Domino finds a user in the Frequent Users group first, it doesn’t check the Domino Directory for the individual name. For example, enter the following in the “Access server” field:
Frequent Users, *

For more information on creating groups, see the chapter “Setting Up and Managing Groups.”

To set up Notes user and Domino server access to a Domino server
1. From the Domino Administrator, click Configuration and open the Server document. 2. Click the Security tab. 3. In the Server Access section, complete one or more of these fields, and then save the document:
Field Access server Enter Click the check box to allow server access to users listed in all trusted directories. This box is disabled by default. If this option is not selected, then only those users specified in the field below the check box can access the server. In the drop-down field that appears below the check box, add the names of specific Notes users, servers, and groups to whom you want to give access to the server, such as: • Names of users, servers, and groups. • An asterisk (*) to allow all users in the Domino Directory to have access. This is the same as enabling the “Users listed in all trusted directories” field. • An asterisk, followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to have access. • An asterisk followed by the name of the view — for example, *($Users) — to allow all names that appear in a specific view in the Domino Directory to have access. Access time is quicker if you specify a group name rather than a view name. The default value for this field is blank, which means that all users can access the server. Separate multiple names with a comma or semicolon. continued

Controlling Access to Domino Servers 38-5

Field Not access server

Enter Any of these: • Names of users, servers, and groups. • An asterisk, followed by a certificate name — for example, */Sales/East/Acme — to deny access to all users certified by a particular certifier. • An asterisk followed by the name of the view — for example, *($Users) — to deny access to all names that appear in a specific view in the Domino Directory. Access time is quicker if you specify a group name rather than a view name. The default value for this field is blank, which means that all names entered in the “Access server” field can access the server. Names entered in the “Not access server” field take precedence over names entered in the “Access server” field. For example, if you enter a group name in the “Access server” field and enter the name of an individual member of this group in the “Not access server” field, the user will not be able to access the server. Note An alternative way to deny Notes user access to a server is to lock out an individual user’s ID from the server. Separate multiple names with a comma or semicolon.

Trusted servers

Names of servers that are trusted to assert the identities of users to this server, and thus are trusted by the current server to have authenticated those users. Used for remote agent access and xSP.

To enable Server document access settings for Internet protocols
1. From the Domino Administrator, click Configuration and open the Server document. 2. Click Ports - Internet Ports. 3. Choose the Internet protocol tab for which you want to enable server access settings. 4. In the field “Enforce server access settings,” select Yes.

38-6 Administering the Domino System, Volume 2

Security

Customizing access to a Domino server
After you set up basic access for Notes users and Domino servers, you can customize access to restrict specific users and servers to specific activities. To customize access to a server, you can do any of these: • • • • • • • • • • • • Deny Notes users access to all servers in a domain. Restrict administrator access. Set up anonymous server access. Control access to a specific server port. Control creation of databases, replicas, and templates. Control use of headline monitors. Control access to a passthru server or passthru destination. Control agents that run on a server. Control access by browser clients that use Java and Javascript Controlling Web browser access to files Controlling the level of authentication for Internet clients Create a Domino Web Server Application Programming Interface (DSAPI) filter to customize the authentication of Web users. For more information about DSAPI and filters, see the Lotus C API Toolkit for Domino and Notes. The most current toolkit is available at http://www.lotus.com/techzone.

Denying Notes users access to all servers in a domain
To deny Notes users access to all servers in a domain, lock out their user IDs and enable password checking. When locked-out users try to access the server, Domino tries to verify the passwords they enter by comparing them against those stored in Person documents. Domino denies the users access because their IDs are locked out. This procedure applies only to Notes users. It does not apply to Internet users attempting to access a Domino server. It’s better to lock out user IDs instead of adding a group to the “Not access server” field. Using ID lockout ensures that users cannot view a list of names that have been denied server access. 1. Make sure that the Administration Process is set up and that you have Editor access in the ACL of the Domino Directory. 2. From the Domino Administrator, click the People & Groups tab, and select the Person documents of users to whom you want to deny access.
Controlling Access to Domino Servers 38-7

3. Choose Actions - Set Password Fields, and then click Yes when prompted to continue. 4. In the “Check Notes password” field, select Lockout ID, and then click OK. 5. Click the Configuration tab, open the Server document for the server to which you want to deny user access, and then click the Security tab. 6. In the Security Settings section, select Enabled for the “Check passwords on Notes IDs” field. 7. Repeat Step 4 for each server to which you want to deny the user access.

Restricting administrator access
You can specify various access levels for different types of administrators in your organization. For example, you may want to give only a few people ’system administrator’ access, while all of the administrators on your team are designated as database administrators. Administrator access rights are granted hierarchically. The privilege hierarchy looks like this: • • Full access administrator — gets all rights and privileges of all administration access levels listed. Administrator — gets all rights and privileges of database administrator and full-console administrator (but not system administrator). Full console administrator — gets rights and privileges of view-only console administrator (but not system administrator) System administrator — gets rights and privileges of restricted system administrator

• •

You do not need to list a user individually in each field. Adding a user to the highest level of administrator access automatically grants that user all privileges listed for more restricted access levels below in the hierarchy. To restrict administrator access 1. From the Domino Administrator, click the Configuration tab, and open the Server document. 2. Click the Security tab. 3. In the Administrators section, complete one or more of these fields, and then save the document.

38-8 Administering the Domino System, Volume 2

Security

For all of these fields, you can specify individual hierarchical names, groups, and wildcards (for example, */Sales/Acme). Separate multiple entries with commas. Note With the exception of the Administrators field, all of these fields are blank by default, meaning that no one has these access rights.
Field Action Enter the names of administrators who have full access to Full access administrators administer the server. This is the highest level of administrative privilege. For more information, see below. Administrators Enter the names of administrators who can administer the server. The default value for this field is the name of the administrator who initially set up the server. Administrators listed here have the following rights: • Manager access to the Web Administrator database (WEBADMIN.NSF). • • • • • • Create, update, and delete folder and database links Create, update, and delete directory link ACLs Compact and delete databases Create, update, and delete full text indexes Create databases, replicas, and Master Templates Get and set certain database options (for example, in/out of service, database quotas, and so on)

• Use message tracking and track subjects • Use the console to remotely administer UNIX servers • Issue any remote console command Database Enter the names of administrators who will be responsible administrators for administering databases on the server. Note that database administrators are not automatically granted Manager access to databases on the server, nor do they have any access to the Web Administrator database. Users listed here have the following rights only: • • • • • • Create, update, and delete Folder and Database links Create, update, and delete directory link ACLs Compact and delete databases Create, update, and delete full text indexes Create databases, replicas, and Master Templates Get and set certain database options (e.g., in/out of service, database quotas, etc.) continued

Controlling Access to Domino Servers 38-9

Field

Action

Full remote Enter the names of administrators who can use the remote console console to issue commands to this server. administrators Enter the names of administrators who can use the remote View-only administrators console to issue only those commands that provide system status information, such as SHOW TASKS and SHOW SERVER View-only administrators cannot issue commands that affect the server’s operation. Enter the names of administrators who are allowed to System administrators issue a full range of operating system commands to the server. The type and range of commands depends on the server operating system. For example, if the Domino server is an NT server, then these administrators can issue NT commands at the system command level prompt. Similarly, administrators for a UNIX server would be able to issue UNIX commands. Note This feature requires that you run the Domino server controller on the server machine. For more information, see the topic The Server Controller and Domino Console in the chapter “Setting Up and Using Domino Administration Tools.” Enter the names of administrators who are allowed to Restricted issue only the operating system commands that are listed system administrators in the Restricted System Commands field (see below). Note This feature requires that you run the Domino server controller on the server machine. For more information, see the topic The Server Controller and Domino Console in the chapter “Setting Up and Using Domino Administration Tools.” Restricted system commands Enter the subset of operating system commands that Restricted System Administrators can issue. The type and range of commands depends on the server operating system and the tasks that restricted system administrators need to do. For example, you may want to have a restricted system administrator for managing UNIX print queues. Enter the UNIX commands for managing print queues in this field. Any names you enter in the “Restricted system administrators” field will then have access to these commands only. continued

38-10 Administering the Domino System, Volume 2

Security

Field Administer the server from a browser (pre-Domino 6 servers only)

Action This setting applies only to pre-Domino 6 servers for the purposes of backwards compatibility. The Domino 6 Web Administrator client will only work with Domino 6 servers. In the case where an Domino 5 to Domino 6, those servers that have not been upgraded will still need to have this setting in their Server documents so they can use earlier versions of the Web Administrator.

Caution Administrators who are listed in the Full Access Administrators, Administrators, and Database Administrators fields on the Security tab of a server document are allowed to delete any database on that server, even if they are not listed as managers in the database ACL.

Full access administrators
Full access administrator is the highest level of administrative access to the server. The full access administrator feature replaces the need to run a Notes client locally on a server. It resolves access control problems — for example, such as those caused when the only managers of a database ACL have left an organization. Full access administrators have the following rights: • • • • • • All the rights as listed for all administrator access levels (see above). Manager access, with all roles and access privileges enabled, to all databases on the server, regardless of the database ACL settings. Manager access, with all roles and access privileges enabled, to the Web Administrator database (WEBADMIN.NSF). Access to all documents in all databases, regardless of Reader names fields. The ability to create agents that run in unrestricted mode with full administration rights. Access to any unencrypted data on the server. Note Full access administrator does not allow access to encrypted data. The use of the specified user’s private key is required to decrypt documents that are encrypted with public keys. Similarly, a secret key is required to decrypt documents encrypted with secret keys.

Controlling Access to Domino Servers 38-11

Enabling full access administrator mode In order to work in full access administrator mode, an administrator must: • Be listed in the Full Access Administrators field in the Administrators section of the Security tab in the Server document. By default, this field is empty. Enable “Full Access Administration” mode in the Administrator client by selecting Administration - Full Access Administration. If this mode is not enabled, then users will not have full administrator access to the server, even if they are listed as a full access administrator in the Server document. They will instead be granted Administrator rights.

When full access administrator mode is enabled, the client’s window title, tab title, and status bar indicate this. This is to remind users that they are accessing the server with the highest level of privilege and should therefore proceed with caution. If an administrator enables full administration mode in the Administration client, this mode is also enabled for the Domino Designer and for the Lotus Notes clients. Full administrator access is also reflected in their window titles, tab titles, and status bars. If a user attempts to switch to full access administrator mode, but is not listed as one in the Server document, the user is denied full access and a message appears in the status bar and on the server console. The client will be in full access mode, but that user will not have full administrator access to that particular server. If the user attempts to switch servers, that person’s access is checked against the server document of the new server. Disabling the full access administrator feature You can disable the Full Access Administrators field by setting SECURE_DISABLE_FULLADMIN = 1 in the NOTES.INI file. This setting disables full access adminstrator privilege and overrides any names listed in that field in the Server document. This NOTES.INI parameter can only be set by a user with physical access to the server who can edit the NOTES.INI file for the server. This parameter cannot be set using the server console, the remote console, or set in the Server document.

38-12 Administering the Domino System, Volume 2

Security

Options for managing the full access administrator feature There are several ways to grant full access administrator: • Create a special Full Admin ID file — for example, “Full Admin/Sales/Acme” — and only put that name in the Full Admin field. You must then either log in with or switch to this user ID in order to gain this level of access. Optionally, you could set up this ID file to require multiple passwords. Create an OU-level certifier for granting full administrator access, and issue additional IDs to trusted administrators — for example, Jane Admin/Full Admin/Acme. Leave the Full Access Administrator field empty. Add the name of a trusted individual for emergency situations, and remove it when the situation has been resolved. Populate the Full Access Administrator field with a limited set of trusted administrators. Configure the Event Handler to send notification through EVENTS4.NSF when full access administration privileges are invoked. Any database activity done using full access administrator access is recorded in the database activity log, under Database Properties. Use of the feature is logged by the server.

You can also track how this feature is used: •

• •

Setting up anonymous server access for Notes users and Domino servers
When a server is set up for anonymous access, Notes users and Domino servers do not need a valid certificate to access the server, since the server does not validate or authenticate them. Use anonymous access to allow users and servers outside your organization to access a server without first obtaining a certificate for the organization. You can also set up anonymous access for Internet/intranet users. For more information on anonymous Internet/intranet access, see the chapter “Setting Up Name-and-Password and Anonymous Access to Domino Servers.” 1. From the Domino Administrator, click the Configuration tab, and open the Server document. 2. Click the Security tab. 3. In the Security Settings section, enable “Allow anonymous Notes connections.”
Controlling Access to Domino Servers 38-13

4. Save the document. 5. Create an entry named Anonymous in the ACL of all databases to which you want to allow anonymous access. Assign the appropriate access level — typically Reader access. If you don’t add Anonymous as an entry in the ACL, anonymous users and servers get -Defaultaccess. 6. Stop and restart the server so that the changes take effect.

Controlling access to a specific server port
Use a port access list to allow or deny Notes user and Domino server access to a specific network port. If you use a port access list and a server access list, users and servers must be listed on both to gain access to the server. To control access to a specific port, use these NOTES.INI settings: • • Allow_Access_portname = names Deny_Access_portname = names where portname is the name of the port, and names is a list of users, servers, and groups to whom you want to deny or allow access. These names must be contained in the Domino Directory. For more information, see the appendix “NOTES.INI File.”

Controlling creation of databases, replicas, and templates
To manage available disk space, control which users and servers are allowed to create databases and replicas on a server. If your system uses multiple Domino Directories, Domino searches only the first Domino Directory specified in the Names setting in the NOTES.INI file. If the server allows a user to create database replicas, but a particular database ACL prevents it, the user cannot create a replica for that database. Tip Create a group named “Replica Makers” that lists the names of all people who can create replicas on servers. Enter the group name “Replica Makers” in the “Create replica databases” field in each Server document in the Domino Directory. 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click the Security tab.

38-14 Administering the Domino System, Volume 2

Security

3. In the Server Access section, complete one or more of these fields, and then save the document:
Field Create new databases and templates Action Enter any of these: • Names of specific servers, users, and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to create databases. • An asterisk (*) followed by a view name — for example, *($Users) — to allow all names that appear in a specific view in the Domino Directory to create databases. Access time is quicker if you specify a group name rather than a view name. The default value for this field is blank, which means that all users can create new databases. Separate multiple names with commas or semicolons. Create replica databases Enter any of these: • Names of specific servers, users, and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to create replicas. • An asterisk (*) followed by a view name — for example, *($Users) — to allow all names that appear in a specific view in the Domino Directory to create replicas. Access time is quicker if you specify a group name rather than a view name. Note Servers, users, and groups who cannot create new databases on the server (see above) cannot create replicas. The default value for this field is blank, which means that no one can create new replicas. Separate multiple names with commas or semicolons. continued

Controlling Access to Domino Servers 38-15

Field Create master templates

Action Enter any of these: • Names of specific servers, users, and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to create templates. • An asterisk (*) followed by a view name — for example, *($Users) — to allow all names that appear in a specific view in the Domino Directory to create replicas. Access time is quicker if you specify a group name rather than a view name. Note Servers, users, and groups who cannot create new databases or replicas on the server (see above) cannot create or update templates. The default for this field is blank, which means that no one can create master database templates on the server. Separate multiple names with commas or semicolons.

For information on creating groups, see the chapter “Setting Up and Managing Groups.”

Controlling the use of headline monitors
This setting is for Notes users only. Notes users can set up their headlines to search server databases automatically for items of interest. This setting controls which users can or cannot access this server for headlines. Note If many users use this feature, server performance may be slow. For information about headlines, see Lotus Notes 6 Help. 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click the Security tab.

38-16 Administering the Domino System, Volume 2

Security

3. In the Server Access section, complete one or both of these fields, and then save the document:
Field Allowed to use monitors Action Enter any of these: • Names of specific users and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to use a monitor. • An asterisk (*) followed by a view name — for example, *($Users) — to allow all names that appear in a specific view in the Domino Directory to use monitors. Access time is quicker if you specify a group name rather than a view name. Separate multiple names with commas or semicolons. The default for this field is * (all users). Leave the field blank to allow no one to use headline monitors. Not allowed to use monitors Enter any of these: • Names of specific users and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to prevent users certified by a particular certifier from using monitors. • An asterisk (*) followed by a view name — for example, *($Users) — to prevent all names that appear in a specific view in the Domino Directory from using monitors. Access time is quicker if you specify a group name rather than a view name. Separate multiple names with commas or semicolons. The default for this field is blank, meaning that no one is restricted from using monitors. Use an asterisk (*) to prevent all users from using monitors.

You can also restrict users from monitoring an individual database. For more information, see the chapter “Improving Database Performance.”

Controlling access to a passthru server or passthru destination
A passthru server allows users and servers to use a passthru connection to connect to another server. The server to which users connect is called a passthru destination. You can control which users and servers can access a passthru server and passthru destination. For more information on passthru servers, see the chapter “Setting Up Server-to-Server Connections.”

Controlling Access to Domino Servers 38-17

If your system uses multiple Domino Directories, Domino searches only the first Domino Directory specified in the Names setting in the NOTES.INI file. Internet and intranet clients cannot use passthru; therefore, these settings are valid only for Notes users and Domino servers. 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click the Security tab. 3. In the Passthru Use section, complete one or more of these fields, and then save the document:
Field Access this server Action Enter any of these: • Names of specific servers, users, and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to access the server. • An asterisk (*) followed by a view name — for example, *($Users) — to allow access to all names that appear in a specific view in the Domino Directory. Access time is quicker if you specify a group name rather than a view name. Any users or servers listed in this field can use a passthru server to access this server. This field does not take precedence over other access fields — for example, the “Access server” and “Not access server” fields. For example, if the “Access server” field specifies that only users listed in the Domino Directory can access this server, users who are not in the local domain cannot access this server. The default for this field is blank, which means that users and servers are prevented from using a passthru connection to access this server. Separate multiple names with commas or semicolons. continued

38-18 Administering the Domino System, Volume 2

Security

Field Route through

Action Enter any of these: • Names of specific servers, users, and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to access the server. • An asterisk (*) followed by a view name — for example, *($Users) — to allow access to all names that appear in a specific view in the Domino Directory. Access time is quicker if you specify a group name rather than a view name. Any users or servers listed in this field can use the server as a passthru server, regardless of whether or not they are also included in the “Access server” or “Not access server” fields. The default for this field is blank, which means that users and servers are prevented from using this server for passthru access. Separate multiple names with commas or semicolons.

Cause calling

Enter any of these: • Names of specific servers, users, and groups. • An asterisk (*) followed by a certificate name — for example, */Sales/East/Acme — to allow all users certified by a particular certifier to initiate calling. • An asterisk (*) followed by a view name — for example, *($Users) — to allow all names that appear in a specific view in the Domino Directory to allow calling. Access time is quicker if you specify a group name rather than a view name. Any users or servers listed in this field can instruct this server to call — that is, place a phone call to — another server in order to establish a routing path to that server. If no names are entered, no calling is allowed. In general, if the Replicator on another server uses the modem on a server to reach its targets, the server name of the Replicator must be included in this list on the server with the modem. Otherwise, the replication will frequently fail. The default for this field is blank, which means that users and servers are prevented from using this server to route a path to another server. Separate multiple names with commas or semicolons. This field corresponds to the Allow_Passthru_Callers setting in the NOTES.INI file. If a conflict exists, the “Cause calling” field takes precedence. continued Controlling Access to Domino Servers 38-19

Field Destinations allowed

Action Enter the names of destination servers to which this server may route clients. The default for this field is blank, which means that all servers may be routed to. This field corresponds to the Allow_Passthru_Targets setting in the NOTES.INI file. If a conflict exists, the “Destinations allowed” field takes precedence.

Controlling agents that run on a server
To control the types of agents users can run on a server, set up restrictions for server agents. The fields in this section are organized hierarchically with regard to privileges. “Run unrestricted methods and operations” has the highest level of privilege and “Run Simple and Formula agents” has the lowest. A user or group name in one list will automatically receive the rights of the lists beneath. Therefore a name has to be entered in only one list, which then gives that user the highest rights. Tip Create a group for each class of users to be used in every category. For a list of restricted LotusScript and Java features and information about agents, see Application Development with Domino Designer. For information on creating groups, see the chapter “Setting Up and Managing Groups.” 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click the Security tab.

38-20 Administering the Domino System, Volume 2

Security

3. In the Programmability Restrictions section, complete one or more of these fields, and then save the document:
Field Run unrestricted methods and operations Action Enter the names of users and groups who are allowed to select, on a per agent basis, one of three levels of access for agents signed with their ID. Users with this privilege select one of these access levels when they are using Domino Designer 6 to build an agent: restricted mode unrestricted mode unrestricted mode with full administration rights. Only users who have this access can choose an option other than “do not allow restricted operations.” This access is enabled by default for the current server and Lotus Notes Template developers. If users in this list are also listed as a database administrator in the Server document, they are allowed to perform database operations without having to be listed explicitly in the database ACL. (for example, they can delete databases without being listed in the ACL of those databases). To have the ability to run agents in unrestricted mode with full administration rights, the agent signer should be listed in this field, or in the Full Access Administrator field, as well as have this mode selected in the Agent Builder. Being listed in Full Access Administrator list alone is not sufficient to run agents in this mode.

Sign agents to run Enter the names of users and groups who are allowed to on behalf of sign agents that will be executed on anyone else’s someone else behalf. The default is blank, which means that no one can sign agents in this manner. This privilege should be used with caution, as the name for whom the agent is signed on behalf of is used to check ACL access. Sign agents to run on behalf of the invoker of the agent Enter the names of users and groups who are allowed to sign agents that will be executed on behalf of the invoker, when the invoker is different from the agent signer. This setting is ignored if the agent signer and the invoker are the same. This is used currently only for Web agents. The default is blank, which means that everyone can sign agents invoked in this manner (this is for backwards compatability). continued

Controlling Access to Domino Servers 38-21

Field

Action

Run restricted Enter the names of users and groups allowed to run LotusScript/Java agents created LotusScript and Java features, but agents excluding privileged methods and operations, such as reading and writing to the file system. Leave the field blank to deny access to all users and groups. Run simple and formula agents Enter the names of users and groups allowed to run to run simple and formula agents, both private and shared. Leave the field blank to allow all users and groups to run simple and formula agents, both private and shared. Enter the names of users and groups who are allowed to sign script libraries in agents executed by someone else. For the purposes of backwards compatibility, the default value is to leave the field empty, to allow all.

Sign script libraries to run on behalf of someone else

Controlling server access by browser clients that use Java and JavaScript
Note These settings are for use only with R5.x and earlier servers. They should not be used with a Domino 6 server and are included for the purpose of backwards compatibility only, to be used to manage prior releases of Domino servers with the Lotus Notes 6 client. For more information on the DIIOP task, see the chapter “Setting Up the Domino Web Server.” 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click the Security tab. 3. In the Programmability Restrictions section, complete one or both of these fields, and then save the document:
Field Action Run restricted Enter the names of authenticated browser users Java/JavaScript/COM and/or groups allowed to run server programs created with a specific set of Java and JavaScript features. Leave the field blank (default) to deny access to all users and groups. Run unrestricted Enter the names of authenticated browser users Java/JavaScript/COM and/or groups allowed to run server programs created with all Java and JavaScript features. Leave the field blank (default) to deny access to all users and groups.

38-22 Administering the Domino System, Volume 2

Security

For a list of restricted Java and JavaScript classes, see Application Development with Domino Designer.

Controlling Web browser access to files
You can use the following security features to control Internet/intranet access to files on the servers: • • File protection documents Web realms

Physically securing the Domino server
Physically securing servers and databases is just as important as preventing unauthorized user and server access. Therefore, locate all Domino servers in a ventilated, secure area, such as a locked room. If servers are not secure, unauthorized users might circumvent security features — for example, ACL settings — access applications on the server, use the operating system to copy or delete files, and physically damage the server hardware itself. To ensure maximum physical security for servers, do one or more of the following: • • Use the server without a mouse, and keep the keyboard locked. Password-protect the server ID. If an ID uses a password, you must manually restart the server rather than restart it automatically. To restart the server, you must know the server password. Use the Set Secure command to password-protect the console and restrict what can be done while the server is running. For more information on the Set Secure command, see the appendix “Server Commands.” • Use the Local Security option to encrypt databases on the server with the server ID. Then people at the server can access databases only if they have access to the server ID that was used to encrypt the databases. Use operating system features to secure data files and lock keyboard access. For more information, see your operating system documentation.

Controlling Access to Domino Servers 38-23

Securing the server console with a Smartcard
Beginning with Lotus Notes 6, Notes users can use a Smartcard with their User ID to log in to Notes. Smartcard use requires the installation of a Smartcard reader on the user’s computer, along with the Smartcard software and drivers. The advantage of using a Smartcard with Notes is that the Smartcard locks User ID. Logging into Notes with a Smartcard requires the Smartcard, the User ID, and the user’s Smartcard PIN. For more information about how Notes users set up Smartcards, see the topic Enabling Smartcards for Notes login. Administrators can take advantage of Smartcard security to physically secure the Domino server console. In this case the administrator would be locking the Server ID with the Smartcard. To secure the server console with a Smartcard Caution Ensure that the server.id is recoverable via the ID File Recovery before proceeding. Also, verify that the encrypted backup copy of the server.ID exists in the ID file repository. Before you begin: • • Have the Domino server workstation on, but do not launch the Domino server software. Modify the Domino server’s NOTES.INI file to include a variable, PKCS11_Library=, that points to the Smartcard PKCS#11 file. This file will be loaded during Smartcard installation. For example:
PKCS11_Library=C:\Program Files\Schlumberger\Smart Cards and Terminals\Common Files\slbck.dll

Caution If you do not modify the server’s NOTES.INI file to include the PKCS11_Library variable, when you try to launch the Domino server, it will shut down and return a “Login aborted by user” error. 1. On the Domino server workstation, install a Smartcard reader and Smartcard driver files. 2. On a Notes client workstation, install a Smartcard reader and the same Smartcard driver files as you installed on the Domino server. This workstation will be used to configure the Smartcard for the server. 3. Copy the server.id from the Domino server onto a diskette. Insert the diskette into the Notes workstation. 4. Launch the Notes client with a User ID from the domain for which the server has a certificate. 5. Place the Smartcard designated for the server into the card reader of the Notes client. If required, enter the Smartcard PIN.
38-24 Administering the Domino System, Volume 2

Security

6. Click File - Security - Switch ID to switch to the copy of the server.id file. 7. Do the following to enable the server.id file for the associated Smartcard a. Click File - Security - User Security, and enter the password for the server.id. b. Click Smartcard Options. c. Click “Enable Smartcard Login.” d. Enter password (if needed) and the Smartcard PIN. After approximately 10 to 15 seconds, the Smartcard will be configured for the server.id file. 8. Copy the Smartcard-enabled server.ID file back to the server’s Domino\data directory. 9. Place the Smartcard in the Domino server card reader, and launch Domino. 10. At the server command console, enter the Smartcard PIN when prompted and Domino will launch.

Controlling Access to Domino Servers 38-25

Security

Chapter 39 Protecting and Managing Notes IDs
This chapter describes how to control access to Domino server and Notes user IDs.

Domino server and Notes user IDs
Domino uses ID files to identify users and to control access to servers. Every Domino server, Notes certifier, and Notes user must have an ID. When you register users and servers, Domino automatically creates their IDs. An ID file contains: • • The owner’s name. A user ID file may also contain one alternate name. A certifier ID may contain multiple alternate names. A permanent license number. This number indicates that the owner is legal and specifies whether the owner has a North American or International license to run Domino or Notes. At least one Notes certificate from a certifier ID. A Notes certificate is a digital signature added to a user ID or server ID. This signature, which is generated from the private key of a certifier ID, verifies that the name of the owner of the ID is correctly associated with a specific public key. A private key. Notes uses the private key to sign messages sent by the owner of the private key, to decrypt messages sent to its owner, and, if the ID belongs to a certifier, to sign certificates. (Optional Notes client only) Internet certificates. An Internet certificate is used to secure SSL connections and encrypt and sign S/MIME mail messages. An Internet certificate is issued by a Certification Authority (CA) and verifies the identity of the user. The user’s private key associated with an Internet certificate is stored with that certificate. (Optional) One or more secret encryption keys, created and distributed by users to allow other users to encrypt and decrypt fields in a document.

39-1

Note If a user is in the process of requesting a new private key or a name change, the pending information is also stored in the ID file. If a Notes private key is changed, then the obsolete information is also stored in the ID file for backwards compatibility. For example, you would need the obsolete information to read old encrypted e-mail.

Certificates
A certificate is a unique digital signature that identifies a user or server. Server and user IDs contain one or more Notes certificates. In addition, user IDs may contain one or more Internet certificates that identify users when they use SSL to connect to an Internet server or send a signed S/MIME mail message. A certificate contains: • • • The name of the certifier that issued the certificate. The name of the user or server to whom the certificate was issued. A public key that is stored in both the Domino Directory and the ID file. Notes uses the public key to encrypt messages that are sent to the owner of the public key and to validate the ID owner’s signature. A digital signature. The expiration date of the certificate.

• •

Certificates are stored in ID files and in Person, Server, and Certifier documents in the Domino Directory. They are also referred to as Notes certified public keys. Public keys are not secret. Any user may look up another user’s public key and use it to send encrypted mail to or authenticate the user. It is important that someone looking up a public key learn it reliably since Domino uses it for identification. Users must be able to obtain the public key of the certifier that issued the certificate before they can authenticate the certificate’s owner. If a user has a certificate issued by the same certifier as another user or server, the first user can verify the public key for the certificate and then reliably know the public key associated with the server or user name. If a user doesn’t have a certificate issued by the same certifier, the user needs a cross-certificate for authentication. When you register users and servers, Domino automatically creates a Notes certificate for each user and server ID. In addition, you can use a Domino or third-party certificate authority (CA) to create Internet certificates for user IDs. Domino uses the x.509 certificate format to create Internet certificates.

39-2 Administering the Domino System, Volume 2

Security

Notes certificates have expiration dates. Therefore, you must recertify Notes IDs when their expiration dates approach. In addition, if a user or server name changes, you must recertify the corresponding Notes ID so that a new certificate will bind the public key to the new name. Changing a name on a user ID may also affect Internet certificates. For example, a user who has changed the name on a user ID may receive warning messages when sending signed S/MIME mail, warning the user that recipients of the message may receive a signature by a name that isn’t on the original certificate used for signing.

Viewing the certificates on an ID
You can display the Notes and Internet certificates associated with an ID and display information about each certificate — for example, public key, creation date, expiration date, and certifier information. For example, the Certificates box displays certificates for a Notes user ID with the name Alan Jones/Sales/East/Acme. The first certificate listed below is the one issued to Alan Jones for international use. The second certificate listed below is the one issued to Alan Jones for North American use and for electronic signing. Following these are the certificates issued to the certifier of the ID and to any ancestors of the certifier. The last certificate listed below is the Internet certificate issued to Alan Jones.
Certificate /Sales/East/Acme (International) /Sales/East/Acme (North American) /East/Acme /Acme /Acme Issued to Alan Jones/Sales/East/Acme Alan Jones/Sales/East/Acme /Sales/East/Acme /East/Acme /Acme

CN=AcmeCA/OU=East/O=Acme/L= EMAIL=alan_jones@acme.com/CN= Cambridge/ST=Massachusetts/C=US AlanJones/OU=East/O=Acme/L= Cambridge/ST=Massachusetts/C=US

To view certificates 1. From the Domino Administrator, click Configuration - Certification. 2. Click ID Properties. 3. Choose the ID file to view. 4. Enter the password and click OK.

Protecting and Managing Notes IDs 39-3

5. In the ID Properties dialog box, do the following: a. Click Your Identity - Your Certificates to display a list of all Notes and Internet certificates issued to this ID file. b. Select the certificate in the Certificates box to display additional information about the certificate. c. To get more information about a certificate, highlight it in the list and click Advanced Details. Here you can specify a default Internet signing certificate if there are multiple Internet certificates in the ID file. For more information on using Internet certificates, see the chapter “Setting Up Clients for S/MIME and SSL.” For more information on how Notes users can view certificates in their IDs, see Lotus Notes 6 Help.

Password-protection for Notes and Domino IDs
To ensure the security of the Domino system, password-protect all Notes and Domino IDs — certifier, server, and user. When you password-protect an ID, a key that is derived from the password encrypts the data on the ID. Then, when you attempt to access mail, open a server-based database, or examine ID file information, you are prompted to enter a password. Note that this information does not apply to password-protection for Internet clients. For information on password protecting Internet clients, see the chapter “Setting Up Name-and-Password and Anonymous Access to Domino Servers.”

Password-protection features
Password quality When you register a user or server or create a certifier ID, you use a scale of 0 to 16 to specify the level of password quality you want enforced for the ID. The higher the level, the more complex the password and, therefore, the more difficult it is for an unauthorized user to guess the password. For optimal security, specify a password quality level of at least 8. The password quality level you assign is enforced when you enter a password for new IDs or when users change the password for an existing ID. When users change their passwords, Notes displays information about the password quality level required by the ID file. Users must enter a password that meets the criteria for the level; otherwise, they are not allowed to change the password.
39-4 Administering the Domino System, Volume 2

Security

When choosing a password, it is best to specify a random, alphanumeric string that includes mixed uppercase and lowercase letters, numbers, and punctuation. Also, it is better to specify an entire phrase, rather than a single word. A passphrase is easy to remember, difficult to guess, and generally longer than a single-word password. If you choose to use a phrase, you should misspell one or more of the words to make it more difficult for attackers to guess at the phrase. To change the password quality level assigned to an ID, you must recertify the ID or use a security settings policy document. For more information about using a security settings policy document to manage IDs, see the chapter “Using Policies.” For more information on password quality, see the topic “Understanding the password quality scale” later in this chapter. Time-delay and anti-spoofing mechanisms All passwords for Notes IDs have built-in time-delay and anti-spoofing mechanisms, both of which deter password-guessing programs and prevent password theft by programs that resemble the password-prompt dialog box. The time-delay mechanism delays the time it takes to be able to proceed after an incorrect password is typed. When a user types a password, the anti-spoofing mechanism creates a graphic pattern that other programs cannot reproduce. Password and public-key verification during authentication By default, Notes and Domino use passwords only to protect information stored in ID files. However, you can configure servers to verify passwords and Notes public keys during authentication. Password and public-key verification reduces the unauthorized use of IDs. If you set up a server to verify passwords and an unauthorized user obtains an ID and its password, the authorized user just needs to change the password for the ID. Then, the next time the unauthorized user attempts to authenticate, that user will not be allowed access to the server because Domino informs the user that they must change the password on this copy of the ID to match that on another copy of their ID (which the unauthorized user doesn’t know). Along with verifying passwords, you can set up servers to require users to change their password periodically. For more information on verifying passwords, see the topic “Verifying user passwords during authentication” later in this chapter. For more information on verifying public keys, see the topic “Public key security” later in this chapter.

Protecting and Managing Notes IDs 39-5

Multiple passwords To provide tighter security for certifier and server IDs, assign multiple passwords to those IDs. Using multiple passwords requires that a group of administrators work together to access an ID. For example, this feature is useful when you want to avoid giving authority for a certifier ID to one person. You can specify that only a subset of the assigned passwords be required to access the ID. For example, you can assign four passwords to the ID but require that only any two of the four passwords be entered to gain access to the ID. Requiring only a subset of the passwords allows administrators to access the ID, even when all of the administrators are not available. Note User IDs can also be secured with multiple passwords. For more information on multiple passwords, see the topic “Assigning multiple passwords to server and certifier IDs” later in this chapter. ID file recovery If you have ID recovery in place, when a user loses an ID file or forgets the password to the ID file, a group of administrators can work together to recover the ID file. Losing an ID file normally prevents users from accessing servers and reading messages and other data that they encrypted with the ID. Using the ID file recovery feature, administrators can prevent this loss of access and prevent unauthorized users from illicitly recovering IDs. For more information on ID file recovery, see the topic “ID file recovery” later in this chapter. Using a Smartcard to secure a Notes ID When using Smartcards to log into Notes, users are essentially locking and unlocking their user IDs. The advantage of using a Smartcard with Notes is that the user’s Internet private keys can be stored on the Smartcard instead of on the workstation. Then users can take Smartcards with them when they are away from their computers. For both regular and roaming users, Smartcards increase user ID security. Caution In order for Notes users to set up Smartcards, you must disable password checking, change/grace intervals and expiration in the user’s Person document. Otherwise, Smartcard users will eventually be locked out. For more information on how Notes users can use Smartcards, see Lotus Notes 6 Help.

39-6 Administering the Domino System, Volume 2

Security

The password quality scale
When creating passwords for user, server, or certifier IDs, you need to understand the criteria by which Domino measures password strength and security. Domino measures this criteria according to the level assigned on its password quality scale. The scale assigns a minimum level of quality to the password on an ID file. Domino bases the password quality on the number and variety of characters in the password. The algorithm used to calculate password quality is used to enforce the selection of passwords that are sufficiently complex to meet the password quality scale level chosen to protect user ID files. When a user is registered, the user’s ID file contains a password strength value. This setting is enforced if the user changes the password. The scale ranges from 0 (weakest — no password required) to 16 (strongest). A quality of 1 indicates that any password satisfies the criteria. Domino defines default levels for certifier, server, and user password quality. You should change these defaults to meet your organization’s security criteria. You can set the defaults in a security settings policy document, in Administration Preferences, or in the registration or certification dialog boxes. Password strength is not the same as password length. Not all passwords of equal length have equal strength in the password quality scale. For example, the 8-character word “password” (because it is a word) and the 8-character word “1168Acme” (because it contains numbers and alphabetic characters) do not carry the same level of character complexity and do not have equal strength on the quality scale.
Password quality scale Description 0 1 2-6 Password is optional. Allow any password. Allow a weak password, even though you might be able to guess it by trial and error. Require a password that is difficult to guess, but might be vulnerable to an automated attack. Example None. “b”, “3” “password”, “doughnut” (password quality scale 3) “lightferret”, “b 4D” (password quality scale 6) “pqlrtmxr”, “wefourkings” (password quality scale 8)

7-12

continued

Protecting and Managing Notes IDs 39-7

Password quality scale Description 13-16 Require a strong password, even though the user may have difficulty remembering it.

Example “4891spyONu” (password quality scale 13) “lakestreampondriverocean”, “stRem2pO()” (password quality scale 15) “stream8pond1river7lake2ocean ”(password quality scale 16)

Tips for assigning passwords and scale
• Do not use words in a password that are in the Domino spell-check dictionary. Passwords containing words found in a Domino spell-check dictionary are generally weaker than passwords of equal length that do not contain words from the spell-check dictionary. Use mixed-case words and words that contain numbers and punctuation for passwords instead of entirely lowercase alphabet characters. To make a password stronger without making it longer, avoid using words; instead use mixed-case characters and include punctuation and numbers. Use a passphrase instead of a password. A complete sentence, especially one with a word or two misspelled, is a strong password that an attacker would have difficulty guessing. Use passwords that have a quality of 12 or higher. Passwords that have a quality of 12 or higher are resistant to an automated attack. Passwords that have a quality below 4 are easy to guess. Set a default value for all Password Quality Scale fields so that all passwords assigned to servers, users, and certifier IDs in your organization have appropriate levels of complexity.

Verifying user passwords during authentication
You can enable password verification so that a Notes user can authenticate with a server only after providing the correct password that is associated with the user ID. If an unauthorized user obtains an ID and learns the ID’s password, the owner of the ID can use password verification to change the password and prevent the unauthorized user from continuing to use the ID to authenticate with servers. The next time the unauthorized user tries to use the ID with the old password to access a server, the server verifies the password, determines that the password entered does not match the new password, and denies the unauthorized user access to the server. Without password verification, an
39-8 Administering the Domino System, Volume 2

Security

unauthorized user could use an ID and password even after the user changed the password on the ID, since, by default, the password is used only to decrypt the ID file and is not verified against the password stored in the Domino Directory. If you set up password verification, require users to change the passwords on their IDs on a regular basis. As the time for the required password change approaches (after two-thirds of the current change interval has passed, but at a minimum of two days remaining), a prompt appears to remind the user to change the password. When users change the password, the current ID and Person document are updated with the new password. If a user has multiple ID files, the user change the password in each of them to match the new password. You cannot use password verification on ID files that contain multiple passwords. Each time a user changes a password, the user must specify a unique password. Notes keeps a record of up to 50 passwords that have been previously used. If you enable password history checking (through the use of a security settings document), you can configure the number of new passwords that must be used before a given password can be reused. An expired password doesn’t prevent a user from reading encrypted mail or creating new signed documents on local replicas; however, without specifying a new password, users cannot access databases on servers. Note that password verification during authentication will not work for Internet users because they do not have Notes user IDs (unless their Notes and Internet passwords have been synchronized). Caution Do not enable password expiration for users whose ID files are locked with Smartcards. Otherwise, it is possible that a user’s ID could be locked out until the password digest can be cleared.

The Administration Process and password verification
Password verification requires the Administration Process to update documents in the Domino Directory. When you enable password verification for a user, the Administration Process creates a “Set Password Information” request in the Administration Requests database. Domino carries out this request according to the setting in the Interval field in the Administration Process section of the Server document. This request enables password-checking by entering values in the Check password, Required change interval, and Grace period fields in the Administration section of the user’s Person document.

Protecting and Managing Notes IDs 39-9

The first time the user logs onto a server that requires password verification, the Administration Process generates a “Change User Password in Domino Directory” request in the Administration Requests database. This request enters a corresponding password digest in the Password digest field in the Administration section of the Person document. It also records the date the user provided the password in the Last change date field in the Administration section of the Person document. To authenticate with servers that are enabled for password verification, the user must provide the password that corresponds to the digest. From then on, when a user changes a password, the Administration Process generates a new “Change User Password in Domino Directory” request in the Administration Requests database. This request updates the Password digest and Last change date fields in the Person document. Note that if you modify the change interval or grace period after you enable password verification, the Administration Process must update the fields in the Person document and then user must change the password for the change to take effect. For information on the Administration Process, see the chapter “Setting Up the Administration Process.”

Required change intervals and grace periods
You can set up a server to verify users’ passwords during authentication without requiring them to change their passwords. If you require password changes, you can specify a grace period that indicates the length of time after the change interval expires before users are locked out of the server. If a required change interval expires before the user changes the password, the user can’t authenticate with servers that require password verification until the user creates a new password. If a grace period expires and the user still hasn’t changed the password, the user can’t authenticate until the administrator manually deletes the data in the Password digest field in the Person document and the user creates a new password. If an unauthorized user changes the password on an ID before the authorized owner of the ID does, the authorized owner can’t authenticate and sees this message: You have a different password on another copy of your ID file and you must change the password on this copy to match. In this case, delete the entry in the Password digest field, and ask the authorized user to log on immediately and enter a new password. Caution For users whose ID files are locked with Smartcards, set the required change interval and grace period to 0. Otherwise, it is possible that a user’s ID could be locked out.
39-10 Administering the Domino System, Volume 2

Security

Setting up password verification
You can enable password verification through the use of a security policy settings document, which allows you to enable this feature for multiple users, or you can enable password verification on an individual basis through the Domino Directory. You can also choose to lock out a user’s ID, which prevents the user from logging into the server. For more information on the security policy settings document, see the chapter “Using Policies.” To enable password verification for individual users 1. Make sure that: • The Administration Process is set up on the server • You have at least Author access and the UserModifier role in the Domino Directory. • Password verification is enabled on the servers with which these users authenticate. 2. From the Domino Administrator, click People & Groups. 3. Select each Person document for which you want to enable password checking. 4. Choose Actions - Set Password Fields, and then click Yes to continue. 5. In the Check Notes Password field, select “Check password.” 6. Complete these fields, and then click OK:
Field Required change interval Allowed grace period Action Enter the length of time, in days, that a password can be in effect before it must be changed. Default is zero. Enter the length of time, in days, that users have to change an expired password before being locked out. Default is zero.

7. (Optional) You can also choose to force individual users to change their Internet passwords the next time they log in. In the “Force users to change Internet password on next login” dialog box, click Yes. Caution Do not enable password expiration for users whose ID files are locked with Smartcards. Otherwise, it is possible that a user’s ID could be locked out until password expiration can be cleared. You should also be sure that the required change interval and allowed grace period is set at zero.

Protecting and Managing Notes IDs 39-11

To disable password verification for an individual user When you disable password verification for a user, Domino does not check passwords for the user even if password verification is enabled for the server. 1. From the Domino Administrator, click People & Groups using a network connection to the Domino Directory. 2. Select each Person document for which you want to enable password checking. 3. Choose Actions - Set Password Fields, and then click Yes to continue. 4. In the Set Passwords Fields dialog box, select “Don’t check password,” and then click OK. To lock out an individual user's ID 1. From the Domino Administrator, click People & Groups using a network connection to the Domino Directory. 2. Select the Person document of the user whose ID will be locked out. 3. Choose Actions - Set Password Fields, and then click Yes to continue. 4. In the Set Passwords Fields dialog box, select “Lockout ID,” and then click OK. To enable password verification on servers To use password verification for Notes users, you must enable password verification for both users and servers. Do the following to enable password verification on each server with which these users authenticate: 1. From the Domino Administrator, click Configuration. 2. Open the Server document of the server for which you want to enable password verification. 3. Click Security, and then in the “Check passwords on Notes IDs” field, select Enabled. 4. Repeat for each server on which you want to enable password verification. To disable password verification for a server When you disable password verification for a server, Domino does not check passwords for any users who access the server, even if the user has password verification enabled. 1. From the Domino Administrator, click Configuration. 2. Open the server document of the server for which you want to disable password verification.
39-12 Administering the Domino System, Volume 2

Security

3. Click Security, and then in the “Check passwords on Notes IDs” field, select Disabled. 4. Repeat for each server on which you want to disable password verification.

Assigning multiple passwords to server and certifier IDs
To assign multiple passwords To complete these steps, you must gather together all of the administrators whose passwords will be assigned to the ID. Each administrator must complete a series of steps. Any password that was assigned to the ID before you assign multiple passwords is no longer valid. 1. From the Domino Administrator, click Configuration, and then click Certification. 2. Choose Edit Multiple Passwords. 3. Select the ID to which you want to assign multiple passwords, and then click Open. 4. Enter the password for the ID (if required). 5. Each administrator in turn completes these steps: a. In the “Authorized User” field, enter your user name. b. In the “New Password” field, enter a password. c. In the “Confirm Password” field, retype the password. d. Click Add to add your name and password to the ID file. 6. Enter the number of passwords required to access the ID. Enter a number that is less than or equal to the number of administrators who assigned passwords to the ID. 7. Click OK. To edit a password 1. From the Domino Administrator, click the Configuration tab, and then click Certification. 2. Choose Edit Multiple Passwords. 3. Select the ID containing a password you want to modify. 4. Enter the required passwords. The administrators need to be physically present to enter all of the passwords. 5. Select a user who has a password in the file. 6. In the “New Password” field, type the new password.

Protecting and Managing Notes IDs 39-13

7. In the “Confirm password” field, retype the new password. 8. Click Modify, and then click OK. To delete a password 1. From the Domino Administrator, click the Configuration tab, and then click Certification. 2. Choose Edit Multiple Passwords. 3. Select the ID from which you want to remove an authorized password. 4. Enter the passwords required. 5. Select a currently authorized user, and then click Remove. 6. Repeat Step 5 to delete the password for each additional authorized user. 7. Click OK.

ID recovery
To recover from loss of, or damage to, an ID file, recommend to your users that they keep backup copies of their ID files in a secure place — for example, on a disk stored in a locked area. Losing or damaging an ID file or forgetting a password has serious consequences. Without an ID, users cannot access servers or read messages and other data that they encrypted with the lost ID. To prevent problems that occur when users lose or damage ID files or forget passwords, set up Domino to recover ID files. Ideally, you should designate several administrators who will act as a group to recover IDs and passwords. Although you can designate a single administrator to manage ID recovery, you should consider having two or more administrators work together to recover ID files. Designating a group of administrators helps to prevent a breach of security by one administrator who has access to all ID files. When you designate a group of administrators, you can specify that only a subset of them be present during the actual ID recovery. For example, if you designate five administrators for ID recovery but require only three administrators to unlock the ID file, any three of the five can unlock the ID file. Designating a group of administrators and requiring only a subset also prevents problems that occur if one administrator is unavailable or leaves the company.

39-14 Administering the Domino System, Volume 2

Security

Before you can recover ID files, an administrator who has access to the certifier ID file must specify recovery information, and the ID files themselves must be made recoverable. There are three ways to do this: • • • At registration, administrators create the ID file with a certifier ID that contains recovery information. Administrators export recovery information from the certifier ID file and have the user accept it. (Only for servers using the server-based certification authority) Users authenticate to their home server after an administrator has added recovery information to the certifier.

Domino stores ID recovery information in the certifier ID file. The information stored includes the names of administrators who are allowed to recover IDs, the address of the mail or mail-in database where users send an encrypted backup copy of their ID files, and the number of administrators required to unlock an ID file. The mail or mail-in database contains documents that store attachments of the encrypted backup ID files. These files are encrypted using a random key and cannot be used with Notes until they are recovered. An encrypted backup copy of the ID file is required to recover a lost or corrupted ID file. Recovering an ID file for which the password has been forgotten is a bit easier. If the original ID file contains recovery information, administrators can recover the ID file, even if an encrypted backup ID file doesn’t exist. You can set up ID recovery for user IDs at any time. If you do so before you register users, ID recovery information is automatically added to user IDs the first time that users authenticate with their home servers. If you set up ID recovery information after you have registered Notes users, recovery information is automatically added to the user IDs the next time users authenticate with their home servers. Caution If your users will be enabling Smartcards to use with their Notes IDs, it is extremely important to set up ID recovery information for these IDs before any Internet keys are pushed onto the Smartcard. Otherwise, the ID file recovery process will not be able to restore those keys. Additionally, acquiring recovery information, through any means, makes any Internet keys that had been previously pushed to the Smartcard unrecoverable.

Protecting and Managing Notes IDs 39-15

How ID recovery works
For each administrator, the user’s ID file contains a recovery password that is randomly generated and encrypted with the administrator’s public key. The password is unique for each administrator and user. For example, administrator Randi Bowker has a unique recovery password for user Alan Jones, and that password is stored in Alan’s ID file. Administrator Randi Bowker has a unique recovery password for user Susan Salani, and that password is stored in Susan’s ID file. To recover an ID, users and administrators do the following: 1. A user contacts each designated administrator to obtain the administrator’s recovery password. 2. The administrator obtains the recovery password by decrypting the recovery password stored in the user’s ID file using the administrator’s private key. 3. The administrator then gives the recovery password to the user. 4. The user repeats Steps 1 through 3 until the minimum number of administrators to unlock the ID file is reached. 5. After the file is unlocked, the user must enter a new password to secure the ID file. Tip The same ID file can be recovered again using the same recovery passwords. However, you should urge users to refresh the recovery information and create a new backup by re-accepting the recovery information after they recover their ID files. When users acquire a new public key, accept a name change, or accept or create a document encryption key, Domino automatically sends updated encrypted backup ID files to the centralized database. To help prevent unauthorized users from recovering IDs without the authorized user’s knowledge, make sure that password verification is enabled for users and servers. If password verification is enabled, the authorized user is aware of the change because the user cannot access servers using the legitimate ID. When the unauthorized user recovered the ID file, that user was forced to make a password change. For more information about password verification, see the topic “Verifying user passwords during authentication” in this chapter. As an extra precaution, after recovering IDs, ask users to re-accept the recovery information and then change the public key on their ID files. Re-accepting recovery information changes recovery password information in the ID file. Changing the public key changes the public and private keys stored in the ID file.
39-16 Administering the Domino System, Volume 2

Security

Setting up ID recovery
Before users can recover their ID files, you must set up a centralized mail or mail-in database to store encrypted backups of ID files and specify information about which administrators — known here as recovery authorities — are allowed to recover IDs. You must perform these steps before anyone loses or corrupts an ID — ideally before you begin registering users. 1. From the Domino Administrator, click Configuration, and then click Certification. 2. Click Edit Recovery Information. 3. In the “Choose a Certifier” dialog box, click Server and select the registration server name from the Domino Directory (only if the correct server name does not appear). 4. Choose the certifier for which you are creating recovery information. • If you are using a server-based certification authority, click “Use the CA process” and select a certifier from the drop-down list. You must be a Certificate Authority (CA) administrator for the certifier in order to change ID recovery information. • If you are not using a server-based certification authority, click “Supply certifier ID and password.” If the certifier ID path and file name does not appear, click Certifier ID and select the certifier ID file and enter the password. 5. Click OK. The “Edit Master Recovery Authority List” dialog box appears. 6. Enter the number of recovery authorities that are required to recover an ID file. It is recommended that you choose at least three. 7. Click Add and select the names of the administrators who are the designated recovery authorities. 8. Choose whether you want to use an existing mailbox for recovery information or create a new one. • If you have a mail or mail-in database already set up for recovery information, click “I want to use an existing mailbox.” Click Address and select the database from the Domino Directory. • If you want to create a new database to store recovery information, click “I want to create a new mailbox.” In the “Create New Mailbox” dialog box, enter the name of the server on which the database is to be created, and the database title. You can use the file name that is created from the database title, or you can create a new one.

Protecting and Managing Notes IDs 39-17

Note Whenever you make changes in this dialog box, the Export button is disabled. You cannot export recovery information until you save the new or updated information. 9. Click OK. 10. If you are using a server-based certification authority, at the server console type:
load ca

This starts the CA process with the new recovery information, or refreshes it if it is already running. Then type:
tell adminp process all

to process the request to add recovery information to the certifier. 11. In the mail-in database ACL, set the -Default- access to No access and give administrators Reader access. Note If you have created additional O-level Notes certifiers, be sure to cross-certify them with the initial Notes certifier prior to setting up recovery information.

Preparing IDs for recovery
After you specify recovery information in the certifier ID, when you register users, the user IDs automatically contain recovery information. However, if you specified recovery information after generating user IDs, users must update their user IDs with recovery information supplied by the administrator. Updating IDs with recovery information automatically sends an encrypted backup of the user ID to the centralized mail or mail-in database. There are two ways that users can update their user IDs with recovery information: • (Only for servers using the server-based certification authority) Users authenticate to their home server after an administrator has added recovery information to the certifier. The recovery information is automatically added to their Notes ID. The administrator sends recovery information to users to incorporate into their user IDs. You must complete these steps before a user loses or damages an ID or forgets a password.

To send recovery information to the user The administrator completes these steps. 1. From the Domino Administrator, click the Configuration tab, and then click Certification. 2. Click Edit Recovery Information.
39-18 Administering the Domino System, Volume 2

Security

3. In the Choose a Certifier dialog box, if the correct server name does not appear, click Server and select the registration server name from the Domino Directory. 4. Choose the certifier for which you are creating recovery information. • If you are using a server-based certification authority, click “Use the CA process” and select a certifier from the drop-down list. • If you are not using a server-based certification authority, click “Supply certifier ID and password.” If the certifier ID path and file name do not appear, click Certifier ID and select the certifier ID file and enter the password. 5. Choose Export, and then enter the certifier ID’s password. 6. Complete these fields, and then click Send:
Field To CC Subject Enter Names of users and groups whose ID files you want to back up. Names of users and groups to whom you want to send a copy of the message. Information for users and groups that will appear in the Subject field of the message. If this field is blank, Notes uses the following text: New ID file recovery information is attached. Please add it to your ID file by using the Actions menu “Accept Recovery Information” option. Information for users and groups that will appear in the Body field of the message. Domino automatically attaches the encrypted backup file information to the message — you do not need to specify it in this field.

Memo

To accept recovery information in the ID file The user completes these steps. 1. After the administrator sends the recovery information, open the message in your mail database. 2. Choose Actions - Accept Recovery Information, and then enter your password.

Protecting and Managing Notes IDs 39-19

3. Complete these fields, and then click Send.
Field To Enter Name of the mail or mail-in database that will store the backup copy of your ID. Domino enters the name of the database specified by your administrator. Names of users and groups to whom you want to send a copy of the message. Information for administrators that will appear in the Subject field of the message. If this field is blank, Notes uses one of the following messages: • • Memo Backup of newly changed recovery information for user name Backup of recent changes to ID file for user name

CC Subject

Information for administrators that will appear in the Body field of the message. Domino automatically attaches the backup of the ID file to the message; you do not need to specify it in this field.

Domino automatically sends the encrypted backup ID file to the centralized mail or mail-in database specified by the administrator. Note You can store multiple copies of the ID file in the centralized mail or mail-in database. Domino creates a new document every time an ID file is backed up. When attempting to recover an ID file, use the most recent backup. If this fails, use the older versions.

Recovering an ID
If a user loses or damages an ID file or forgets a password, the user can work with administrators to recover the ID file from backup. To recover a user ID from a backup ID The user completes these steps. 1. If you have recovery information set up for your user ID, contact your administrator to obtain the password(s) needed to recover your ID. The recovery password is randomly generated and unique to each recoverable ID file and administrator. Note If you do not have access to your user ID file, contact your administrator, who can provide you with an encrypted backup of your user ID. Once you have the backup user ID, continue with the following steps. 2. When you first log in to Notes and the Password dialog box appears, do not enter your password. Just click OK. 3. Click “Recover Password” in the “Wrong password” dialog box.
39-20 Administering the Domino System, Volume 2

Security

4. Select the user ID file to recover in the “Choose ID File to Recover” dialog box. 5. Enter the password(s) given to you by your administrator(s) in the “Enter Passwords” dialog box, and repeat until you have entered all of the passwords, and you are prompted to enter a new password for your user ID. 6. Enter a new password for your user ID, and confirm the password when prompted. Note that if you do not enter a new password, you will need to recover your user ID again.

7. Replace all backups and copies of your user ID file with the newly recovered user ID file. To obtain the ID file recovery password For security reasons, the administrators must complete these steps from their own workstations, rather than from the same workstation. Using separate workstations prevents an unauthorized user from using a program to capture the keystrokes that the administrators enter on the same workstation. If an unauthorized user obtains an administrator’s ID file and password, the unauthorized user can obtain the administrator’s recovery password for all ID files. Therefore, you must protect the administrator’s ID file and require that multiple administrators work together to recover any given user ID file. 1. Detach the encrypted backup of the user’s ID file from the mail or mail-in database to the local hard drive. 2. If the user’s ID file is damaged, send a copy of the ID file from the centralized mail or mail-in database to the user. 3. From the Domino Administrator, click the Configuration tab, and choose Certification - Extract Recovery Password. 4. Enter the password to the administrator’s ID file. 5. Specify the ID file you want to recover. This is the same ID you detached in Step 1. 6. Give the user the recovery password that is displayed.

Changing administrator information for ID recovery
If an administrator leaves an organization or changes job responsibilities within an organization, you need to update the administration recovery information used to recover user ID files and then send the new information to users to add to their ID files.

Protecting and Managing Notes IDs 39-21

To add or delete administrators An administrator with access to the certifier ID completes these steps. 1. From the Domino Administrator, click the Configuration tab, and then click Certification. 2. Click Edit Recovery Information. 3. In the Choose a Certifier dialog box, if the correct server name does not appear, click Server and select the registration server name from the Domino Directory. 4. Choose the certifier for which you are creating recovery information. • If you are using a server-based CA, click “Use the CA process” and select a certifier from the drop-down list. • If you are not using a server-based CA, click “Supply certifier ID and password.” If the certifier ID path and file name does not appear, click Certifier ID and select the certifier ID file and enter the password. 5. Do one: • To delete an administrator, highlight the administrator’s name, and then click Remove. • To add new administrators, click Add and then select the names of administrators who are authorized to recover ID files. 6. (Optional) Change the number of administrators required to unlock an ID. 7. When you finish adding or deleting names, click OK. 8. Prepare IDs for recovery.

Public key security
Every Notes user ID and Domino server ID has a unique public key for the Notes certificate. The public key is stored in an ID file and in the Person or Server document for that ID in the Domino Directory. Notes and Domino use the public key to authenticate users and servers, verify digital signatures, and encrypt messages and databases. A Notes user ID can also have a unique public key for an Internet certificate. For information on encrypting and electronically signing mail messages, see the chapter “Encryption and Electronic Signatures.” For information on Internet certificates, see the chapter “Setting Up Clients for S/MIME and SSL.”
39-22 Administering the Domino System, Volume 2

Security

Issuing new public keys for a Notes certificate
If you suspect that an ID has been compromised because it was lost, stolen, or copied without permission, you can create a new public key for the ID. Creating a new public key allows you to maintain other parts of the ID — for example, the encryption keys — rather than create an entirely new ID. Notes users can create a new public key for the Notes certificate. The new public key must be certified before it can be used by Notes. After certifying a new public key, you should set up servers to verify public keys. Public key verification involves matching the public key stored in the Domino Directory with the public key on the ID. Verifying public keys prevents an unauthorized user from using the ID with the original public key to access the server. For information on verifying public keys, see the topic “Creating a new Notes public key and adding it to the Domino Directory” later in this chapter.

Adding an existing Notes public key
When you register a user or server, Domino automatically adds the Notes public keys to the corresponding Person or Server document. However, you may need to manually add a user or server ID’s public key in these situations: • A user wants to send encrypted mail to a Notes user in another domain. To send Notes encrypted mail, Domino must be able to access the recipient’s Notes public key in the Personal Address Book, Domino Directory, or LDAP directory. If the recipient is in another domain and the Domino Directory or LDAP directory for that domain is not accessible by directory assistance, then Domino can’t access the recipient’s public key for encryption. The sender must obtain the recipient’s public key and add it to the Personal Address Book or a Domino Directory that is set up with directory assistance. An administrator might also want to set up directory assistance for the Domino Directory or LDAP directory so users can encrypt messages to all users in the directories. For information on setting up directory assistance, see the chapter “Setting Up Directory Assistance.” • A user or server ID’s public key in the Domino Directory becomes corrupted or is accidentally deleted, and the administrator needs to replace it. For more information, see the topic “Adding a Notes public key to the Domino Directory” later in this chapter.
Protecting and Managing Notes IDs 39-23

Creating a new Notes public key and adding it to the Domino Directory
Creating and certifying a new public key requires the following procedures, which are described below: • • • The user creates the new public key and submits it for certification. The certification administrator certifies the user’s public key with a Notes certificate and adds it to the Domino Directory. The user merges the new certificate into the user’s ID file.

To create a new Notes public key The ID owner performs these steps. 1. Choose File - Security - User Security. 2. Type the password (if required). 3. Click Your Identity - Your Certificates, and click Other Actions. Choose “Create New Public Keys.” 4. In the New Public Keys Confirmation dialog box, click Continue to use Notes mail to send your request for adopting new public keys. Note If you want to create a new public key without using Notes mail, click Export ID to create a safe copy of your ID file, and then click “Do not continue.” Use another e-mail program to send the exported file to the administrator. 5. In the Mail New Public Key Request dialog box, address the request to one of the following: • The certification administrator for the certifier. • The certifier — for example /East/Acme. Domino mails the request to the person indicated in the Administration section of the corresponding Certifier document in the Certificates view of the Domino Directory. 6. Click Send. To recertify the ID with a Notes certificate and add the Notes public key to the Domino Directory The certification administrator performs these steps. 1. Open the certification request in your mail file. 2. Choose Actions - Certify Attached ID File. 3. Select whether to use a server-based certification authority or the certifier ID, and click OK. 4. If you chose to use the certifier ID, enter the password for the ID, and click OK.
39-24 Administering the Domino System, Volume 2

Security

5. (Optional) Change the expiration date for the certificate. 6. (Optional) Click Add to specify alternate user name information. 7. (Optional) Specify a minimum password length. 8. Click Certify. The ID owner’s name appears in the To field and explanatory text appears in the Subject field of the Mail Certified ID dialog box. 9. Click Send. To merge the new Notes certificate with the ID The ID owner performs these steps. 1. Choose File - Security - User Security. 2. Click Your Identity - Your Certificates. 3. Click Get Certificates, and then click Import (Merge) Notes Certificates. 4. Select the recertified ID sent to you by the certification administrator, and then click OK. To verify a Notes public key Verifying Notes public keys against those in the Domino Directory helps prevent an unauthorized user or server from accessing another server. 1. From the Domino Administrator, click Configuration and open the Server document for the server. 2. Click Security. 3. In the Security Settings section, select Yes in the “Compare Notes public keys against those stored in Directory” field. 4. Save the document. 5. Restart the server so that the changes take effect.

Adding a Notes public key to the Domino Directory
You can copy a Notes public key to a file or mail it to a user or administrator who pastes the public key into a Personal Address Book or a Domino Directory that users can access. This lets users encrypt mail sent to a user in another organization or replace a missing or corrupted key in the Domino Directory. To mail a public key 1. Choose File - Security - User Security. 2. Select the ID and enter the password. 3. Click Your Identity - Your Certificates - Other Actions. Choose “Mail, Copy Certificate (Public Key).”
Protecting and Managing Notes IDs 39-25

4. In the Mail, Copy Certificate (Public Key) dialog box, click Mail Certificate. 5. Address the request to the person who will paste the key into a Domino Directory or Personal Address Book. 6. (Optional) Next to CC, type the name of any other people you want to notify of the request. 7. (Optional) Click Sign to prove you are the sender of the ID. 8. (Optional) Click Encrypt to protect the message as it is being sent to the recipient. 9. Click Send. To copy a public key to a file 1. Choose File - Security - User Security. 2. Select the ID and enter the password. 3. Click Your Identity - Your Certificates - Other Actions. Choose “Publish (Mail, Copy) Certificate.” 4. In the Publish (Mail, Copy) Certificate dialog box, click Copy Certificate and click OK to copy the key to the clipboard. 5. Save the contents of the clipboard to a file. 6. Deliver the file by hand or postal service to someone to paste into a Domino Directory or Personal Address Book. To paste the public key into a Personal Address Book 1. In your Personal Address Book, create a Contact document for the owner of the public key. 2. Click the Advanced tab, and then use the clipboard viewer to open the file or mail message that contains the public key. 3. Copy the public key from the clipboard and paste it into the “Certified public key” field of the Contact document. 4. Save the document. To paste the public key into a Domino Directory 1. From the Domino Administrator, do one of the following: a. Click the People & Groups tab and edit the Person document. b. Click the Configuration tab and edit the Server document. 2. Click Certificates - Flat Name Key in the Person document, or click Administration in the Server document. 3. Use the clipboard viewer to open the file or mail message that contains the public key.

39-26 Administering the Domino System, Volume 2

Security

4. Copy the public key from the clipboard, and paste it into one of the following fields: • Certified public key field (hierarchical Domino certificates) • (Person documents only) Flat name key (non-hierarchical Domino certificates) Note You cannot paste Internet certificates into Person or Server documents. 5. Save the Person or Server document.

Using cross-certificates to access servers and send secure S/MIME messages
Domino uses two types of cross-certificates: Notes and Internet. Notes cross-certificates allow users in different hierarchically-certified organizations to access servers and to receive signed mail messages. Internet cross-certificates allow users to receive signed mail messages and send encrypted mail messages.

Notes cross-certificates
To allow users and servers from the different hierarchically-certified organizations to access servers in the other organization, and to verify the digital signature of a user from another organization, you use cross-certificates. Domino servers store cross-certificates in the Domino Directory. To access Domino servers, Notes clients obtain cross-certificates for those servers and store them in their Personal Address Books. These cross-certificates can be used only by the user to whom they are issued. For example, if Alan Jones/Sales/East/Acme wants to access the Support/Seascape server, he needs a cross-certificate from /Seascape, and the Support/Seascape server needs a cross-certificate for /Sales/East/Acme. When Alan tries to authenticate with the Support/Seascape server, it checks for the cross-certificate in Alan’s Personal Address Book. If Support/Seascape finds a valid cross-certificate, the server then checks whether Alan is allowed to access the server. Cross-certification can occur at various levels of an organization. For example, to allow every user within one organization to authenticate with every server in another, each user has a cross-certificate for the other’s organization certifier in the Personal Address Book. Servers in each organization have a cross-certificate for the other’s organization certifier in the Domino Directory. Cross-certification can also occur at the
Protecting and Managing Notes IDs 39-27

level of an individual user or server ID. For example, to allow a single user to authenticate with any server in another organizational unit or verify a digital signature from a user in that organizational unit, the user ID needs a cross-certificate for the organizational unit certifier in the other company, and that organizational unit certifier needs a cross-certificate for the user ID. Two-way cross-certification does not need to be symmetric. For example, one organization can have a cross-certificate for an organizational unit certifier and another organization can have a cross-certificate for an organization certifier. If you have cross-certificates for an organization or organizational unit certifier, set up server access restrictions to prevent the other organization from accessing specific servers that store confidential information. To allow your organization to access servers in another organization but prevent that organization from accessing your servers, exchange cross-certificates as required, but then set up server access lists on all servers to prevent access by the other organization.

Internet cross-certificates
An Internet cross-certificate is a certificate that validates the identity of a user or server. An Internet cross-certificate ensures the recipient of an encrypted S/MIME message that the sender’s certificate can be trusted and that the certificate used to sign an S/MIME message is valid. It also validates the identity of a server when a Notes client uses SSL to access an Internet server. An Internet cross-certificate is stored in a Certificate document in the user’s Personal Address Book and can be used only by the user to whom it is issued. An Internet cross-certificate can be issued for a leaf certificate — that is, a certificate issued to a user or server by a CA — or the CA itself. Creating a cross-certificate for a leaf certificate indicates trust for only the owner of the certificate — for example, the sender of the signed message or recipient of an encrypted message. A cross-certificate for a CA indicates trust for all owners who have a certificate issued by that CA. If you cross-certify a CA, you trust the CA to issue certificates to users and servers lower in the hierarchical name tree. For example, after cross-certifying Sales/ABC, you trust Sales/ABC to issue a certificate to Fred/Sales/ABC. Alternatively, after creating a cross-certificate for Fred/Sales/ABC, you trust only Fred/Sales/ABC.

39-28 Administering the Domino System, Volume 2

Security

Adding cross-certificates to the Domino Directory or Personal Address Book
You can use several methods to obtain a Notes or Internet cross-certificate. See the topic “Examples of cross-certification” later in this chapter.

Accessing a server
If a user attempts to access a server in a foreign domain, and the user does not already have a certificate in common with the domain, a dialog box gives the recipient the option to add the cross-certificate “on demand.” Users can add a Notes cross-certificate this way. This is usually the quickest and easiest way for a user to obtain a cross-certificate. For more information, see the topic “Adding a Domino or Internet cross-certificate on demand” in this chapter.

Receiving a signed mail message
If a user receives a signed mail message from a user in a foreign domain and the recipient does not already have a certificate in common with the domain, the “on demand” cross-certificate dialog box appears. Users can add both Notes and Internet cross-certificates this way. For more information, see the topic “Adding a Domino or Internet cross-certificate on demand” in this chapter.

Adding a cross-certificate from the Domino Directory
Users can retrieve Internet certificates and Notes and Internet cross-certificates from the Domino Directory on their home/mail server, and add them to their Personal Address Books. Domino administrators can use any method to add the Internet certificates and Notes and Internet cross-certificates to the Domino Directory; however, the cross-certificates must be issued by a common ancestor before Notes copies the cross-certificates to the user’s Personal Address Book.

By Notes mail or postal service
Users can add a cross-certificate by sending a safe copy of the certificate through Notes mail or the postal service. Users can use this method to add a Notes cross-certificate only. For more information, see the topics “Adding a Notes cross-certificate for IDs by Notes mail” and “Adding a Notes cross-certificate for IDs by postal service” in this chapter.
Protecting and Managing Notes IDs 39-29

From an Internet server
Users can obtain an Internet cross-certificate through the User Security panel (File - Security - User Security). Users would choose Identity of Others - People, Services, and click “Retrieve Internet Service Certificate.” A dialog box allows the user to specify an Internet server from which to obtain a certificate to cross-certify. This method can be the quickest way to obtain an Internet cross-certificate. For more information on obtaining Internet cross-certificates for a Notes client, see Lotus Notes 6 Help.

By phone
Users can add a cross-certificate by providing the name and public key of the certificate by phone. Users can use this method to add a Notes certificate only. For more information, see the topic “Adding a Notes cross-certificate by phone” later in this chapter.

In the Person document
Users can cross-certify a certificate stored in a Person document in the Domino Directory using Actions - Create Cross Certificate. Users can add both Internet and Notes cross-certificates this way. For more information, see the topic “Creating a cross-certificate from a user’s Person document” later in this chapter. From a trusted root certificate Users can create an Internet cross-certificate from a trusted root certificate if you have a trusted root certificate in the Personal Address Book or Domino Directory. Notes and Domino provide in the Personal Address Book and Domino Directory many default trusted root certificates for third-party CAs. To indicate trust for these CAs, create a cross-certificate using the trusted root. You can also add a trusted root certificate for other CAs that are not included by default and create cross-certificates for them. For more information, see the chapter “Setting Up Clients for S/MIME and SSL.”

39-30 Administering the Domino System, Volume 2

Security

Examples of cross-certification
To authenticate with all servers in another organization This example describes what the Acme company and the ABC company do to allow all users and servers in both organizations to authenticate. 1. The Acme organization certifier (/Acme) obtains a cross-certificate for the ABC organization certifier (/ABC) and stores it in Acme’s Domino Directory. 2. The ABC organization certifier (/ABC) obtains a cross-certificate for the Acme organization certifier (/Acme) and stores it in ABC’s Domino Directory. To authenticate with a specific server in another organization The Acme company wants to let Seascape users who have the hierarchical certification AppDevelopment/Seascape to access their customer support server, CSSUPPORT/East/Acme. 1. The Acme organizational unit certifier (/East/Acme) has a cross-certificate for the Seascape organizational unit certifier (/AppDevelopment/Seascape) and stores it in Acme’s Domino Directory. 2. The Seascape organizational unit certifier (/AppDevelopment/Seascape) has a cross-certificate for the Acme organizational unit certifier (/East/Acme) and stores it in Seascape’s Domino Directory. This cross-certification enables Kelly Jones/AppDevelopment/Seascape and Jonathan Moutal/AppDevelopment/Seascape to authenticate with the server CSSUPPORT/East/Acme. However, it does not allow these users to authenticate with the Acme server Mail-W/West/Acme. To send signed S/MIME messages Alan Jones has an Internet certificate issued from the Acme CA, and Dave Lawson has an Internet certificate issued from the ABC CA. If Alan wants to send Dave an encrypted S/MIME message and Dave wants to send Alan an encrypted S/MIME message: 1. Alan has a trusted cross-certificate for ABC and stores it in his Personal Address Book. 2. Dave has a trusted cross-certificate for Acme and stores it in his Personal Address Book. Both Dave and Alan can now also send encrypted S/MIME messages to each other.

Protecting and Managing Notes IDs 39-31

Adding a Notes or Internet cross-certificate on demand
When users access a server or receive a signed message, they can accept a Notes or Internet cross-certificate from another organization. Domino adds the cross-certificate to the user’s Personal Address Book. Then the next time the user tries to access the server, the user can authenticate the server with that cross certificate. Similarly, the user can use the cross certificate to verify signed messages from the organization that was cross certified. Note You cannot add an Internet cross-certificate on demand if a users’ Internet certificate already exists in an LDAP directory. To add a cross-certificate on demand 1. Using a Notes workstation, attempt to access a server in an organization with which you are not cross-certified or open a signed message whose signature you do not trust. 2. If you attempted to access a server, when Domino displays this message, select Advanced Options: Your local Domino Directory does not contain a cross-certificate for this organization. Would you like to suppress this warning in the future by creating a cross-certificate for this organization in your Name and Address Book? 3. To avoid the possibility of cross-certifying an impostor, call someone trustworthy from the named organization and ask the person to tell you the organization’s public key. Compare it to the key displayed in the Advanced Options dialog box. 4. Complete these fields:
Field Certifier Enter File name of a user, server, or certifier ID. Specify a server or certifier ID when creating a cross-certificate for a server. The ID specified indicates who can use the cross-certificate. Location of the Personal Address Book or Domino Directory where you want to copy the cross-certificate. Add the cross-certificate to the Personal Address Book for Notes clients. Organization or organizational unit certifier that you want to cross-certify — for example, /Acme. You can also create a cross-certificate for the owner of the certificate. An alternate name that identifies the subject. Alternate names allow you to assign more than one name to an ID, which is recognizable in a user’s native language.

Server

Subject name Subject alternate name list

Expiration Date when the cross-certificate will expire. date 39-32 Administering the Domino System, Volume 2

Security

5. Click Cross Certify. Domino places the cross-certificate in the Server Certificates view of the Domino Directory of the server you specified in Step 4 or in the Advanced/Certificates view of the Personal Address Book.

Adding a Notes cross-certificate by phone
Two organizations can add a Notes cross-certificate to user, server, and certifier IDs by providing the name and public key of the IDs to be cross-certified over the phone. For cross-certification to work, these steps must be carried out twice, with each organization alternately requesting cross-certification. You cannot use this procedure to create an Internet cross-certificate. To request a cross-certificate for a user, server, or certifier ID Use these steps to add a cross-certificate for a user or server or for an organization or organizational unit when you have access to the user, server, or certifier ID. 1. From the Domino Administrator, click the Configuration tab. 2. Click Certification - ID Properties. 3. Select the user, server, or certifier ID file, and click Open. 4. Type the password (if required). 5. Click Security Basics. Write down the name exactly as it appears in the Name field, including any forward slashes (/) — for example, Alan Jones/Sales/East/Acme, Mail-E/East/Acme, or /Acme. 6. Click Your Identity - Your Certificates. Write down the Key Identifier information exactly as it appears, including spaces. 7. Call the organization that will add the cross-certificate, and provide the name and key exactly as you recorded them. To request a cross-certificate for an ancestral certifier of an ID Use these steps to add a cross-certificate for an organization or organizational unit when you have access to the user or server ID. 1. From the Domino Administrator, click the Configuration tab. 2. Click Certification - ID Properties. 3. Select the user, server, or certifier ID file, and click Open. 4. Type the password (if required). 5. Click Your Identity - Your Certificates and in the Certificates list, select the certificate for the certifier you want to cross-certify. Click Advanced Details.

Protecting and Managing Notes IDs 39-33

6. Look at the “Certificate Issued To” field to verify that you selected the correct certificate. Write down the name exactly as it appears, including any forward slashes (/) — for example, /Acme. 7. Look at the “Issuer Key Identifier” field and write down the public key exactly as it appears, including spaces. 8. Call the organization that will add the cross-certificate, and provide the name and public key exactly as you recorded them. To add a cross-certificate to a Domino Directory or Personal Address Book After someone from another organization provides the name and public key over the phone, use these steps to add a cross-certificate for the ID. 1. From the Domino Administrator, click the Configuration tab. 2. Choose Certification, and then choose Cross Certify Key. 3. Select whether to use a CA-enabled certifier or use the Certifier ID, and click OK. 4. If you chose to use the certifier ID, enter the password for the ID, and click OK. 5. In the “Subject name” field, type the full hierarchical name for the ID you are cross-certifying exactly as provided over the phone, including any forward slashes (/). 6. Type the public key for the ID you are cross-certifying exactly as it was provided over the phone, including spaces. 7. (Optional) Change the expiration date for the certificate. The default is 10 years. 8. (Optional) Click Certifier to select a different certifier to issue the cross-certificate. 9. (Optional) Click Server and select a different registration server whose Domino Directory will store the cross-certificate. To store the cross-certificate in a user’s Personal Address Book, choose Local as the server. Then click OK. 10. Click Cross Certify. Domino places the cross-certificate in the Server Certificates view of the Domino Directory of the selected registration server.

Adding a Notes cross-certificate for IDs by postal service
Organizations that cannot communicate through Notes mail can use these steps to add a Notes cross-certificate for user, server, and certifier IDs. For cross-certification to work, these steps must be carried out twice, with each organization alternately requesting cross-certification.
39-34 Administering the Domino System, Volume 2

Security

You cannot use this procedure to create an Internet cross-certificate. To create a safe copy of an ID Use these steps to create a safe copy of the user, server, or certifier ID that you want to cross-certify. 1. From the Domino Administrator, click the Configuration tab. 2. Choose Certification and then choose ID Properties. 3. Select the user, server, or certifier ID file, and then click Open. 4. Type the password (if required). The ID Properties dialog box appears. 5. Click Your Identity - Your Certificates - Other Actions, and then select Export Notes ID (Safe Copy). 6. Enter a path and name for the safe copy, and then click OK. The default name is SAFE.ID. 7. Copy the file to a disk. 8. Use the postal service to send the disk to the certification administrator at the other organization. To add a cross-certificate for the safe copy Use these steps to add the cross-certificate to the Domino Directory. 1. From the Domino Administrator, click the Configuration tab. 2. Click Certification, and then click Cross Certify. 3. Select whether to use a CA-enabled certifier or use the certifier ID, and click OK. 4. If you chose to use the certifier ID, enter the password for the ID, and click OK. 5. Select the safe copy of the ID to be cross-certified, and then click OK. 6. Complete one or more of these fields:
Field Certifier Server Subject name Enter Name of your organization’s certifier ID Location of the Domino Directory where you want to copy the cross-certificate Organization or organizational unit certifier to be cross-certified — for example, /Acme

Subject alternate An alternate name that identifies the certifier ID. Alternate name list names allow you to assign more than one name to an ID, which is recognizable in a user’s native language. Expiration date Date when the cross-certificate will expire Protecting and Managing Notes IDs 39-35

7. Click Cross Certify. Domino places the cross-certificate in the Server Certificates view of the Domino Directory of the server you specified in Step 6.

Adding a Notes cross-certificate for IDs by Notes mail
If you can route mail to the organization that will cross-certify a user, server, or certifier ID, you can use Notes mail to add a Notes cross-certificate. For cross-certification to work, these steps must be carried out twice, with each organization alternately requesting cross-certification. You cannot use this procedure to create an Internet cross-certificate. To send an ID for cross-certification 1. Choose File - Security - User Security, select the ID, and enter the password. 2. Click Your Identity - Your Certificates, and then click Other Actions, and then select Mail, Copy Certificate (Public Key). 3. Select the user, server, or certifier ID you want to have cross-certified, and then click OK. 4. Enter the password (if required). 5. Address the cross-certification request to the certification administrator at the other organization, and then click Send. To cross-certify the ID 1. Open the cross-certification request in your mail file. 2. Choose Actions - Cross Certify Attached ID File. 3. Select the certifier that will issue the cross-certificate. If you choose a non-CA enabled certifier, enter the password for that certifier ID, and then click OK. 4. Complete one or more of these fields:
Field Subject name Enter Organization or organizational unit certifier to be cross-certified — for example, /Acme

Subject alternate An alternate name for the subject of the certificate. Alternate names allow you to assign names that are name list recognizable in a user’s native language to an ID file. Expiration date Certifier Server Date when the cross-certificate will expire File name of your organization’s certifier ID Location of the Domino Directory where you want to copy the cross-certificate

39-36 Administering the Domino System, Volume 2

Security

5. Click Cross Certify. Domino places the cross-certificate in the Server Certificates view of the Domino Directory of the server you specified in Step 5.

Creating a cross-certificate from a user’s Person document
You can create a Notes and/or Internet cross-certificate from a certificate stored in a user’s Person document. 1. Do one of the following: • From the Domino Administrator, click People & Groups, and open the Person document for the user you are cross-certifying. • From the Domino Administrator, click Configuration Certificates, and open the certifier document for which you want • In the Personal Address Book, open the Contact document for the user you are cross-certifying. 2. Choose Actions - Create Cross Certificate. 3. Choose the certificate to cross-certify. 4. Complete these fields and then click Cross Certify:
Field Certifier Enter File name of a user, server, or certifier ID. Specify a server or certifier ID when creating a cross-certificate for a server. The ID specified indicates who can use the cross-certificate. Location of the Personal Address Book or Domino Directory where you want to copy the cross-certificate. Add the cross-certificate to the Personal Address Book for Notes clients. Organization or organizational unit certifier that you want to cross-certify — for example, /Acme. You can also create a cross-certificate for the owner of the certificate. An alternate name for the subject of the certificate. Alternate names allow you to assign names that are recognizable in a user’s native language to an ID file. Date when the cross-certificate will expire.

Server

Subject name

Subject alternate name list Expiration date

5. Repeat Steps 3 and 4 for every user for whom you want to create cross-certificates.

Protecting and Managing Notes IDs 39-37

Creating a cross-certificate from a certifier document
You can create a Notes and/or Internet cross-certificate from a certificate stored in the Domino Directory. 1. From the Domino Administrator, click Configuration - Certificates, and open the certifier document for which you want to create a cross certificate. 2. Choose Actions - Create Cross Certificate. 3. In the Issue Cross Certificate dialog box, complete these fields and then click Cross Certify:
Field Certifier Enter File name of a user, server, or certifier ID. Specify a server or certifier ID when creating a cross-certificate for a server. The ID specified indicates who can use the cross-certificate. Location of the Personal Address Book or Domino Directory where you want to copy the cross-certificate. Add the cross-certificate to the Personal Address Book for Notes clients. Organization or organizational unit certifier that you want to cross-certify — for example, /Acme. You can also create a cross-certificate for the owner of the certificate.

Server

Subject name

Subject alternate An alternate name for the subject of the certificate. name list Alternate names allow you to assign names that are recognizable in a user’s native language to an ID file. Expiration date Date when the cross-certificate will expire.

4. Repeat Steps 2 and 3 for every certifier for which you want to create cross-certificates.

Displaying cross-certificates
To view cross-certificates, from the Domino Administrator, click the Configuration tab and choose the Certificates/Certificates view. The view lists certificates according to type: • • • • Internet certifiers Notes certifiers Notes cross-certificates Internet cross-certificates

Certificates whose type cannot be determined are listed as Unknown.

39-38 Administering the Domino System, Volume 2

Security

Chapter 40 Controlling User Access to Domino Databases
To control the access that users and servers have to a database, you can customize the database access control list (ACL) and specify other security settings.

The database access control list
Every database has an access control list (ACL) that specifies the level of access that users and servers have to that database. Although the names of access levels are the same for users and servers, those assigned to users determine the tasks that they can perform in a database, while those assigned to servers determine what information within the database the servers can replicate. Only someone with Manager access can create or modify the ACL. To control the access rights of Notes users, select the access level, user type, and access level privileges for each user or group in a database. You can set default entries in the ACL when you create the database. You may also assign roles if the database designer determines this level of access refinement is needed by the application. Work with the designer and user representatives of the application to plan the correct access level before you put a database into production. For each user name, server name, or group name in an ACL, you can specify: • • • • An access level Access level privileges A user type Roles

Caution Domino administrators with full access administration rights, as well as users who are allowed to run agents with unrestricted access, can access databases without being explicitly listed in the database ACLs. For more information on full access administration rights and running agents with unrestricted access, see the chapter “Controlling Access to Domino Servers.”
40-1

Note The database ACL should not be confused with other types of ACLs used by Domino administrators. One such ACL is the extended ACL, which is used only in the Domino Directory and the Extended Directory Catalog to restrict access to specific documents and fields within those databases. You must enable extended access to use this feature. The other type of access control list is the .ACL file, which is used by administrators to restrict user access to server directories.

Default ACL entries
A new database, by default, contains these entries in the ACL: • • • • • -DefaultAnonymous Database creator user name LocalDomainServers OtherDomainServers

Of the default ACL entries, Anonymous and the database creator’s user name are the only entries that are defined as a Person in the ACL. Anonymous and -Default- are the only entries that are specific to a database, and not related to an entry in the Domino Directory. For example, LocalDomainServers is created automatically in the Domino Directory, and added to the ACL when a database is created. Anonymous is created as an ACL entry only when the database is created.

-DefaultUsers and servers receive the access assigned to the -Default- entry if they have not specifically been assigned another access level, either individually or as a member of a group, or from a wildcard entry. In addition, if the database ACL does not contain an entry for Anonymous, then users accessing the database anonymously get the -Default- level of access. The default access for -Default- depends on the design of the database template and varies among the different templates.

40-2 Administering the Domino System, Volume 2

Security

The access level you assign to the -Default- entry depends on how secure you want the database to be. Select No Access if you want a database available to a limited number of users. Select Author or Reader access to make a database available for general use. The -Default- entry should have a user type of “Unspecified”. You cannot delete the -Default- entry from an ACL.

Anonymous
Anonymous database access is given to Internet users and to Notes users who have not authenticated with the server. The default ACL entry for Anonymous for all database templates (.NTF files) has an access level of Reader, so that users or servers can successfully read from the template when creating or refreshing .NSF files based on that template. The default ACL entry for Anonymous for database (.NSF files) files is No Access. For more information about Anonymous access, see the topic “Acceptable entries in the ACL” later in this chapter.

Database creator user name
The database creator user name is the hierarchical user name of the person who created the database. The default access for the user who creates the database is Manager. Typically, this person retains Manager access or is granted Designer access to the database.

LocalDomainServers
The LocalDomainServers group lists the servers in the same domain as the server on which the database is stored, and is provided by default with every Domino Directory. When you create a new database, the default access for LocalDomainServers is Manager. The group should have at least Designer access to allow replication of database design changes across the domain. The LocalDomainServers group is typically given higher access than the OtherDomainServers group.

OtherDomainServers
The OtherDomainServers group lists the servers outside the domain of the server on which the database is stored, and is provided by default with every Domino Directory. When you create a new database, the default access for OtherDomainServers is No Access.

Controlling User Access to Domino Databases 40-3

Acceptable entries in the ACL
Acceptable entries in the ACL include: • • • • • • Wildcard entries User, server, and group names (including user and group names of Internet clients) Alternate names LDAP users Anonymous, used for anonymous Internet user access and anonymous Notes user access Database replica IDs

Each ACL entry can have a maximum of 255 characters. Add names to the ACL in hierarchical format for better security. For example:
Sandra E Smith/West/Acme/US Randi Bowker/Sales/FactoryCo

For more information about creating hierarchical name schemes, see the chapter “Installing and Setting Up Domino Servers.”

Types of ACL entries
Wildcard entries To allow general access to a database, you can enter hierarchical names with a wildcard character (*) in the ACL. You can use wildcards in the common name and organizational unit components. Users and/or servers who do not already have a specific user or group name entry in the ACL, and whose hierarchical names include the components that contain a wildcard, are given the highest level of access specified by every one of the wildcard entries that match. Here is an ACL entry in wildcard format: */Illustration/Production/Acme/US This entry grants the chosen access level to: Mary Tsen/Illustration/Production/Acme/US Michael Bowling/Illustration/Production/Acme/US This entry does not grant the chosen access level to: Sandy Braun/Documentation/Production/Acme/US Alan Nelson/Acme/US
40-4 Administering the Domino System, Volume 2

Security

You can use a wildcard only at the leftmost portion of the ACL entry. For example, you can’t use the entry: */Illustration/*/Acme/US to represent these entries: Michael Bowling/Illustration/West/Acme/US Karen Richards/Illustration/East/Acme/US When you use a wildcard ACL entry, set the user type as Unspecified, Mixed Group, or Person Group. User names You can add to an ACL the names of any individuals with certified Notes user IDs or Internet users who authenticate using name-and-password or SSL client authentication. • For Notes users, enter the full hierarchical name for each user; for example, John Smith/Sales/Acme, regardless of whether the user is in the same hierarchical organization as the server that stores the database. For Internet users, enter the name that appears as the first entry in the User name field of the Person document. Note Many alias names can be entered in the user name field and used for authentication; however, it is the first name in the list that is used to perform the security authorization check. This is the name that should be used on all Domino database ACLs, in the security settings on the Server document, and in .ACL files. For more information about setting a maximum level of access for Internet users, see the topic “Maximum Internet name-and-password access” later in this chapter. Server names You can add server names to an ACL to control the changes a database receives from a database replica. To ensure tighter security, use the full hierarchical name of the server — for example, Server1/Sales/Acme — regardless of whether the name of the server being added is in a different hierarchical organization than that of the server that stores the database. Group names You add a group name — for example, Training — to the ACL to represent multiple users or servers that require the same access. Users must be listed in groups with a primary hierarchical name or an alternate name. Groups can also have wildcard entries as members. Before you can use a group name in an ACL, you must create the group in the Domino Directory or in either a secondary Domino Directory or an external
Controlling User Access to Domino Databases 40-5

LDAP Directory that has been configured for group authorization in the Directory Assistance database. Tip Use individual names rather than group names for the managers of a database. Then when users choose Create - Other - Memo to Database Manager, they’ll know whom they are addressing. Groups provide a convenient way to administer a database ACL. Using a group in the ACL offers the following advantages: • Instead of adding a long list of individual names to an ACL, you can add one group name. If a group is listed in more than one ACL, modify the group document in the Domino Directory or the LDAP Directory, rather than add and delete individual names in multiple databases. If you need to change the access level for several users or servers, you can do so once for the entire group. Use group names to reflect the responsibilities of group members or the organization of a department or company.

• •

Tip You can also use groups to let certain users control access to the database without giving them Manager or Designer access. For example, you can create groups in the Domino Directory for each level of database access needed, add the groups to the ACL, and allow specific users to own the groups. These users can then modify the groups, but they can’t modify the database design. Terminations group When employees leave an organization, you should remove their names from all groups in the Domino Directory and add them to a Deny List Only group used to deny access to servers. The Deny Access list in the Server document contains the names of Notes users and groups who no longer have access to Domino servers. You should also make sure that the names of terminated employees are removed from the ACLs of all databases in your organization. When you delete a person from the Domino Directory, you have the option to “Add deleted user to deny access group,” if such a group has been created. (If no such group exists, the dialog box displays “No Deny Access group selected or available.”) For more information on Deny List Only groups, see the chapter “Setting Up and Managing Groups.” For more information on the Deny Access list, see the chapter “Controlling Access to Domino Servers.”

40-6 Administering the Domino System, Volume 2

Security

Alternate names An alternate name is an optional alias name that an administrator assigns to a registered Notes user. You can add alternate names to an ACL. An alternate name provides the same level of security as the user’s primary hierarchical name. For a user whose primary name is Sandra Brown/West/Sales/Acme, an example of an alternate name format would be Sandy Smith/ANWest/ANSales/ANAcme, where AN is an alternate name. For more information about alternate names, see the chapter “Setting Up and Managing Notes Users.” LDAP users You can use a secondary LDAP directory to authenticate Internet users. You can then add the names of these Internet users to database ACLs to control user access to databases. You can also create groups in the secondary LDAP directory that include the Internet user names and then add the groups as entries in Notes database ACLs. For example, an Internet user may try to access a database on a Domino Web server. If the Web server authenticates the user, and if the ACL contains a group named “Web,” the server can look up the Internet user’s name in the group “Web” located in the foreign LDAP directory, in addition to searching for the entry in the primary Domino Directory. Note that for this scenario to work, the Directory Assistance database on the Web server must include an LDAP Directory Assistance document for the LDAP directory with the Group Expansion option enabled. You can also use this feature to look up the names of Notes users stored in foreign LDAP directory groups for database ACL checking. When you add the name of an LDAP directory user or group to a database ACL, use the LDAP format for the name, but use a forward slash (/), rather than a comma (,), as a delimiter. For example, if the name of a user in the LDAP directory is: uid=Sandra Smith,o=Acme,c=US enter the following in the database ACL: uid=Sandra Smith/o=Acme/c=US To enter the name of a nonhierarchical LDAP directory group in an ACL, enter only the attribute value, not the attribute name. For example, if the nonhierarchical name of the LDAP group is: cn=managers in the ACL enter only: managers
Controlling User Access to Domino Databases 40-7

To enter the name of a hierarchical group name, include LDAP attribute names in ACL entries. For example, if the hierarchical name of the group is: cn=managers,o=acme in the ACL enter: cn=managers/o=acme Note that if the attribute names you specify exactly correspond to those used in Notes — cn, ou, o, c — the ACL won’t display the attributes. For example, if you enter this name in an ACL: cn=Sandra Smith/ou=West/o=Acme/c=US because the attributes exactly correspond to those used by Notes, the name appears in the ACL as: Sandra Smith/West/Acme/US Acceptable ACL entries for LDAP users
LDAP DN ACL entry cn=Scott Davidson+ id=1234, ou= cn=Scott Davidson+id=1234/ou=Sales/o= Sales,o=Acme Acme cn=Scott Davidson,o=Acme\, Inc cn=Scott Davidson/o=Acme, Inc Note If the LDAP name includes a backslash followed by another character, omit that backslash when you specify the name in the database ACL. uid=smd12345,dc=Acme,dc=Com uid=smd12345/dc=Acme/dc=Com uid=Sandra Smith,o=Acme,c=US uid=Sandra Smith/o=Acme/c=US

Anonymous Any user or server that accesses a server without first authenticating is known by the name “Anonymous” at that server. Anonymous database access is given to Internet users and to Notes users who have not authenticated with the server. Anonymous access is generally used in databases that reside on servers available to the general public. You can control the level of database access granted to an anonymous user or server by entering the name Anonymous in the access control list, and assigning an appropriate level of access. Typically you assign Anonymous users Reader access to a database.

40-8 Administering the Domino System, Volume 2

Security

The table below describes the different conditions for access that an anonymous user would have to a database:
Anonymous access enabled for Internet protocol Anonymous access enabled in database ACL Users access the database with the Anonymous entry’s access level. For example, if Anonymous access is set to Reader, anonymous users who access the database will be granted Reader access. Anonymous access not enabled for Internet protocol

Users are prompted to authenticate when they attempt to access any resource on the server. If the user is not listed in the database (through a group entry, a wildcard entry, or if the user name is Anonymous If Anonymous has been granted explicitly listed), then the “No Access” (and the Read & given “no user accesses the database Write public documents access” in with the -Default- entry’s privileges are not enabled) database access level. Anonymous users are not ACL allowed access to the database and they will be prompted to authenticate. When they authenticate, the name is checked in the database ACL to determine the level of database access that should be granted. Anonymous not listed in database ACL Anonymous users access the database with the -Defaultentry’s access level. For example, if -Default- access is set to Reader, and there is no Anonymous entry in the ACL, anonymous users who access the database will be granted Reader access.

Anonymous users (both those who are given access to a database through the Anonymous entry and those who have access through the -Default- entry) who attempt to do something in the database that is not allowed for their access level will be prompted to authenticate. For example, if Anonymous is set to Reader, and an anonymous user tries to create a new document, that user is prompted to authenticate with a name and password. Tip If you want all users to authenticate with a database, then make sure that Anonymous is in the database ACL with an access level of No Access, and be sure that the Read Public Documents and Write Public Documents are not enabled. Add the Internet user’s name to the ACL with the level of access you want them to have.
Controlling User Access to Domino Databases 40-9

The Domino server uses the group name Anonymous solely for access control checks. For example, if Anonymous has Author access in the database ACL, the true name of the user appears in the Authors field of those documents. The Domino server can display only the true name of anonymous Notes users, but not of anonymous Internet users, in the Authors field of the document. Authors fields are never a security feature, regardless if anonymous access is used; if the validity of the author’s name is needed for security, then the document should be signed. Replica IDs To allow an agent in one database to use @DbColumn or @DbLookup to retrieve data from another database, enter the replica ID of the database containing the agent in the ACL of the database containing the data to be retrieved. The database containing the agent must have at least Reader access to the database containing the data to be retrieved. Both databases must be on the same server. An example of a replica ID in a database ACL is 85255B42:005A8fA4. You can enter the replica ID in uppercase or lowercase letters, but do not enclose it in quotation marks. If you do not add the replica ID to the access control list, the other database can still retrieve data if the -Default- access level of your database is Reader or higher. Order of evaluation for ACL entries ACL entries are evaluated in a specific order to determine the access level that will be granted to an authenticated user trying to access the database. If a user fails to authenticate with a server, and the server permits access anyway, access will be computed as though the user’s name was “Anonymous.” • The ACL first checks the user name to see if it matches an explicit entry in the ACL. The ACL checks all matching user names. For example, Sandra E Smith/West/Acme would match the entries Sandra E Smith/West/Acme/US and Sandra E Smith. In the event that two different entries for an individual have different access levels (for example, applied at different times by different administrators), the user trying to access the database would be granted the highest access level, as well as the union of the access privileges of the two entries for that user in the ACL. This can also happen if the user has alternate names. Note If you enter only the common name in the ACL (for example, Sandra E Smith), then that entry matches only if the user’s name and the database server are in the same domain hierarchy. For example,

40-10 Administering the Domino System, Volume 2

Security

if the user is Sandra E Smith, whose hierarchical name is Sandra E Smith/West/Acme, and the database server is Manufacturing/FactoryCo, then the entry Sandra E Smith will not get the correct level of access for ACLs on the server Manufacturing/FactoryCo. The name must be entered in full hierarchical format in order for the user to obtain the correct level of access to ACLs on servers in other domains. • If no match is made on the user name, the ACL then checks to see if there is a group name entry that can be matched. If an individual trying to access the database happens to match more than one group entry — for example, if the person is a member of Sales and there are two group entries for Sales - Acme Sales and Sales Managers — then the individual is granted the highest access level, as well as the union of the access privileges of the two entries for that group in the ACL. Note If the user matches an explicit entry in the ACL, and is a member of a group that is also listed in the ACL, then the user always gets the level of access assigned to the explicit entry, even if the group access level is higher. • If no match is made on the group name, the ACL then checks to see if there is a wildcard entry that can be matched. If the individual trying to access the database happens to match more than one wildcard entry, the individual is granted the highest access level, as well as the union of the access privileges of all of the wildcard entries that match. Lastly, if no match can be made from among the database ACL entries, the individual is granted the level of access defined for the -Default- entry.

Configuring a database ACL
Plan the database access for the application before adding users, groups or servers to a database ACL. After you add a name to the ACL, assign an access level to the name. Although assigning a user type is optional, it provides an additional level of security. Add access level privileges and roles if the application requires them. After you configure a database ACL, users can click the Effective Access button on the ACL dialog in the Notes client to view their level of access to a database. You can make changes to multiple ACLs on a server through the Multi-ACL Management dialog box in the Administration Client. For information about using the ACL dialog in the Notes client to edit an ACL for a single database, see Notes 6 Help.

Controlling User Access to Domino Databases 40-11

Configuring a database ACL
1. Make sure that you have: • Manager access in the database ACL. • Created the roles and groups that you want to use in the ACL. 2. From the Domino Administrator Server pane, select the server that stores the databases. 3. Click Files, and select one or more databases from the Domino data directory. Note You can add the same entry to more than one database. You can also edit and remove entries from multiple databases. See the topic “Editing entries in multiple ACLs” later in this chapter. 4. From the Tools pane, select Database - Manage ACL. 5. Add entries for Notes users, servers, groups, and authenticated Internet users. 6. Set the access level for each entry. 7. (Optional) For additional security, select a user type for each entry. 8. (Optional) Refine the entries by restricting or allowing additional access level priviliges. 9. (Optional) Assign roles to ACL entries. The role displays a check mark when selected. 10. (Optional) Enforce a consistent ACL across all replicas of the database. 11. (Optional) Assign an administration server to automatically update ACL entries. 12. (Optional) To prevent users whose access levels are Depositor or No Access from using the operating system to copy the database, encrypt the database with the server ID through the local Encryption option. This ensures that the database, even when copied, is illegible to anyone who doesn’t have access to the server ID. 13. Click OK to save your changes.

40-12 Administering the Domino System, Volume 2

Security

Access levels in the ACL
Access levels assigned to users in a database ACL control which tasks users can perform in the database. Access level privileges enhance or restrict the access level assigned to each name in the ACL. For each user, group, or server listed in the ACL, you select the basic access level and user type. To further refine the access, you select a series of access privileges. If the application designer created roles, assign them to the appropriate users, groups, or servers. Access levels assigned to servers in a database ACL control what information within a database the server can replicate. To access a database on a particular server, Notes users must have both the appropriate database access, as well as the appropriate server access specified in the Server document in the Domino Directory. To view a database ACL, users must have Reader access or higher. For more information on database access for Internet users, see the topic “Maximum Internet name-and-password access” later in this chapter. Caution: special ACL access There are some cases in which users can have significant access to a database that is not defined in the database ACL. This access is granted through rights set up in other areas of Domino, or by having access to the server itself. As an administrator, you need to understand these other kinds of access in order to be able to fully protect server databases. • Administrators who are designated as full access administrators in the Server document have manager access to all databases, with all privileges and roles enabled, on the server, regardless of whether they are listed in the database ACLs. Note If a user has full administrator access to a database, the database ACL indicates that by enabling the “Full Access Administrator” check box that appears in the “Effective Access” dialog box. • Administrators who are designated as administrators or database administrators in the Server document are allowed to modify (for example, designate an administration server or create a full-text index) or delete any database on the server, even if they are not listed as managers in the database ACL. Administrators who can run arbitrary executables on the server, either through non-Domino access to the server or through the use of Unrestricted Agents that launch executables.

Controlling User Access to Domino Databases 40-13

Administrators who run the Notes client directly on the server machine or on a machine that has file level access to the server database files. Users may still have access to a database by running agents with the “Unrestricted with Full Access” privilege, even if they are not listed in the database ACL. This privilege bypasses the ACL and reader lists.

This table shows the user access levels, listed from highest to lowest.
Access level Allows users to Manager Modify the database ACL. Encrypt the database. Modify replication settings. Delete the database. Perform all tasks allowed by lower access levels. Modify all database design elements. Create a full-text search index. Perform all tasks allowed by lower access levels. Create documents. Edit all documents, including those created by others. Read all documents unless there is a Readers field in the form. If an editor is not listed in the Readers field, the user with Editor ACL access cannot read or edit the document. Assign to Two people who are responsible for the database. Then if one person is absent, the other can manage the database. A database designer and/or the person responsible for future design updates. Any user allowed to create and edit documents in a database.

Designer

Editor

Author

Users who need to Create documents if the user or server contribute documents to also has the Create documents access level privilege. When you assign Author a database. access to a user or server, you must also specify the Create documents access level privilege. Edit the documents where there is an Authors field in the document and the user is specified in the Authors field. Read all documents unless there is a Readers field in the form. continued

40-14 Administering the Domino System, Volume 2

Security

Access level Allows users to Reader

Assign to

Read documents where there is a Readers Users who only need to field in the form and the user name is read documents in a specified in the field. database but not create or edit documents. Create documents, but otherwise has no access, with the exception of options to “Read public documents” and “Write public documents.” These are privileges that designers may choose to grant. Users who only need to contribute documents but who do not need to read or edit their own or other users’ documents. For example, use Depositor access for a ballot box application. Terminated users, users who do not need access to the database, or users who have access on a special basis. Note You may want to specifically assign No Access to individuals who should not have access to a database, but who may be members of a group that does.

Depositor

No Access

Has no access, with the exception of options to “Read public documents” and “Write public documents.” These are privileges that designers may choose to grant.

Viewing ACL entries by access level
You can view ACL entries by access level. This shows you at a glance what entries have been assigned a given access level.

To view ACL entries by access level
1. Make sure that you have Manager access in the database ACL. 2. Select the database icon from your bookmarks page. 3. Choose File - Database - Access Control. 4. Click the arrow next to “People, Servers, Groups” and select a specific access level. The ACL displays only those names with the selected access level. 5. Click OK.

Controlling User Access to Domino Databases 40-15

Access level privileges in the ACL
After you assign an access level to each user, group, and server, you can select or deselect privileges within an access level. This table lists the user access level privileges from highest to lowest. The section that follows describes each privilege in detail.
Access level Default privileges Manager Create documents Create private agents Create personal folders/views Create shared folders/views Create LotusScript/Java agents Read public documents Write public documents Create documents Create private agents Create personal folders/views Create shared folders/views Read public documents Write public documents Create documents Read public documents Write public documents Optional privileges Delete documents Replicate or copy documents

Designer

Delete documents Create LotusScript/Java agents Replicate or copy documents

Editor

Delete documents Create private agents Create personal folders/views Create shared folders/views Create LotusScript/Java agents Replicate or copy documents Create documents Delete documents Create private agents Create personal folders/views Create LotusScript/Java agents Write public documents Replicate or copy documents Create private agents Create personal folders/views Create LotusScript/Java agents Write public documents Replicate or copy documents continued

Author

Read public documents

Reader

Read public documents

40-16 Administering the Domino System, Volume 2

Security

Access level Default privileges Depositor Create documents

Optional privileges Read public documents Write public documents Read public documents Write public documents

No Access None

Create documents
Select this privilege for all users with Author access. If you deselect this privilege to prevent Authors from adding any more documents, they can continue to read and edit documents they’ve already created.

Delete documents
Authors can delete only documents they create. If this privilege is deselected, an author can’t delete documents, no matter what the access level. If the form contains an Authors field, Authors can delete documents only if their name, or a group or a role that contains their name, appears in the Authors field.

Create private agents
A user can run only agents that perform tasks allowed by the user’s assigned access level in the ACL. Whether or not a user can run agents is dependent on the access set by the Domino administrator in the Programmability Restrictions section of the Server document in the Domino Directory. If you select “Create LotusScript/Java agents” for a name in the ACL, the Server document controls whether or not the user can run the agent on the server. Since private agents on server databases take up disk space and processing time on the server, you may want to disallow this privilege. For more information, see the chapter “Controlling Access to Domino Servers.”

Create personal folders/views
Personal folders and views created on a server are more secure than those created locally, and they are available on multiple servers. Also, administrative agents can operate only on folders and views stored on a server. If the “Create personal folders/views” privilege is not selected, users can still create personal folders and views, but the folders and views are stored on their local workstations. Deselect this privilege to save disk space on a server.
Controlling User Access to Domino Databases 40-17

Create shared folders/views
Deselect this privilege to maintain tighter control over database design. Otherwise, a user assigned this privilege can create folders and views that are visible to others.

Create LotusScript/Java agents
Since LotusScript and Java agents on server databases can take up significant server processing time, you may want to restrict which users can create them. Whether or not a user can run agents depends on the access set by the Domino administrator in the Programmability Restrictions section of the Server document in the Domino Directory. If you select “Create LotusScript/Java agents” for a name in the ACL, the Server document controls whether or not the user can run the agent on the server.

Read public documents
Select this privilege to allow users who have No Access or Depositor access to read documents or to see views and folders to which the designer assigned the property “Available to Public Access users.” The form must contain a text field named $PublicAccess, and its value should be equal to 1.

Write public documents
Select this privilege to allow users to create and edit specific documents that are controlled by forms to which the designer has assigned the property “Available to Public Access users.” This option lets you give users create and edit access to specific documents without giving them Author access. Author access, or an equivalent role, gives users access to create documents from any form in a database. Note Users who have this privilege can also delete any public documents in the database.

Replicate or copy public documents
Select this privilege to allow users to replicate or copy the database, or documents from the database, locally or to the clipboard. You can select this privilege for all access levels except Depositor and No Access.

40-18 Administering the Domino System, Volume 2

Security

User types in the ACL
A user type identifies whether a name in the ACL is for a person, server, or group. When you assign a user type to a name, you specify the type of ID required for accessing the database with that name. The user types are Person, Server, Mixed Group, Person Group, Server Group, and Unspecified. The -Default- group in the ACL is always assigned Unspecified as the user type. If you have added Anonymous to the ACL, then it should have a user type of Unspecified. User types provide additional security for a database. For example, assigning the Person user type to a name other than “unspecified” prevents an unauthorized user from creating a Group document with the same person name, adding his or her name to the group, and then accessing the database through the group name. Designating a name as a Server or Server Group prevents a user from using the server ID at a workstation to access a database on the server. Be aware, though, that designating a name as a Server or Server Group is not a foolproof security method. It is possible for a user to create an add-in program that acts like a server and uses a server ID to access the server database from a workstation. Instead of assigning a user type to each name, you can automatically assign a user type to all unassigned names in the ACL. The user type assigned to each name is determined by the Domino Directory entry for that name. Using this method, a group is always designated as “Mixed Group,” and not as a “Person Group” or a “Server Group.” To assign a “Person Group” or “Server Group” to a name, you must select the name and manually assign that user type. You can assign user types to entries in multiple database ACLs, or you can have the server automatically assign user types to unspecified entries in a single database ACL.

To automatically assign user types to ACL entries
Use this method when you have just added a large number of entries to a database ACL. 1. Make sure that you have Manager access in the database ACL. 2. From the Domino Administrator Server pane, select the server that stores the databases. 3. Click Files, and select a database from the Domino data directory. 4. Click Tools - Database - Manage ACL. 5. Click Advanced.
Controlling User Access to Domino Databases 40-19

6. On the Advanced panel of the ACL dialog, click “Lookup User Types for ‘Unspecified’ Users.” The server uses the Domino Directory to look up each entry in the ACL and assign a user type of Person, Server, or Mixed Group. If it cannot find a match in the Directory, then the entry in the ACL will be left as “Unspecified.”

Roles in the ACL
A database designer can assign special access to database design elements and database functions by creating roles. A role defines a set of users and/or servers. They are similar to groups that you can set up in the Domino Directory. However, unlike groups, roles are specific to the database in which they are created. Once a role is created, it can be used in database design elements or functions to restrict access to those elements or functions. For example, you may want to allow only a certain group of users to edit certain documents in a database. You could create a role named “DocEditors.” That role would then be added to the Authors fields of those documents, and assigned to those users who are allowed to edit those documents. You must have Manager access to create roles in the database ACL. You must create a role before you assign it to a name or group in the ACL. Once you have created roles in an ACL, they are listed in the Roles list box on the Basics panel of the ACL dialog box. Role names appear in brackets — for example, [Sales]. When you add an entry to a database ACL, you can assign them to a role by selecting a role from the Roles list box. Note If you do not have Manager access to the ACL (meaning that you are not allowed to edit the ACL), the Roles tab does not appear in the ACL dialog box. This table describes the design elements to which the database designer can restrict access by using roles.
To restrict who can Edit specific documents Edit specific portions of a document Read specific documents The designer uses An Authors field Sections A Readers field or a read access list on the Security tab of the Document Properties dialog box continued

40-20 Administering the Domino System, Volume 2

Security

To restrict who can View and read documents in a specific view View and read documents in a specific folder Read documents created with a specific form Create documents with a specific form

The designer uses View properties Folder properties Form properties Form properties

Using roles to restrict access to database elements is not a foolproof security measure. For example, if a designer restricts access to certain documents in a database, the database manager or Domino administrator must remember that documents inherit their Reader access list from the Reader access option that is set in the Form Properties box for the form used to create the document. Therefore, anyone with Editor access or above in the database ACL can change a document’s Reader access list.

Creating and editing roles
You must create a role before you can assign it to a name in the ACL. In the Domino Administrator you can create, modify, or delete roles for multiple database ACLs, but you cannot assign a name to a role or remove a name from a role in the ACL or display names assigned to a role, as you can in the Notes client. To create and manage roles, you must have Manager access in the database ACL. To create or edit roles 1. Make sure that you have Manager access in the database ACL. 2. From the Domino Administrator Server pane, select the server that stores the databases. 3. Click Files and select one or more databases from the Domino data directory. 4. Click Tools - Database - Manage ACL. 5. Click Roles. 6. Do one of the following, and then click OK, and click OK again to save your changes: • To create a role, click Add, and type a name for the role. • To rename a role, click Rename. In the Rename Role box, type a new name for the role. • To delete a role, click Remove, and type the name of the role that you want to delete.

Controlling User Access to Domino Databases 40-21

Note In Domino Administrator, you do not need to include any brackets in the role name when adding or removing a role. However, when you rename a role, you must type the role name exactly as it appears in the ACL, including the brackets and case-sensitive characters. To assign a role to an ACL entry Because roles are specific to a database, you must modify database ACLs on an individual basis in order to assign roles to users. 1. Make sure that you have Manager access in the database ACL. 2. Open the database ACL that you want to modify. 3. Highlight the user to whom you want to assign a role. 4. In the Roles list box, select the role that you want to assign to that user. 5. Repeat steps 3 and 4 for each user to whom you want to assign a role. 6. Click OK to save your changes.

Managing database ACLs
As a Domino administrator, you can use any of these methods to manage database ACLs. To update ACLs • Use the Administration Process • • • Use the Web Administrator Edit entries in multiple ACLs View the list of all database ACLs on a server.

To monitor changes to ACLs • Display the ACL log to view a chronological list of changes to the ACL • Create an ACL monitor to automatically send you e-mail when any changes are made to the database ACL.

40-22 Administering the Domino System, Volume 2

Security

Using the Administration Process to update ACLs
To maintain maximum database security, you must be vigilant about keeping the ACL up to date. You can use the server administration process to do this. The Administration Process is a server program that automatically renames or deletes groups, servers, users, personal views, personal folders, and private agents, and then updates the Domino Directory and any database ACLs that have named the server running the Administration Process as their administration server. This program also updates the Readers and Authors fields for all documents in a database. You can select an administration server for the Administration Process in the Access Control List dialog box for single databases or in the Multi-ACL Management dialog box for multiple databases.

A user leaves the organization
When a user leaves the company, you can use the Domino Administrator to request that the user be deleted from the system. The Administration Process responds to this request and deletes the user’s Person document from the Domino Directory, as well as the user’s name from all Group documents, ACLs, roles, Readers and Authors fields, personal folders and views, and private agents.

A user needs access to the database
If possible, add new names to existing groups in the ACL rather than listing names individually. Consider whether to include new names in any roles associated with the database. If the database does not use roles, check whether there are access lists associated with forms, views, fields, or sections, and if so, consider whether to include new names in these lists. For more information on the use of public access lists with database design elements, see Application Development with Domino Designer.

A user name changes or you move the user in the hierarchy
Edit the user’s Person document in the Domino Directory. The Administration Process carries out all related renaming tasks in database ACLs and in personal folders and views and private agents.

Controlling User Access to Domino Databases 40-23

Setting up the Administration Process for database ACLs
To use the Administration Process to update and manage names in an ACL and in Readers and Authors fields, you must assign an administration server to the database. Use this method to specify an administration server for multiple databases. 1. Make sure that you have Manager access in the database ACL. 2. From the Domino Administrator Server pane, select the server that stores the databases. 3. Click Files, and select the databases from the Domino data directory to which you want to assign an administration server. 4. Click Tools - Database - Manage ACL. 5. Click Advanced. 6. Select “Modify Administration Server setting.” 7. Select Server, select an administration server from the list, and then click OK. Note When Notes users create databases, they can specify the administration server for their databases on the Advanced panel of the database ACL. The database ACL list will automatically be updated when the Administration Process is run on the specified administration server.

Managing database ACLs with the Web Administrator
The Web Administrator is a utility application that is packaged as a Notes database (WEBADMIN.NSF). 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 Web Administrator ACL. By default, Domino Full Access Administrators and Administrators get Manager access in the ACL of the WEBADMIN.NSF when this database is created. Have Manager access in the database ACLs of all the databases you want to modify.

40-24 Administering the Domino System, Volume 2

Security

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, if you are not using SSL with X.509 client certificates. This option is set to Manager by default in the WEBADMIN.NSF so you can add more user names to the ACL of the WEBADMIN.NSF from a browser.

You can use the Web Administrator to perform the following tasks for Internet or Notes users: • • • • • • • • • • • 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

Editing entries in multiple ACLs
As a Domino Administrator, you can make the following changes to entries that exist in multiple database ACLs. To edit entries in a database ACL, you must have Manager access to that ACL. You can also use the Web Administrator to manage database ACLs. For more information, see the topic “Managing database ACLs with the Web Administrator” earlier in this chapter.

To add or remove an entry
1. From the Domino Administrator Server pane, select the server that stores the databases. 2. Click Files, and select one or more databases from the Domino data directory. 3. Click Tools - Database - Manage ACL. 4. Click Add or Remove.

Controlling User Access to Domino Databases 40-25

5. Type the entry, or select it from the Domino Directory by clicking the button next to the list box 6. Click OK.

To rename an entry
1. From the Domino Administrator Server pane, select the server that stores the databases. 2. Click Files, and select one or more databases from the Domino data directory. 3. Click Tools - Database - Manage ACL. 4. Click Modify. 5. In the From box, type the name of the person, server, or group that you want to rename. 6. Select Modify Name. 7. In the To box, type the new name of the person, server, or group that you want to rename. 8. Click OK to save your changes.

To change the access, user type, or attributes assigned to an entry
1. From the Domino Administrator Server pane, select the server that stores the databases. 2. Click Files, and select one or more databases from the Domino data directory. 3. Click Tools - Database - Manage ACL. 4. Click Modify. 5. In the From box, type the name of the person, server, or group whose access or user type you want to change, and click OK. 6. Do one of the following, and then click OK, and click OK again to save your changes: • To change the user type assigned to an entry, select the user type from the drop-down list. • To change the access level assigned to an entry, select the access level from the drop-down list. • To modify the access level privileges assigned to an entry, click “Modify attributes” and type the name of the role that you want to delete. 7. Click OK.

40-26 Administering the Domino System, Volume 2

Security

Viewing all database ACLs on a server
You can view all the database ACLs on a server by user name, access level, or by database. To view a list of all database ACLs on a server 1. From the Domino Administrator Server pane, select the server that stores the databases. 2. Click Files. 3. Select the Catalog (V6) - Access Control Lists. 4. Select By Name, By Level, or By Database. • The By Name list shows the ACL list by ACL entry name, then access level, and then database title. • The By Level list shows the ACL list by access level, then ACL entry name, and then database title. • The By Database list shows the ACL list by database name, then server, then access level, and then ACL entry name.

Using the ACL log
You can display a log of all changes made to a database ACL. Each entry in the list shows when the change occurred, who made the change, and what changed. The log stores only 20 lines of changes, not the complete history. Only users who have manager access in the ACL can view the ACL log. To display an ACL log 1. Make sure that you have Manager access in the database ACL. 2. From the Domino Administrator Server pane, select the server that stores the databases. 3. Click Files, and select one or more databases from the Domino data directory. 4. Choose File - Database - Access Control. 5. Click Log. 6. Highlight a line of log history. To see the complete text of the log history, look in the field at the bottom of the dialog box. 7. (Optional) Click Copy to copy the ACL log to the clipboard so that you can paste it in a document. Note If you enable an ACL for Extended Access, there is no longer a 20-line limit for the log. The log also includes more details about Extended Access changes.

Controlling User Access to Domino Databases 40-27

Enforcing a consistent access control list
You can ensure that an ACL remains identical on all database replicas on servers, as well as on all local replicas that users make on workstations or laptops. Select the “Enforce a consistent Access Control List” setting on a replica whose server has Manager access to other replicas to keep the access control list the same across all server replicas of a database. If you select a replica whose server does not have Manager access to other replicas, replication fails because the server has inadequate access to replicate the ACL. If a user replicates a database locally, the database ACL recognizes that user’s access as it is known to the server. This happens automatically for local replication, regardless of whether “Enforce a consistent Access Control List” is enabled. It should be noted that local replicas with “Enforce a consistent access control list” enabled attempt to honor the information in the ACL and determine who can do what accordingly. However, they have some limitations. One limitation is that group information is generated on the server, not at the local replica. When a database is replicated locally, information about the group membership of the person doing the replication is stored in the database for use in ACL checking. If a person/identity other than the one doing the replication accesses the local replica, there will be no group membership information available for that person, and the ACL can use only the person’s identity, not group membership, to check access. Additionally, enforcing a consistent access control list does not provide additional security for local replicas. To keep data in local replicas secure, encrypt the database. Note If a user changes a local or remote server database replica’s ACL when the “Enforce a consistent Access Control List” option is selected, the database stops replicating. The log (LOG.NSF) records a message indicating that replication could not proceed because the program could not maintain a uniform ACL on replicas.

40-28 Administering the Domino System, Volume 2

Security

To enforce or disable a consistent access control list for multiple databases
1. Make sure that you have Manager access in all the database ACLs you select. 2. From the Domino Administrator Server pane, select a server that has Manager access to the databases on which you want to enforce a consistent ACL. 3. Click Files, and select one or more databases from the Domino data directory. 4. Click Tools - Database - Manage ACL. 5. Click Advanced. 6. Select the option “Modify Consistent ACL setting.” • To enforce a consistent ACL, select “Enforce a consistent Access Control List across all replicas of this database.” • To disable a consistent ACL, select “Do not enforce a consistent ACL.” 7. Click OK.

Updating Readers and Authors fields
By default, the Administration Process examines all documents in a database to find and update Readers and Authors fields and to update personal folders and views and private agents. When the Administration Process performs a “Rename person” or a “Delete person” request, it edits or removes the name in all Readers and Authors fields and in personal folders and views, and in private agents. To update Readers and Authors fields in only selected documents, you create a special view in the database and then update that view. You must select an administration server if you want to select the option to modify Readers and Authors fields. The default is to not modify Readers and Authors fields.

To update Readers and Authors fields
1. Make sure that you have Manager access in the database ACL and that you have already specified an administration server for the database. 2. From the Domino Administrator Server pane, select the server that stores the databases. 3. Click Files, and select the databases from the Domino data directory to which you want to assign an administration server.
Controlling User Access to Domino Databases 40-29

4. Click Tools - Database - Manage ACL. 5. Click Advanced. 6. Select “Modify Administration Server setting.” 7. Choose “Modify fields of type Reader or Author,” and click OK.

Setting up database access for Internet users
When you set up database access, you must make special provisions for Internet users. See the following topics for information about setting up and controlling the access that these users have to a database: • • • Specify maximum Internet name-and-password access. Require an SSL connection to a database Default entries in the ACL.

Maximum Internet name-and-password access
Users who have Internet or intranet browser access to a database cannot be identified by Notes in the same way Notes users are identified. Use the “Maximum Internet name & password access” setting to control the maximum type of access that Internet or intranet browser users have to a database. The list contains the standard access levels for Notes users. This option applies to users who use name-and-password authentication or access the server anonymously over the Internet and connect to servers using either the TCP/IP port or the SSL port. This option does not apply to users who have SSL client certificate IDs and who access the database over the Internet on the SSL port. Users with SSL client access receive the level of access specified in the database ACL. Add an entry for the group Anonymous to the database ACL, if appropriate for this database. Then select the maximum access level you want to assign to all Internet and intranet users who use name-and-password authentication for a particular database. Users who access a Notes database over the Internet, either anonymously or by using name-and-password authentication, never have an access level higher than what is specified as the “Maximum Internet name & password access” level. Caution The “Maximum” access level overrides the access level that a user may have been explicitly given in the database ACL, but only to enforce the lower of the two access levels.

40-30 Administering the Domino System, Volume 2

Security

For example, a user, Sandra Smith/West/Sales/Acme can use name and password to access a server using a Web browser. If Sandra Smith/West/Sales/Acme is assigned Editor access in the ACL and the “Maximum Internet name & password access” setting is Reader, the lower of the two access levels applies and Sandra is allowed only Reader access. Similarly, if Sandra Smith/West/Sales/Acme is assigned Reader access in the ACL and the “Maximum” access setting is Editor, Sandra is allowed only Reader access. However, if Sandra Smith also uses a Notes client to access the database, the “Maximum” access setting is ignored and Sandra is allowed Editor access. The default for this option is Editor access. Tasks such as creating folders, views, and agents do not apply to Internet users. Tip You can use this setting to prevent Internet users from accessing the database using name-and-password authentication. By setting it to “No Access,” the database would then be accessible only to Notes users or Internet users who authenticate using SSL client certificates.

Selecting the maximum Internet name and password
Use this method to select the maximum Internet name-and-password access for one or more databases. 1. Make sure that you have Manager access in all the database ACLs you select. 2. From the Domino Administrator Server pane, select a server that has Manager access to the databases. 3. Click Files, and select one or more databases from the Domino data directory. 4. Click Tools - Database - Manage ACL. 5. Click Advanced. 6. If you have selected multiple databases, select the option “Modify Internet name & password setting.” 7. Select the maximum access level from the list next to the field “Maximum Internet name & password.” 8. Click OK.

Requiring an SSL connection to a database
Secure Sockets Layer (SSL) is a security protocol that provides communications privacy and authentication for Domino server tasks that operate over TCP/IP. You can require users to access a database using a secure SSL connection. You can also choose to require an SSL connection to a single database or to all databases on a server.
Controlling User Access to Domino Databases 40-31

If the server is not configured to require an SSL connection, clients will be able to use either SSL or unsecured TCP/IP to connect to the server; for example, in a browser, by using HTTP (for non-SSL) or HTTPS (for SSL). For more information about Internet client access to Domino servers and databases, see the chapter “Setting Up Name-and-Password and Anonymous Access to Domino Servers.” To require an SSL connection to a database 1. Make sure you have Manager access in the database ACL. 2. From the Domino Administrator Server pane, select a server that stores the database(s) for which you want to require an SSL connection. 3. Click Files, and open the database from the Domino data directory. 4. Choose File - Database - Properties. 5. On the Basics tab, choose Web access: Require SSL connection.

40-32 Administering the Domino System, Volume 2

Security

Chapter 41 Protecting User Workstations with Execution Control Lists
This chapter describes how to set up and manage execution control lists for user workstation data security.

The execution control list
You use an execution control list (ECL) to set up workstation data security. An ECL protects user workstations against active content from unknown or suspect sources, and can be configured to limit the action of any active content that does run on workstations. The ECL determines whether the signer of the code is allowed to run the code on a given workstation, and defines the access that the code has to various workstation functions. For example, an ECL can prevent another person’s code from running on a computer and damaging or erasing data. “Active content” includes anything that can be run on a user workstation, including formulas; scripts; agents; design elements in databases and templates; documents with stored forms, actions, buttons, hot spots; as well as malicious code (such as viruses and so-called “Trojan horses”). There are two kinds of ECLs: the Administration ECL, which resides in the Domino Directory (NAMES.NSF), and the workstation ECL, which is stored in the user’s Personal Address Book (NAMES.NSF). The Administration ECL is the template for all workstation ECLs. The workstation ECL is created when the Notes client is first installed. The Setup program copies the administration ECL from the Domino Directory to the Notes client to create the workstation ECL.

The workstation ECL
A workstation ECL lists the signatures of trusted authors of active content. “Trust” implies that the signature comes from a known and safe source. For example, every system and application template shipped with Domino or Notes contains the signature Lotus Notes Template

41-1

Development. Likewise, every template and database that your organization designs should contain the signature of either the application developer or the administrator. For each signature, the ECL contains settings that control the actions that active content signed with that signature can perform and the workstation system resources it can access. For a description of ECL access options, see the topic “ECL security access options” in this chapter. How the workstation ECL works When active content runs on a user workstation and attempts a potentially harmful action — for example, programmatically sending mail — the following occurs: 1. Notes verifies that the active content is signed and looks up the signer of the code in the workstation ECL. 2. Notes checks the signer’s ECL settings to determine whether the action is allowed. 3. One of the following occurs: a. If the signer of the code is listed in the workstation ECL and the appropriate setting is enabled, the active content runs. b. If the active content attempts an action that is not enabled for the signer, or if the signer is not listed in the ECL, Notes generates an Execution Security Alert (ESA), which specifies the attempted action, the signer’s name, and the ECL setting that is not enabled. The ESA gives the user four options: • Do not execute the action — to deny the signer access to perform the specified action. • Execute the action this one time — to allow the signer access to perform the action only once. The ESA appears again if the same action is attempted in the future. This option does not modify the ECL. • Start trusting the signer to execute this action — to allow the action to be performed and modify the ECL configuration to add the signature of the active content to the ECL. This grants permission for the signer to execute the specific action any time on that workstation.

41-2 Administering the Domino System, Volume 2

Security

• More Info — to display a dialog box that provides information about the design type, design name, Notes ID, signature status, and parent database of the code that caused the ESA. For example, locally scheduled agents, as well as manual agents, can generate ESAs. Click “More Info” to get information about the agent that generated the alert. Note The administration ECL has a setting that prevents users from changing their workstation ECLs. If this setting is enabled, then the user’s option to trust the signer is disabled.

ECL security access options
There are three categories of access options for ECLs. • • • Workstation security Java applet JavaScript

Workstation security access options Choose from these options when setting up access to workstation data for active content, such as Notes databases:
Access option Access to file system Access to current database Access to environment variables If enabled, allows formulas and code to Attach, detach, read to, and write from workstation files Read and modify the current database Use the @SetEnvironment and @GetEnvironment variables and LotusScript methods to access the NOTES.INI file

Access to non-Notes databases Use @DBLookup, @DBColumn, and @DBCommand to access databases when the first parameter for these @ functions is a database driver of another application Access to external code Access to external programs Ability to send mail Run LotusScript classes and DLLs that are unknown to Notes Access other applications, including activating any OLE object Use functions such as @MailSend to send mail

Ability to read other databases Read information in databases other than the current database Ability to modify other databases Modify information in databases other than the current database continued Protecting User Workstations with Execution Control Lists 41-3

Access option Ability to export data Access to Workstation Security ECL

If enabled, allows formulas and code to Print, copy to the clipboard, import, and export data Modify the ECL

Java applet options Choose from these options when setting up access to workstation data for Java applets that run in Notes:
Access option Access to file system Access to Notes Java classes Access to network addresses If enabled, allows the applet to Read and write files on the local file system. Load and call the Domino objects for Java and CORBA. Bind to and accept connections on a privileged port (a port outside the range 0 to 1024) and establish connections with other servers. Submit print jobs. Read system properties such as color settings and environment variables. Access the system clipboard. Also disables the security banner that is displayed in the top-level window to indicate that a Java applet created the window. Displaying the security banner reminds users not to enter security-sensitive information into a dialog that masquerades as a password dialog, for example. Create threads and threadgroups, fork and run external processes, load and link external libraries, access nonpublic members of classes using Java core reflection, and access the AWT event queue.

Printing Access to system properties Dialog and clipboard access

Process-level access

JavaScript options These options control access to workstation data for JavaScript that runs in the Notes client, on a Notes form or on a Web page rendered by the Notes browser. These options do not control JavaScript run by other browsers, including the Microsoft Internet Explorer browser, even when the browser is embedded in the Notes client. JavaScript ECL settings control whether JavaScript code can read and/or modify JavaScript properties of the Window object. You can allow read access from, and write access to, the properties of the Window object. As the top-level object in the JavaScript document object model, the Window
41-4 Administering the Domino System, Volume 2

Security

object has properties that apply to the entire window. Securing access to the Window object secures access to other objects on the page since the JavaScript program cannot access the objects further down in the object model hierarchy without first traversing the Window object. Window object classes are described in the following table:
Window object class Source window Description Default

Allow read Controls JavaScript access to the Window and write object on the same page as the JavaScript code. Selecting this option does not prevent a access JavaScript directly to the object on the source window, because doing so circumvents the Window object; therefore this ECL option is not enforced. Controls JavaScript access to the Window Allow read object on a different page from the JavaScript and write code, but from a page using the same host. access For example, JavaScript code on a page on www.lotus.com can access the Window object on another page on www.lotus.com. This allows two pages to interact if they are within the same frameset. Controls JavaScript access to the Window Not allow object on a different page within a frameset read and write access that uses a different host. For example, JavaScript code on a page on www.lotus.com can access the Window object on a page on any other server. Enabling this option poses a high security risk because of the possibility of malicious code on one page of the frameset accessing data on another page.

Other window from same host

Other window from different host

Two additional ECL options control whether JavaScript that runs in the Notes client is authorized to open a new Web page or Notes document. You can enable open access for these options, described in the following table:
Option URL on same host Description Controls access for opening a page or Notes document on the same host as the JavaScript code. Default Allow open access

URL on different Controls access for opening a page or Notes Not allow host document on a different host as the JavaScript open access code.

Protecting User Workstations with Execution Control Lists 41-5

The administration ECL
When you set up the first server in a domain, Domino creates a default administration ECL, which you can then customize. The administration ECL is the template for all workstation ECLs. Whenever a new Notes client is installed, the setup program copies the administration ECL from the Domino Directory to the Personal Address Book on the Notes client workstation. The user’s Notes ID is added to the workstation ECL, with all access allowed. For example, when John Doe’s Notes client is being set up, John Doe is automatically added to the client ECL signer list. If the home server is unavailable when a Notes client is installed — for example, when a user is disconnected — the workstation ECL is created with default settings, rather than being created from the administration ECL. Note Technically, when a server is initially installed, there is no Admin ECL. When a client attempts to edit the workstation ECL, or refresh it from an admin ECL that does not exist, the client creates an ECL with default settings that are coded into the client. The Admin ECL exists on disk, once an administrator modifies and saves it. Once the modified administration ECL is saved to disk, then that is the ECL that is copied to user workstations. You use the administration ECL to define and deploy customized ECLs for your users. You can control ECL changes or allow users to modify their own ECLs. Furthermore, you can update your users’ workstation ECLs as security requirements change — automatically, through the use of a security settings document deployed through a policy, or manually, by asking users to refresh their workstation ECLs. To create customized ECLs that can be deployed for specific groups of users, you must use a security settings document that is deployed through a server policy. For example, you can create one ECL exclusively for contract employees and another ECL for full-time employees. For more information on using policies for security, see the chapter “Using Policies.”

Guidelines for creating an effective administration ECL
Your goal as an administrator is to limit the number of trusted signers for active content, and the access that active content has to user workstations. To accomplish this goal, limit the number of trustworthy signers in your organization and ensure that workstation ECLs trust only those signers.

41-6 Administering the Domino System, Volume 2

Security

Use these guidelines to create secure ECLs: • Do not grant access to unsigned content. This creates a security hole that allows potentially harmful code, malicious or otherwise, to access user workstations. Keep the default access options for unsigned content. Do not let your users trust unsigned content. To prevent users from changing their ECLs — for example, by giving access to unsigned content, or to content signed by signers who are not listed in the ECL, deselect “Allow user to modify” in the Administration ECL. Know your signers. Trusting signed active content, especially from other organizations, is risky. Before adding an active content author to an ECL, decide if you trust that the author has created safe code. Create a separate certifier for an organizational unit to issue IDs specifically for users who must sign templates and applications — for example, Enterprise ECLApp Signer/West/Acme. Then users who create templates and applications use those IDs to sign templates and applications. You can then set up the administration ECL to trust any user in that special organizational unit, or fine-tune it on a per-user basis.

Default ECL settings
When you first edit the ECL, it includes the following signatures and access options. By default, the ECL does not allow access to protected operations for active content that is unsigned, or for active content that is signed by a signer who is not listed in the ECL.
Signature -DefaultApplies to Default access options

Formulas and code that contain a None signature, and that signature is verified by Domino, but the signature does not match any entry in the ECL. For example, if the signer is John Andrews/Atlas, but the ECL does not contain this signature, the ECL uses the -Default- signature to assign access. continued

Protecting User Workstations with Execution Control Lists 41-7

Signature -No Signature-

Applies to

Default access options

Formulas and code that contain an None invalid or corrupted signature, are unsigned, or are signed by an identity or organization that can’t be verified by Domino. For example, if the code is not signed, or is signed by a user unknown to the Domino server, the ECL matches -No Signature-. Every template related to Binary Tree Mail and Calendar Migration Tools. If your organization isn’t using this tool, you can remove this entry from the ECL. Access to file system, Access to current database, Access to environment variables, Access to external code, Ability to read other databases, Ability to modify other databases Access to current database, Access to environment variables, Access to external code, Access to external programs, Ability to send mail, Ability to read other databases, Ability to modify other databases Access to current database, Access to environment variables, Ability to read other databases, Ability to modify other databases continued

BT Mail and Calendar Migration Tools/ Lotus Notes Companion Products

Domino Unified Communications Services/Lotus Notes Companion Products

Every template related to Domino Unified Communications Services. If your organization isn’t using this tool, you can remove this entry from the ECL.

Lotus Fax Development/ Lotus Notes Companion Products

Every template related to Lotus Fax for Domino. If your organization isn’t using this tool, you can remove this entry from the ECL.

41-8 Administering the Domino System, Volume 2

Security

Signature Lotus Notes Template Development/ Lotus Notes

Applies to Every template shipped with Domino and Notes. For example, the signer matches this type only if it has the Lotus Notes Template Development/Lotus Notes signature.

Default access options All

Sametime Development/ Lotus Note Companion Products

All except Access to Every template related to workstation security Sametime. If your organization isn’t using this ECL tool, you can remove this entry from the ECL.

You can also add additional users or signature types to the ECL. You could add the hierarchical names of specific users or groups — for example, Phyllis Spera/Sales/East/Acme. If you create a special certifier to certify the IDs of a group of trusted signers, you could use a wildcard character to name all signers — for example, */Trusted Signers/Acme. The table below describes the access that these users (or signature types) in an ECL would have:
Signature */Trusted Signers/Acme Applies to Formulas and code that have */Trusted Signers/Acme signature. For example, if the signer is anyname/Trusted Signers/Acme — such as Emily Marks/Trusted Signers/Acme or Alan Jones/Sales/East/Trusted Signers/Acme — the ECL uses the */Trusted Signers/Acme signature to match access. Formulas and code that have Phyllis Spera/Sales/East/Acme as the signature. For example, the signer matches this type only if the ECL contains the Phyllis Spera/Sales/East/Acme signature.

Phyllis Spera/Sales/East/Acme

Protecting User Workstations with Execution Control Lists 41-9

Collecting information for a new administration ECL
Before you can create an Admin ECL to distribute, identify the individual people and/or organizations that you can trust to create and sign active content. Identify a few users who use a broad range of typical Notes applications, then ask them to complete these steps. 1. Remove all entries from the workstation ECL except the following: • All entries in the form */org, where org is a local domain/organization • -Default• -No signature• Lotus Notes Template Development/Lotus Notes To do this, highlight the item to remove under “When signed by,” then click Remove. Note If any of these entries are not listed in the ECL, it means that those entries are not needed. 2. Make a list of the entries you remove so that if those entries were, in fact, not needed, they can later be added with “No access” in the administration ECL. 3. Make these changes to the remaining entries in the ECL:
For “When signed by” */org, where org is a local domain/organization -Default-No signatureLotus Notes Template Development/Lotus Notes For “Allowed” Deselect all selected items. Deselect all selected items. “Default” should have no permissions. Deselect all selected items. Select all items. This signer should have all permissions.

4. For a designated time period (a week should be sufficient), when the Execution Security Alert dialog box appears, click “Trust signer,” with the following exceptions: • Do not trust any actions with “-No Signature-”. • Check with the administrator before trusting odd or unfamiliar signatures or before clicking “Execute once” for templates and applications signed with odd or unfamiliar signatures. Note Users who use the Lotus Notes Client 5.01 or earlier should choose “No” in the dialog box that asks if you want to trust everybody in the organization of the user whose signature you are about to trust.
41-10 Administering the Domino System, Volume 2

Security

The resulting ECLs for these users should contain more signers than what the ECL originally contained, unless your organization has managed the signing process up front and only uses objects signed by a small number of known trustworthy signers. After the designated time period is complete, the administrator should combine the signatures in the users’ ECLs to create an updated administration ECL. The workstation ECL log The Lotus Notes 6 Client logs ECL-related operations in the Client log (LOG.NSF) in Miscellaneous Events. This includes: • Results of Execution Security Alert (ESA) dialogs, as well as additional ESA details. These details include information about the code that caused the ESA, such as the design type, design title, NoteID, database title, and path. Any ECL modifications. This includes information on which ECL was modified; the ECL entries that were changed, added or deleted; and the rights that were granted or revoked. It also includes all ECL modifications resulting from such operations as dynamic ECL update, programmatic ECL refresh (@ECLRefresh function), setup ECL refresh/creation and manual ECL changes made in the ECL Editor or through the User Security Panel.

It is possible to write an agent to run on Notes clients and parse the ECL logging data to provide administrators with specific information on how users are managing their workstation ECLs, as well as current information about applications or other code that should be added to Admin ECLs.

Creating the administration ECL
Before you register users, edit the administration ECL to create a template for user workstation ECLs. Use the following procedure to create and deploy an administration ECL that provides a good starting point for managing and maintaining secure workstation ECLs. You can deploy and maintain ECLs on a group and organizational basis through the use of policies. For more information, see the chapter “Using Policies.” 1. (Optional) Collect information for creating the administration ECL. For more information, see the topic “Collecting information for a new administration ECL” in this chapter. 2. Edit the Administration ECL.

Protecting User Workstations with Execution Control Lists 41-11

For more information, see the topic “Editing the administration ECL” in this chapter. 3. Deploy the new ECL to user workstations. This happens automatically when Notes client software is first installed on user workstations. 4. Update user workstation ECLs, as required.

Editing the administration ECL
1. From the Domino Administrator, click the Files tab. 2. From the Servers pane, choose the server to work from. 3. Open the Domino Directory (NAMES.NSF). 4. Choose Actions - Edit Administration ECL. 5. (Optional) Select -Default- and then select access options. For more information on access options, see the topic “ECL security access options” in this chapter. 6. (Optional) Select -No Signature- and then select access options. 7. To add an entry, click Add, enter the name of a person or server, and then click OK. a. Enter an asterisk (*) to allow access to all users, even those not listed in the Domino Directory, access. b. Enter an asterisk (*) followed by a certifier name — for example, */Acme — to allow access to users certified by that certifier. Note Add entries to the ECL even if you want to deny access to a person, group, or organization. Then you can overwrite existing entries in workstation ECLs and essentially undo any trust users have granted. For example, to revoke access previously granted to someone, add that person to the administration ECL, but don’t give them any privileges. When the updated administration ECL is distributed, it will overwrite the workstation ECLs with the updated privileges for that person. 8. To remove an entry, select it from the list and click Remove. Note Removing an entry will not deny access to that entry when existing client ECLs are refreshed. To ensure that this entry no longer has access, leave the entry in the list and instead, remove all rights. 9. To rename an entry, select it from the list and click Rename. Note It may be better to leave the existing entry and add a new entry with the new name instead. Active content signed with the user’s previous name will then still be allowed the same access it had before.
41-12 Administering the Domino System, Volume 2

Security

10. To let users modify their workstation ECLs or enable Java applets from trusted senders, select “Allow users to modify.” 11. Click OK.

Deploying and updating workstation ECLs
If you create an Admin ECL prior to registering users, that Admin ECL is deployed automatically to user workstations when users run Notes setup during install. For Domino 6, you can also deploy and maintain ECLs through the use of policies, which allow you to create and deploy ECLs on a group or organizational basis, as well as define the frequency and extent to which workstation ECLs are updated. For more information about using policies to create, deploy, and update ECLs, see the chapter “Using Policies.” If you edit the administration ECL after users run setup, and you are not using a security policy, you can use one of the following procedures to update user workstation ECLs. • • Use the @Refresh ECL function, through a memo or common database event Have users update their ECLs through the User Security dialog box.

To use the @RefreshECL function to update workstation ECLs This procedure enables users to update their workstation ECL by running a macro that copies the current administration ECL to the local workstation ECL. 1. Make sure the Domino Directory with the ECL changes has replicated throughout the domain. 2. Address a memo to users whose ECLs you want to update. 3. Add a button to the memo that executes this formula: @RefreshECL (server : database ; name) Where server : database is a text list that specifies the server location and file name of the Domino Directory (NAMES.NSF) that contains the administration ECL; and name is text that specifies the name of the administration ECL. Specify “” (null) if you have not named the administration ECL. For example, for an unnamed administration ECL located in NAMES.NSF on the server SERVER1, the @RefreshECL formula is:

@RefreshECL("server1":"names.nsf";"")
Note For MIME-enabled users who lose their active content in mail messages, add the button to a document in a particular Notes database and tell those users to go there to update their ECLs.
Protecting User Workstations with Execution Control Lists 41-13

4. Describe the purpose of the memo and instruct users to click the button. 5. Mail the memo. Tip Add the @Refresh ECL function to a common database event, so that all users in the organization can use it to update their ECLs. To use the Refresh button to update workstation ECLs 1. Make sure the Domino Directory with the ECL changes has replicated throughout the domain. 2. Address a memo to users whose ECLs you want to update. 3. Describe the purpose of the memo and instruct the users to do the following: a. Choose File - Security - User Security. b. Click “What Others Do,” and then click “Using LotusScript,” “Using Java,” or “Using JavaScript.” c. Click “Refresh All” 4. Mail the memo. Note Even after you distribute an updated ECL, users might still encounter Execution Security Alerts. Make sure that users: • Do not trust any actions with “-No Signature-” • Check with you before trusting any odd or unfamiliar signatures, or before clicking “Execute once” for templates or applications signed with odd or unfamiliar signatures. Investigate those signatures, and if necessary, update and redistribute the administration ECL.

Administration ECL <ECLOwner> key
In order to provide more flexibility to users, especially in organizations that do not allow users to modify their own ECLs, administrators can set the execution rights of the current ECL owner during workstation ECL refresh and replace. You do this by adding the key string
<ECLOwner>

as an entry in the Admin ECL. You then give that entry the ECL rights that are appropriate for a workstation user. For example, if you want to give users the ability to write and execute basic Notes programs on their own workstations, you would enable the appropriate rights for this entry.

41-14 Administering the Domino System, Volume 2

Security

When a workstation ECL is refreshed or replaced, the <ECLOwner> entry is replaced with the name of the current user. This updates the user’s workstation ECL rights with those set in the Admin ECL for the key string entry. If this key string entry is not included in the Admin ECL, and if “Allow user to modify” is not enabled, the current user entry is removed from the workstation ECL during ECL replace. If “Allow user to modify” is enabled, the current user remains in the Workstation ECL Refreshing the ECL without the key string leaves the current user’s entry as is.

Protecting User Workstations with Execution Control Lists 41-15

Security

Chapter 42 Setting Up Name-and-Password and Anonymous Access to Domino Servers
This chapter describes how to set up servers for name-and-password and anonymous access by Internet/intranet clients.

Name-and-password authentication for Internet/intranet clients
Name-and-password authentication, also known as basic password authentication, uses a basic challenge/response protocol to ask users for their names and passwords and then verifies the accuracy of the passwords by checking them against a secure hash of the password stored in Person documents in the Domino Directory. When set up for this, Domino asks for a name and password only when an Internet/intranet client tries to access a protected resource on the server. Internet/intranet access differs from Notes client and Domino server access in that a Domino server asks a Notes client or Domino server for a name and password when the client or server initially attempts to access the server. If you want to assign database access to an Internet/intranet client based upon Domino ACL security, you must create a Person document for that client in the Domino Directory, or, optionally, in a secondary Domino directory or an external LDAP directory. Clients who do not have Person documents are considered Anonymous and can only access servers and databases that allow Anonymous access. Name-and-password authentication allows Domino to locate the Person document (if one exists) for the client accessing the server. After the client is identified, access to server resources can then be determined. For example, if you want Alan Jones to have Editor access to a database and all others accessing the database to have Author access, you must create a Person document for Alan Jones. You can set up the database ACL to include Alan Jones as an Editor and Anonymous as Author. You can use name-and-password authentication with either TCP/IP or SSL on any servers that run an Internet protocol — namely, LDAP, POP3, HTTP, SMTP, IIOP, or IMAP. For each Internet protocol enabled on the server, you can specify the method of security. For example, you might
42-1

enable client certificate authentication for HTTP connections but require name-and-password security for LDAP connections that use TCP/IP. Or you might use name-and-password security with anonymous and SSL client authentication — for example, to allow users with SSL client certificates to authenticate using SSL client authentication and to allow other users to enter a name and password if they do not have an SSL client certificate. Note Name-and-password authentication is not supported when a Domino server acts as an SMTP client — for example, when a Domino server connects to an SMTP server to route mail. Name-and-password security is supported only when a Domino server acts as an SMTP server — that is, when SMTP clients access a Domino server. If you are setting up name-and-password authentication for an HTTP server, you have an additional method to use with name-and-password authentication: session-based authentication. Name and password authentication sends the name and password in unencrypted format and is sent with each request. Session-based authentication differs in that the user name and password is replaced by a cookie. The user’ name and password is sent over the network only the first time the user logs in to a server. Thereafter the cookie is used for authentication. Session-based name-and-password authentication offers greater control over user interaction than basic name-and-password authentication and lets you customize the form in which users enter their name and password information. It also allows users to log out of the session without closing the browser.

Name-and-password authentication over non-SSL secured connections
Use name-and-password authentication over non-SSL secured connections to identify users without tightly securing access to data on the server — for example, when you want to display different information to different users based on the user name and when the information in the database is not confidential. No information, including the name and password, sent between the user and server is encrypted. In this case, name-and-password authentication deters some types of hackers but does not prevent others from listening to network transmissions and guessing passwords.

42-2 Administering the Domino System, Volume 2

Security

Name-and-password authentication over SSL
Using SSL, all information, including the name and password, is encrypted. SSL provides confidentiality and data integrity for users set up for name-and-password authentication. Requiring a name and password in addition to SSL security provides security for users who do not use client certificate authentication and allows you to identify individual users who access a database. For information on setting up an SSL server, see the chapter “Setting Up SSL on a Domino Server.” For information on setting up clients for SSL, see the chapter “Setting Up Clients for S/MIME and SSL.”

Customizing name-and-password authentication
The Domino Web Server Application Programming Interface (DSAPI) is a C API that you can use to write your own extensions to the Domino Web Server. These extensions, or “filters,” let you customize the authentication of Web users. For more information on DSAPI and filters, see the Lotus C API Toolkit for Domino and Notes. The toolkit is available at www.lotus.com/techzone.

Setting up basic name-and-password authentication
To enable basic name-and-password authentication, for both TCP and SSL, for all Internet protocols: Web (HTTP); IMAP; POP3; LDAP; SMTP Inbound; and IIOP, you must complete three separate procedures: • Create an Internet Site document for the Internet protocol for which you want to require a name and password. or Edit the Server document to specify which Internet protocols require a name and password. • • Create a Person document for each user in the Domino Directory on the Domino server and assign an Internet password to each user. Edit server database ACLs to give users access.

To enable basic name-and-password authentication for Internet Site documents 1. From the Domino Administrator, click Configuration - Web - Internet Sites. 2. In the Internet Sites view, select the Internet Site document for which you want to enable name-and-password authentication.
Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-3

3. In the Internet Site document, click Security. • If you want clients to use name-and-password authentication when they connect using TCP/IP, select Yes in the Name & password field in the TCP Authentication section. • If you set up SSL on the server and you want clients to use name-and-password authentication when they connect using SSL, select Yes in the Name & password field in the SSL Authentication section. 4. Save the document. To enable basic name-and-password authentication in the Server document 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click Ports - Internet Ports. This displays four tabs: Web, Directory, Mail, and IIOP. Each tab lists protocols appropriate for its name — for example, the Web tab lists HTTP/HTTPS, and the Mail tab lists IMAP, POP3, and SMTP. 3. Click the protocol for which you want to specify name-and-password authentication. For each protocol, do the following: • If you want clients to use name-and-password authentication when they connect using TCP/IP, select Yes in the Name & password field in the TCP/IP section. • If you set up SSL on the server and you want clients to use name-and-password authentication when they connect using SSL, select Yes in the Name & password field in the SSL section. 4. Save the document. Note If you want LDAP clients to access the server using name-and-password authentication, you must also allow anonymous access for LDAP on the server as well. LDAP clients who access the server using a browser supply an e-mail address for authentication, and the client searches for the address anonymously before Domino can authenticate the user. For information on setting up anonymous access, see the topic “Setting up Internet/intranet clients for anonymous access” later in this chapter. To create Person documents for Internet/intranet users 1. In the Domino Directory, create a Person document for each user who needs to access the server. (You can also edit the Person document of an existing user.)

42-4 Administering the Domino System, Volume 2

Security

Note Users can also be created in secondary Domino directories or external LDAP directories, if your server is configured to use them. 2. In each Person document, complete these fields, and then save the document:
Field Action First name, Middle Enter the user’s first name, middle initial, and last initial, Last name name. The user’s last name is required. User name (Required) Enter the user’s full name. This is the name the user enters when trying to access a server. This field can contain multiple names. However, Domino uses the first name in this field to validate a user in database ACLs, design access lists, groups, and File Protection documents. For example, this field can contain these names: • Alan Jones/Sales/Acme • Alan Jones • Al Jones • AJ When prompted for his name and password, the user can enter “Al Jones” as his name. However, Domino uses “Alan Jones/Sales/Acme” to validate him in database ACLs and design access lists. Therefore, the name “Alan Jones” must be the one that appears in ACLs and design access lists. Note You should always use the user’s hierarchical name — for example, Alan Jones/Acme/US — to help eliminate ambiguous or duplicate user names. Internet password (Required) Specify the user’s Internet password.

To edit database ACLs After you edit the Server document and create Person documents, edit the database ACL of each database to which you want to give users access. For more information on setting up a database ACL, see the chapter “Controlling User Access to Domino Databases.”

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-5

Session-based name-and-password authentication for Web clients
To set up name-and-password authentication for Web clients who have access to a Domino Web server, you can use one of two methods: basic name-and-password authentication or session-based name-and-password authentication. Session-based name-and-password authentication includes additional functionality that is not available with basic name-and-password authentication. A session is the time during which a Web client is actively logged onto a server with a cookie. To specify settings that enable and control session authentication, you edit the Web Site document or the Server document, depending on your configuration. Furthermore, you have two selections for enabling session-based authentication — single and multi-server selections. The single server option causes the server to generate a cookie that is honored only by the server that generated it, while the multi-server option generates a cookie that allows single sign-on with any server that shares the Web SSO configuration document. To use session-based authentication, Web clients must use a browser that supports cookies. Domino uses cookies to track user sessions.

Features of session-based name-and-password authentication
Name-and-password authentication sends the client’s name and unencrypted password, and is sent with each request to the server. Session-based authentication differs in that the client’s name and encrypted password is stored in a cookie on the workstation. That information is sent over the network only the first time the user logs in to a server, not each time a request is posted. Using session-based name-and-password authentication provides greater control over user interaction than basic name-and-password authentication. For example, you can customize the form in which users enter their name and password information. It also allows users to log out of the session without closing the browser. Customized HTML log-in form An HTML log-in form allows a user to enter a name and password and then use that name and password for the entire user session. The browser sends the name and password to the server using the server’s character set. For HTTP session authentication, a user can enter a name, using any printable characters in Unicode. The user password, however, must be entered in any printable characters in US-ASCII. Note Printable characters excludes control characters.
42-6 Administering the Domino System, Volume 2

Security

Domino provides a default HTML form — ($$LoginUserForm), which is provided and configured in the Domino Configuration database (DOMCFG.NSF). You can customize the form or create your own to contain additional information. Default logout time period You can specify a default logout time period to log the Web client off the server after a specified period of inactivity. This forces the cookie that Domino uses to track the user session to expire. Automatically logging a user off the server prevents others from using the Web client to impersonate a user if the user leaves the workstation before logging off. If you enable session-based name-and-password authentication for a server, users can also append ?logout at the end of a URL to log off a session — for example: http://acmeserver/sessions.nsf?logout. You can also redirect the logout to a design element or URL. For example: http://acmeserver/sessions.nsf?logout&redirectto=/logoutDB.nsf/ logoutApp?OpenPage http://acmeserver/sessions.nsf?logout&redirectto=http://www. sales.com You can build this expression into an application — for example, using it in a button — or type it in as a URL. Maximum user sessions You can specify the maximum number of concurrent user sessions allowed on the server for single-server session-based authentication only. If server performance is slow, you can reduce this number. Internet password management Domino 6 provides features for managing Internet passwords for session-based authentication. Multi-server session-based authentication Multi-server session-based authentication, also known as single sign-on, allows Domino cookies to span servers. It also allows Domino and Websphere servers to interoperate and share cookies. Note If your servers are set up for round-robin DNS, you should use the multi-server (or single sign-on) option for session-based name-and-password authentication. Servers cannot store the session information in memory when using round-robin DNS with the single server cookie. In addition, if a server is restarted or crashes, session
Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-7

information is lost, and then users must re-enter their names and passwords. This will not occur with the multi-server session authentication option.

Setting up session-based name-and-password authentication
To set up single-server session-based name-and-password authentication for Web clients, you must complete three procedures: • Create a Web site document and enable it for session-based name-and-password authentication. or Edit the Server document to require session authentication for Web clients. • • Create a Person document for each Web client who will use session-based name-and-password authentication. Edit the database ACLs to give users access.

To enable single-server session-based authentication for Web Site documents 1. From the Domino Administrator, click Configuration - Web - Internet Sites. 2. In the Internet Sites view, select the Web Site document for which you want to enable session authentication. 3. In the Web Site document, click Domino Web Engine. 4. In the HTTP Sessions section, complete these fields:
Field Idle session timeout Maximum active sessions Action Enter a default time period to log an inactive Web client off the server. Default is 30 minutes. Enter the maximum number of user sessions allowed on the server at the same time. Default is 1000. Session authentication Select single server. This is disabled by default.

5. Click Security, and enable name-and-password authentication for the TCP and for SSL (if using SSL). 6. Save the document. To edit the Server document for single-server session-based name-and-password authentication 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click Internet Protocols - Domino Web Engine.
42-8 Administering the Domino System, Volume 2

Security

3. Complete these fields:
Field Idle session timeout Maximum active sessions Action A default time period to log an inactive Web client off the server. Default is 30 minutes. The maximum number of user sessions allowed on the server at the same time. Default is 1000. Session authentication Select single server. This is disabled by default.

4. Click Ports - Internet Ports - Web, and enable name-and-password authentication for the TCP/IP port and for the SSL port (if using SSL). 5. Save and close the Server document. To create Person documents for Web users 1. In the Domino Directory, create a Person document for each Web user who needs to access the server. (You can also edit the Person document of an existing user.) 2. In each Person document, complete these fields, and then save the document:
Field Action First name, Middle Enter the user’s first name, middle initial, and last initial, Last name name. The user’s last name is required. User name (Required) Enter the user’s full name. This is the name the user enters when trying to access a server. This field can contain multiple names. However, Domino uses the first name in this field to validate a user in database ACLs, design access lists, groups, and File Protection documents. For example, this field can contain these names: • Alan Jones/Sales/Acme • Alan Jones • Al Jones • AJ When prompted for his name and password, the user can enter “Al Jones” as his name. However, Domino uses “Alan Jones/Sales/Acme” to validate him in database ACLs and design access lists. Therefore, the name “Alan Jones” must be the one that appears in ACLs and design access lists. Note You should always use the user’s hierarchical name — for example, Alan Jones/Acme/US — to help eliminate ambiguous or duplicate user names.

Internet password (Required) Specify the user’s Internet password. Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-9

To edit database ACLs After you edit the Server document and create Person documents, edit the database ACL of each database to which you want to give users access. For more information on setting up a database ACL, see the chapter “Controlling User Access to Domino Databases.” Customizing the HTML log-in form Note The terms log-in and sign-in are used interchangeably. Domino provides a default HTML log-in form to allow a user to enter a name and password, and then use that name and password for the entire user session. The Web browser sends the user’s name and password to the server using the server’s character set. Therefore, a user can enter a name and password in a character set other than ASCII or Latin-1. The available set of characters to use for user name are different for basic authentication and session-based authentication.
Authentication type User name Password

Basic authentication Any printable characters in Any printable characters in ISO-8859-1 US-ASCII HTTP session authentication Any printable characters in Any printable characters in Unicode US-ASCII

This form is created and configured in the Domino Web Server Configuration database (DOMCFG.NSF). You can customize the form to contain additional information. To do this, the Domino Web server must be set up. For more information on setting up the Web server, see the chapter “Setting Up the Domino Web Server.” To create and use a custom sign-in form, you must complete these procedures: • • • Create the Domino Web Server Configuration database. If you do not create the database, Domino uses a generic log-in form. Create a custom form. Specify the custom form as the sign-in form. If the Domino Web Server Configuration database exists on the Web server but you have not created and specified a custom sign-in form, Domino uses the form $$LoginUserForm.

42-10 Administering the Domino System, Volume 2

Security

To create the Domino Web Server Configuration database (DOMCFG.NSF) 1. Open the Notes client and choose File - Database - New. 2. Enter the name of the Web server in the Server field. 3. Select the Domino Web Server Configuration template (DOMCFG5.NTF). 4. Enter a title for the database and name the database DOMCFG.NSF. Note The name of the database is not optional, because the Web server has this name incorporated into its code. The name of the database must be DOMCFG.NSF. 5. Click OK. 6. Add an entry named Anonymous to the database ACL, and give the entry Reader access. To create a custom form The simplest way to create a custom log-in form is to modify a copy of $$LoginUserForm, the example log-in form provided in the Domino Configuration database. You can also create a new log-in form. You must have the Domino Designer 6 client to create and edit forms. 1. In the Domino Designer client, open the Domino Configuration database (DOMCFG.NSF). 2. Choose View - Design. 3. Do one of the following: • To create a custom form using $$LoginUserForm, make a copy of $$LoginUserForm, then double-click the copy to open it. (You can rename the copy if necessary — for example, CustomLoginForm.) • Click New Form to create a new form. 4. When you finish designing the custom form, save and close it. To specify the custom form as the log-in form 1. In the Notes client, open the Domino Configuration database (DOMCFG.NSF) and open the Sign In Form Mappings view. 2. Click Add Mapping. 3. Under Site Information, choose one: • All Web Sites/Entire Server — to use the custom log-in form for all Web Sites on the server, or for the entire Web server. • Specific Web Sites/Virtual Servers — to map the custom log-in form to specific Web Site documents or Virtual Servers. If you choose this option, a new field appears, in which you specify the IP addresses of the Web Site documents or Virtual Servers
Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-11

4. (Optional) Enter a comment. 5. Enter the file name of the database that contains the custom form. This should be DOMCFG.NSF unless you store the custom form in a different database. 6. Enter the name of the custom log-in form. 7. Save and close the document. Configuring error messages You can enable session-based Web authentication to return error messages for log-in failures and session time-outs. This is accomplished by configuring two fields on your custom login form — the reasontext and reasontype fields. DOMCFG.NTF includes these two fields in the default form provided, $$LoginUserForm. (To obtain the changes, you must refresh or replace the design of DOMCFG.NSF with the most current DOMCFG5.NTF). The four cases that cause the Login form to appear are encoded in the field “reasontype” and include: • • Prompt for the user to log in, at which no error message will display. “User Name, you are not authorized to access application.nsf. Please sign in with a name which has sufficient access rights.” The user is authenticated with correct credentials for the server but is not authorized to the database or file, for example. “You provided an Invalid username or password. Please sign in again.” The user has given an incorrect name or password. “Your connection has expired. Please sign in again.” This occurs when the browser has not sent a request to the server in the given amount of time as configured in the server document (default=30 minutes). If the session times out, they will lose what hasn’t been saved. Administrators should lengthen the server’s session timeout, if this occurs frequently, to the length of a workday.

• •

Multi-server session-based name-and-password authentication for Web users (single sign-on)
Multi-server session-based authentication, also known as single sign-on (SSO), allows Web users to log in once to a Domino or WebSphere server, and then access any other Domino or WebSphere servers in the same DNS domain that are enabled for single sign-on (SSO) without having to log in again.

42-12 Administering the Domino System, Volume 2

Security

User Web browsers must have cookies enabled since the authentication token that is generated by the server is sent to the browser in a cookie. You set this up by doing one of the following: • Creating a domain-wide configuration document — the Web SSO Configuration document — in the Domino Directory. (You can have multiple Web SSO Configuration documents in a Domino Domain or directory.) Enabling the “Multi-server” option for session-based authentication in the Web Site or in the Server document.

You can enable single sign-on across multiple Domino domains. See the topic “Setting up the Web SSO Configuration document for more than one Domino domain” later in this chapter.

Checklist for enabling single sign-on
The SSO feature makes logging in and using multiple servers in a mixed environment easier for users. Use the following list to configure your Domino environment to ensure that your SSO configuration is successful. General issues • URLs issued to servers configured for single sign-on must specify the full DNS server name, not the host name or IP address. For browsers to be able to send cookies to a group of servers, the DNS domain must be included in the cookie, and the DNS domain in the cookie must match the server URL. This is why cookies cannot be used across TCP/IP domains. • Clustered servers must have the full DNS server name in the host name field of the Web Site or Server document. This enables the Internet Cluster Manager (ICM) to redirect to cluster members using SSO. If the DNS server host name is not there, ICM will redirect URLs to clustered Web servers with only the TCP/IP host name, by default, and will not be able to send the cookie because the DNS domain is not included in the URL.

WebSphere issues • WebSphere and Domino should both be configured for the same LDAP directory. The authentication token used for SSO stores the full Distinguished Name of the user (DN) — for example, cn=john smith,ou=sales, o=ibm, c=us. To set up LDAP for SSO, set up Directory Assistance in Domino and configure it to point to an LDAP server that the WebSphere server uses. Or, load LDAP on the Domino Directory and configure WebSphere to use the Domino LDAP server.
Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-13

If the group of servers participating in single sign-on includes WebSphere servers that use a Domino LDAP directory, users with flat names in that directory cannot use SSO (if the participating servers are all Domino, then SSO will work with flat user names).

Creating a Web SSO configuration document
The Web SSO configuration document is a domain-wide configuration document stored in the Domino Directory. This document, which should be replicated to all servers participating in the single sign-on domain, is encrypted for participating servers and administrators, and contains a shared secret key used by servers for authenticating user credentials. To create a Web SSO configuration document if you are using Internet Sites You should have already created a Web Site document, and enabled the use of Internet Site documents in the Server document. Also be sure that your client location document has the home/mail server set to a server in the same domain as the servers participating in SSO. This ensures that all public keys for participating server can be found when the SSO document is encrypted. 1. In the Domino Administrator, click Files, and open the server’s Address Book (NAMES.NSF). 2. Select the Internet Sites view. 3. Click Create Web SSO Configuration. 4. In the document, click Keys. 5. Initialize the Web SSO Configuration with the shared secret key in one of two ways: • Choose Domino only (no WebSphere servers participating in single sign-on), and then select “Create Domino SSO Key.” • Choose Domino and WebSphere (single sign-on with WebSphere), and then do the following: a. Select “Import WebSphere LTPA Keys.” b. Browse and select the WebSphere LTPA export file. (See WebSphere documentation for details about generating ltpatoken keys). c. Enter the password (specified when generating the keys in WebSphere). The document is updated to reflect the information in the export file.

42-14 Administering the Domino System, Volume 2

Security

6. Complete the rest of the document as follows:
Field Configuration Name Action Enter the name of the SSO configuration. Note If the single sign-on configuration includes both Domino 6 and Release 5.0x servers, the Configuration Name must be LtpaToken, as Release 5.0x servers only work with this configuration name. (Required) Enter the name of the organization. This must match the organization name for the corresponding Web site. The SSO document will then appear in the Internet sites view, along with the Web Sites documents. (Required) Enter the DNS domain (for example — lotus.com) for which the tokens will be generated. The servers enabled for single sign-on must all belong to the same DNS domain. Enter the names of the servers that will be participating in single sign-on (for example — server1/acme, server2/acme). This document will be encrypted for the creator of the document, the members of the Owners and Administrators fields, and the servers specified in the Domino Server Names field. Groups, wildcards, and the names of WebSphere servers are not allowed in this field. Only Domino servers can be listed as participating servers in the Server Names field. Note There is a 64K-size limit on this field. An error message appears when the limit is reached, such as when the names of several hundreds of servers are entered. It is recommended that you create more than one Web SSO Document if this limit is reached. Expiration (minutes) Specify the time period, in minutes, for which the token will be valid. This time period begins at the time the token is issued. The token is valid for only the number of minutes specified; it does not expire based on inactivity. Default is 30 minutes.

Organization Name

DNS Domain

Domino Server Names

7. Save the Web SSO Configuration document. A message on the status bar indicates the number of servers/people for whom the document was encrypted. The document(s) will appear in the Internet Sites view.

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-15

To create a Web SSO configuration document if you are using the Web Server Configurations view Use this procedure to create a Web SSO configuration document if your server is a Release 5.0x server, or if you are using Domino 6 but you do not use Web Site documents to manage your Web sites. 1. In the Domino Administrator, click Files, and open the server’s Address Book (NAMES.NSF). 2. Select the Servers view. 3. Click Create Web SSO Configuration. 4. In the Web SSO Configuration document, click Keys. 5. Initialize the Web SSO Configuration with the shared secret key in one of two ways: • Choose Domino only (no WebSphere servers participating in single sign-on), and then select “Create Domino SSO Key.” • Choose Domino and WebSphere (single sign-on with WebSphere), and then do the following: a. Select “Import WebSphere LTPA Keys.” b. Browse and select the WebSphere LTPA export file. (See WebSphere documentation for details about generating ltpatoken keys). c. Enter the password (specified when generating the keys in WebSphere). The document is updated to reflect the information in the export file. 6. Complete the rest of the document as follows:
Field Action Configuration Enter the name of the SSO configuration. Name Note If the single sign-on configuration includes both Domino 6 and Release 5.0x servers, the Configuration Name must be LtpaToken, as Release 5.0x servers only work with this configuration name. Organization Name DNS Domain Leave this field blank, and this document will appear in the Web Configurations view. (Required) Enter the DNS domain (for example, lotus.com) for which the tokens will be generated. The servers enabled for single sign-on must all belong to the same DNS domain. continued

42-16 Administering the Domino System, Volume 2

Security

Field

Action

Domino Server Enter the names of the servers that will be participating in single sign-on (for example — server1/acme, Names server2/acme). This document will be encrypted for the creator of the document, the members of the Owners and Administrators fields, and the servers specified in the Domino Server Names field. Note Groups, wildcards, and the names of WebSphere servers are not allowed in this field. Only Domino Servers can be listed as participating servers in the Server Names field. Expiration (minutes) Specify the time period, in minutes, for which the token will be valid. This time period begins at the time the token is issued. The token is valid for only the number of minutes specified; it does not expire based on inactivity. Default is 30 minutes.

7. Save the Web SSO Configuration document. A message on the status bar indicates the number of servers/people for whom the document was encrypted. The document(s) will appear in the Internet Sites View. Note If you receive messages on the client indicating that a particular key was not found for encrypting the document, you may have to change your client’s location document to point to a different mail/directory server that will have all the public keys included in server and person documents.

Enabling single sign-on and basic authentication
This procedure creates single sign-on cookies for your server that can be used successfully on other participating servers. To enable single sign-on and basic authentication for a Web Site Use this procedure to enable single sign-on for Domino 6 servers configured with Web Site documents. 1. In the Domino Administrator, click Configuration - Web - Internet Sites. 2. Open the Web Site document for which you want to enable single sign-on. 3. Click Domino Web Engine. 4. In Session authentication, select “Multiple Servers (SSO).” 5. In the Web SSO Configuration field, select the Web SSO Configuration for this Web Site from the drop-down list.

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-17

6. Click Security. For both TCP and SSL authentication, enable Name & Password. 7. Save and close the Web Site document. 8. At the server console, start the HTTP process by typing:
load HTTP

If the HTTP process is already running, type:
tell HTTP restart

Note If something is wrong with the configuration, the browser will receive an Error 500 message stating that single sign-on is not configured. To enable single sign-on and basic authentication in the Server document Use this procedure to enable single sign-on for Domino Release 5.0x servers, or for Domino 6 servers not configured with Web Site documents. 1. Open the Server document. 2. Click Ports - Internet Ports - Web, and enable Name-and-password authentication for the Web (HTTP/HTTPS) port. 3. Click Internet Protocols - Domino Web Engine, and select Multiple Servers (SSO) in the Session authentication field. Note The “Idle session timeout” and “Maximum active sessions” fields will be disabled. 4. In the Web SSO Configuration field, select the Web SSO Configuration for this server from the drop-down list. 5. Save and close the Server document.

Setting up the Web SSO Configuration document for more than one Domino domain
This procedure lets you enable servers in other domains for SSO with servers in your current domain, by setting up both domains to use the same key information. Two conditions must exist in order to do this: • You must be a registered Notes user and your server must be a registered server. This gives you and the server the rights to decrypt the Web SSO Configuration document in your current domain, and the right to create documents in the Domino Directory for the new domain.

42-18 Administering the Domino System, Volume 2

Security

The server document and the administrator’s person document must exist in the domain for which you will be creating the Web SSO Configuration, as the public keys that are used for encryption and decryption are stored in each registered person and server document.

To set up the Web SSO Configuration document for more than one Domino domain 1. Copy the Web SSO Configuration document from the Domino Directory in which it was created, and paste it into the Domino Directory in the new domain. 2. Open the Web SSO Configuration document for the new domain and edit the “Participating Domino Servers” field to include only those servers with server documents in the new domain that will be enabled for single sign-on. 3. The client must be able to find server documents for the participating single sign-on servers. Make sure that the home server specified in your client’s location document is pointing to a server in the same domain as those servers participating in single sign-on, so that lookups will be able to find the public keys of the servers. If the home server cannot find participating servers, then the SSO document cannot be encrypted and SSO will fail. 4. Save the document. It is encrypted for the participating servers in the new domain, and should enable those servers in the new domain to participate in single sign-on with servers in the current domain.

Controlling the level of authentication for Internet clients
You can select the level of restriction Domino uses when authenticating users in Domino Directories and LDAP directories. This applies to all Internet protocols (HTTP, LDAP, IMAP, POP3). Using this setting makes servers less vulnerable to security attacks by refining how Domino searches for names and authenticates Internet clients. Domino also uses this setting when a Java applet hosted on a Domino server authenticates users with the Domino IIOP protocol. Fewer name variations with higher security The option “Fewer name variations with higher security” is the default setting and is recommended for tighter security. This authentication method is less vulnerable to attacks because a single authentication attempt does not produce as many matches, lessening the likelihood that

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-19

a guessed password matches. It requires users to enter only the following in the name-and-password dialog box in a Web browser or other Internet client:
Domino Directory authentication Full hierarchical name Common name or Common name with CN= prefix Not applicable LDAP Directory authentication DN CN or CN with CN=prefix UID or UID with UID= prefix

Alias name (a name listed in the User name field Not applicable of the Person document, excluding the first name listed in the field) Internet address (user’s e-mail address as listed Mail in the Internet address field in the user’s Person document)

More name variations with lower security Domino tries to authenticate users based on the name and password entered. This authentication method can be vulnerable to hackers who guess names and passwords in an attempt to use a legitimate user account to access a server. This option allows users to enter any of the following in the name and password dialog box in a Web browser:
Domino Directory authentication Last name First name Common name or Common name with cn=prefix Full hierarchical name (canonical) Full hierarchical name (abbreviated) Short name LDAP Directory authentication Surname Givenname Common name (CN) or CN with CN=prefix DN DN UID or UID with UID=prefix

Alias name (a name listed in the User name field Not applicable of the Person document, excluding the first name listed in the field) Soundex number Not applicable Internet address (user’s e-mail address as listed Mail in the Internet address field in the user’s Person document)

42-20 Administering the Domino System, Volume 2

Security

To select the level of authentication for Internet clients 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click Security. 3. In the Internet Access section, choose one of the following in the Internet Authentication field: • Fewer name variations with higher security (default). • More name variations with lower security. 4. Save and close the document. See the topic “Examples of names allowed for Internet client authentication” later in this chapter. Note The Domino Web Server Application Programming Interface (DSAPI) is a C API tool that lets you write your own extensions to the Domino Web server. These extensions, or filters, let you customize the authentication of Web users. For more information on DSAPI and filters, see the current Lotus C API Toolkit for Domino and Notes, which is available at www.lotus.com/techzone.

Examples of names allowed for Internet client authentication
More name variations with lower security Using the More name variations authentication level, Alan Jones/Sales/East/Acme can enter the following names when using a browser to authenticate with a Domino Directory:
Example Alan Jones Alan Jones Ajones Alan Jones/Sales/East/Acme/US Description Common name First name Last name Short name Full hierarchical name (abbreviated)

cn=Alan Jones/ou=East/ou=Sales/o=Acme/c=us Full hierarchical name (canonical) cn=Alan Jones alan_jones@acme.com Common name with CN=prefix Internet (e-mail) address

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-21

If you want to authenticate Alan in an LDAP Directory, he can use a browser to enter the following names:
Example Alan Jones Alan Jones Ajones Description Common name Givenname Surname UID

cn=Alan Jones, cn=recipients, ou=Sales, Full hierarchical name (canonical) ou=East, o=Acme, c=us (valid for a Microsoft Exchange server) cn=Alan Jones (valid for Domino Directory) Common name with CN=prefix

uid=ajones, ou=Sales, ou=East, o=Acme, Full hierarchical name (canonical) c=us (valid for a Netscape Directory Server) uid=ajones (valid for Netscape Directory UID with UID=prefix Server) Alan Jones/Sales/East/Acme/US alan_jones@acme.com Full hierarchical name (abbreviated) LDAP mail attribute

Fewer name variations with higher security Using the Fewer name variations authentication level, Alan Jones/Sales/East/Acme can enter only the following names when using a browser to authenticate with a Domino Directory:
Example Alan Jones/Sales/East/Acme CN=Alan Jones Alan Jones cn=Alan Jones/ou=East/ou=Sales/o= Acme/c=us alan_jones@acme.com Description Full hierarchical name (abbreviated) Common name with CN= prefix Common name Full hierarchical name (canonical) Internet (e-mail) address

42-22 Administering the Domino System, Volume 2

Security

If you want to authenticate Alan in an LDAP Directory, he can use a browser to enter the following names:
Example AJones Alan Jones Description UID CN

cn=Alan Jones, cn=recipients, ou=Sales, ou=East, DN o=Acme, c=us (valid for a Microsoft Exchange server) cn=Alan Jones (valid for a Domino Directory) uid=ajones, ou=Sales, ou=East, o=Acme, c=us (valid for a Netscape Directory Server) uid=Ajones (valid for a Netscape Directory Server) alan_jones@acme.com CN with CN=prefix DN UID with UID= prefix LDAP mail attribute

Authenticating Internet name-and-password clients in secondary Domino and LDAP directories
When an Internet client authenticates with a server, by default the server checks the primary Domino Directory to see if it can find a Person document with a name and password that match those entered by the Internet client. If your organization uses a secondary Domino Directory and/or an LDAP directory to verify Internet clients who use name-and-password authentication, you can set up Domino to check those additional directories. To do so, you set up the secondary Domino Directories and LDAP directories as trusted domains in the Directory Assistance database. When you mark domains as trusted, Domino first searches the primary Domino Directory for the user name and password and then searches the trusted secondary Domino Directories and LDAP directories. When you set up directory assistance, you specify the order in which Domino searches the secondary directories. The hierarchical name returned by the Domino Directory or LDAP directory is checked against the trusted rule in the Directory Assistance database to verify that the organization and organizational units match the specified rule. For example, if the user name returned is Dave Lawson/Acme, the Directory Assistance document must include the rule */Acme. Searching multiple directories is also available for authenticating users with SSL client authentication. Note For Domino R5.x and earlier, searching multiple directories is only used by the HTTP protocol and not the other Internet protocols.
Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-23

Managing Internet passwords
To manage the Internet passwords that you assign to users who have person documents in the Domino Directory, use a security settings policy document. You can manage Internet password quality and length, as well as allow users to change their Internet passwords using a Web browser, and control expiration period and change intervals. You can force users to change their Internet password on the next login through a setting in the Person document. Note In order to allow users to change their Internet passwords through a browser, you must have session authentication enabled for your server. You can also synchronize a user Internet password stored in the Person record in the Domino Directory with the user’s Notes password. This means that users can use the same password to log in to a Domino server through the Notes client and a Web browser. You can synchronize Notes and Internet passwords for individual users during user registration, or you can enable Notes-Internet password synchronization for multiple users on a server through the use of a security settings policy document. When a user changes their Notes password, the Internet password is eventually changed, as well. For more information on using a security settings policy document to manage Notes and Internet passwords, see the chapter “Using Policies.” For more information on changing password settings in the Person document, see the chapter “Protecting and Managing Notes IDs.”

Providing additional security for Internet passwords
When you enter an Internet password and save the Person document, Domino automatically one-way encrypts the Internet password field. To improve password security for users who access Domino 4.6 or higher servers, use the more secure password format. You can upgrade the password format for Person documents that already exist or automatically use the more secure password format for all Person documents that you create. For existing Person documents 1. From the Domino Administrator, click People & Groups, and select the Person documents that you want to upgrade to a more secure password format. 2. Choose Actions - Upgrade to More Secure Internet Password Format. 3. Click Yes.
42-24 Administering the Domino System, Volume 2

Security

For new Person documents 1. From the Domino Administrator, click Configuration, and select All Server Documents. 2. Choose Actions - Edit Directory Profile. 3. Select Yes in the “Use more secure Internet passwords” field. 4. Save and close the document.

Anonymous Internet/intranet access
When you set up anonymous access, Internet/intranet clients can access servers without identifying themselves. Domino does not record these clients’ database activity — for example, in the log file and in the User Activity dialog box. With anonymous access, you never know who is accessing databases on the server. Therefore, you cannot use the client’s identity — that is, the client’s name and password — to control access to databases and design elements. Use anonymous access when you do not need to know who is accessing the database and/or when you do not need to control access based on client identity. You can use anonymous access with TCP/IP and/or SSL on any server that runs LDAP, HTTP, SMTP, or IIOP. For each Internet protocol enabled on the server, you can specify the method of security. For example, you can enable SSL for HTTP connections, but require name-and-password authentication for LDAP connections that use TCP/IP. In addition to using anonymous access, you can enable name-and-password authentication and SSL client authentication. Then users can use any authentication method to connect to the server. For example, if the user has an SSL client certificate, the user can access the server using SSL; whereas a user who does not have an SSL client certificate can access the server anonymously. For more information on how Domino validates and authenticates users when anonymous, SSL client authentication, and name-and-password authentication are set up on a server, see the topic “Validation and authentication for Internet/intranet clients” later in this chapter.

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-25

Setting up Internet/intranet clients for anonymous access
To set up Internet/intranet clients for anonymous access, you either set up the Internet Site or the server for anonymous access, and then set up database ACLs to include the entry “Anonymous.” The anonymous setting in the Internet Site document (or Server document) overrides individual database ACLs for anonymous users — for example, if the database ACL includes an Anonymous entry but the setting in the Internet Site document does not allow anonymous access to the server, clients do not have anonymous access. If you do not allow anonymous access and a user tries to access the server anonymously, the user is prompted to authenticate. Tip For strategic databases on the Domino server — such as the Domino Directory — set Anonymous to No Access. To enable anonymous access for Internet/intranet clients in Internet Site documents 1. From the Domino Administrator, click Configuration - Web - Internet Sites. 2. In the Internet Sites view, select the Internet Site document for which you want to enable anonymous access. Note You cannot enable anonymous access for IMAP and POP3 Internet Site documents. 3. In the Internet Site document, click Security. • If you want to allow clients to use anonymous access when they connect using TCP, select Yes in the Anonymous field in the TCP Authentication section. • If you set up SSL on the server and you want to allow clients to use anonymous access when they connect using SSL, select Yes in the Anonymous field in the SSL Authentication section. 4. Save and close the document. To enable anonymous access for Internet/intranet clients in the Server document 1. From the Domino Administrator, click Configuration, and open the Server document. 2. Click Ports - Internet Ports. This displays four tabs: Web, Directory, Mail, and IIOP. Each tab lists protocols appropriate for its name — for example, the Web tab lists HTTP/HTTPS and the Mail tab lists IMAP, POP, and SMTP.

42-26 Administering the Domino System, Volume 2

Security

3. Click the tab that lists the protocol for which you want to allow anonymous access. For each protocol, do the following: • If you want to allow clients anonymous access when they connect using TCP/IP, select Yes in the Anonymous field in the TCP/IP section. • If you set up SSL on the server and you want to allow clients anonymous access when they connect using SSL, select Yes in the Anonymous field in the SSL section. 4. Save and close the document. 5. Restart the Internet protocol that you modified. To edit database ACLs for anonymous access In the ACL of each database on the server for which you want to enable anonymous access, do the following: 1. Create an entry named Anonymous. If you don’t add Anonymous as an entry in the ACL, users and servers who access the server anonymously get -Default- access. 2. Assign the appropriate access level — typically Reader access. 3. Leave user type set to Unspecified. For more information on database ACLs, see the chapter “Controlling User Access to Domino Databases.” For information on setting up SSL on a server, see the chapter “Setting Up SSL on a Domino Server.”

Validation and authentication for Internet/intranet clients
After you set up name-and-password access and create Person documents for Internet/intranet users, Domino authenticates users when: • • They attempt to do something for which access is restricted. Anonymous access is not allowed on the server.

For example, when a user tries to open a database that has an ACL with No Access as the -Default-, Domino challenges the user for a valid user name and password. Authentication succeeds only if the user provides a name and password that matches the name and password stored in the user’s Person document and if the database ACL gives access to that user. Anonymous users are not authenticated.

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-27

You can use name-and-password and anonymous access with TCP/IP and SSL. Name-and-password and anonymous access with TCP/IP are described below. This section also applies to Web clients who are accessing a Domino Web server for which session authentication has been enabled. Note The Domino Web Server Application Programming Interface (DSAPI) is a C API that you use to write extensions to the Domino Web server. Using these extensions, or filters, you can customize the authentication of Web users. For more information on DSAPI, see the Lotus C API Toolkit for Domino and Notes. The toolkit is available at www.lotus.com/techzone.

How validation and authentication works
This example describes how a client (Andrew) uses TCP/IP to connect to a server (Mail-E). 1. Andrew tries to access a database on Mail-E. 2. The server checks the Internet Site document (or Server document) to determine if anonymous access is enabled for TCP/IP. If it is, then: a. The server checks the database ACL for an entry named Anonymous. If Anonymous exists and the level of access for Anonymous is Reader or higher, then Andrew will access the database anonymously. b. If the ACL does not contain an entry named Anonymous, the server checks the -Default- access in the database ACL. If the -Default- access is Reader or higher, Andrew accesses the database anonymously using the -Default- access level. 3. If anonymous access is disabled for the protocol or if the database ACL does not allow anonymous access, then the server checks the Internet Site (or Server document) to determine if name-and-password access is enabled for TCP/IP. If name-and-password access is enabled, then: a. The server prompts Andrew for his user name and password. b. The server looks up the user name that Andrew entered in the browser. The server uses either “More name variations with lower security” or “Fewer name variations” with higher security as the lookup mechanism to search all directories for the name entered.

42-28 Administering the Domino System, Volume 2

Security

c. If a match is found for the user name Andrew entered, and the password that Andrew entered matches the password in the Internet password field of his Person document, then Andrew will be authenticated. The server checks the primary Domino Directory for the Person document. The server also checks secondary Domino Directories and LDAP directories if it is configured to search secondary Domino Directories and LDAP directories. Note When Domino authenticates an Internet user, it uses the “distinguished name,” which is the first name that appears in the Full Name field of a Person document. This name should be used in entries for groups, delegated server administration, database ACLs, and file protection documents. d. Next, the server compiles a “grouplist,” which contains Andrew’s distinguished name, plus any wildcard entries and any groups of which he is a member on that server. e. The server then checks the database ACL to determine if Andrew’s name is listed explicitly on the ACL, or if any of the grouplist entries for his name appear in the ACL. f. If Andrew’s distinguished name, or the name of any group of which is a member, matches an entry in the ACL, then Andrew gets access to the database using the access level specified for that entry in the ACL. Otherwise, he is denied access.

Setting Up Name-and-Password and Anonymous Access to Domino Servers 42-29

Security

Chapter 43 Encryption and Electronic Signatures
This chapter describes how to use encryption to secure messages and how to use digital signatures to verify the author of the message.

Encryption
Encryption protects data from unauthorized access. Using Notes and Domino, you can encrypt: • Messages sent to other users. Then an unauthorized user cannot read the message while it is in transit. You can also encrypt saved and incoming messages. Network ports. Encrypting information sent between a Notes workstation and a Domino server, or between two Domino servers, prevents unauthorized users from reading the data while it is in transit. SSL transactions. You can use SSL to encrypt information sent between an Internet client, such as a Notes client, and an Internet server, to prevent unauthorized users from reading the data while it is in transit. Fields, documents, and databases. Application developers can encrypt fields within a document, an entire document, and local databases. Then only the specified users can read the information.

For information on SSL encryption, see the chapter “Setting Up SSL on a Domino Server.” For information on field, document, and database encryption, see the book Application Development with Domino Designer.

Public and private keys
For all types of encryption except network port encryption, Domino uses public and private keys so that data encrypted by one of the keys can be decrypted only by the other. The public and private keys are mathematically related and uniquely identify the user. Both are stored in the ID file. Within the ID file, the public key is stored in a certificate, but the private key is stored separately from the certificate. The certificate
43-1

containing the public key is also stored in the Domino Directory, where it is available to other users. Domino uses two types of public and private keys — Notes and Internet. You use the Notes public key to encrypt fields, documents, databases, and messages sent to other Notes users, while the Notes private key is used for decryption. Similarly, you use the Internet public key for S/MIME encryption and the Internet private key for S/MIME decryption. For both Notes and Internet key pairs, electronic signatures are created with private keys and verified with public keys. You can use one set of Internet public and private keys or you can set up Notes to use a set of Internet keys for S/MIME signatures and SSL and another set for S/MIME encryption. For information on dual Internet certificates, see the chapter “Setting Up Clients for S/MIME and SSL.” When you register a user, Domino automatically creates a Notes certificate, which contains the user’s public keys, and adds it to the ID file and the Domino Directory. The private key is created and stored in the ID file. You can also create Internet public and private keys after user registration. Domino stores Internet certificates, which contain public keys, in the ID file and also in the Domino Directory. The Internet private key is stored in the ID file, separately from the certificate. To create Notes public and private keys, Domino uses the dual-key RSA Cryptosystem and the RC2 and RC4 algorithms for encryption. To create the Internet public key, Domino uses the x.509 certificate format, which is an industry-standard format that many applications, including Domino, understand. Both the Notes client and Domino server support 1024-bit RSA key and 128-bit symmetric key for S/MIME and SSL. The Notes proprietary protocols use a 630-bit key for key exchange, and a 64-bit symmetric key.

Encryption strength
All Notes IDs contain two public/private key pairs. Prior to 5.0.4, key lengths were restricted for the purposes of encrypting data, but not for authentication or signing. Anything over 512-bit RSA key and 56-bit symmetric key was considered strong encryption and was not allowed for export by the U.S. Government. Customers were required to order and choose among kits of different cryptographic strengths. With the relaxation of US government regulations on the export of cryptography, the Domino server and the Domino Administrator, Domino Designer, and Lotus Notes client products have consolidated all previous encryption strengths — North American, International, and
43-2 Administering the Domino System, Volume 2

Security

France — into one strong encryption level resulting in a single “Global” release of the products. The Global release adopts the encryption characteristics previously known as North American. Strong encryption in Global products can be used worldwide, except in countries whose import laws prohibit it, or except in those countries to which the export of goods and services is prohibited by the U.S. government. Customers are no longer required to order Notes software according to cryptographic strength. When you upgrade to a Global release of Domino and Notes, stronger cryptography will be used without a requirement to reissue existing IDs. These changes are seamless to users as well as administrators. When two different versions of software are communicating, the encryption negotiation will result in a step-down to the weaker level. Therefore, the full benefits of stronger encryption will only be realized when all software has been upgraded to the Global (release 5.0.4 and later) level. However, any mixed versions of the software will interoperate. The “Register New User” dialog box still offers a choice between North American and International IDs. It was left this way because administrators often use the North American or International distinction for administration purposes, or there may be older versions of the software still in use in some companies. In addition, countries have their own import rules. Preserving this distinction will allow Lotus to respond to specific country changes, if required. Note These regulations pertain only to export from the United States. For other countries with import regulations, customers need to check the requirements of the specific country. While Lotus takes all steps to acquiesce with governmental encryption regulations worldwide, Lotus recommends that customers familiarize themselves with local encryption regulations to remain in compliance. Interoperability issues • Support for ID types. Both North American and International ID types continue to be supported for the Global release. This is for backward compatibility with pre-5.0.4 clients. Lotus Notes users can keep their existing International IDs if the Global version of the software is installed. The Global version will automatically allow the use of stronger encryption. Browser users can keep their existing key ring, but users must follow the manufacturer’s recommendations for upgrading the browser to stronger encryption. • Interoperability with post-5.0.4 releases. If your organization’s clients and servers are all running release 5.0.4 or later, it makes no difference whether you create North American or International IDs. Both types of ID will work the same way.
Encryption and Electronic Signatures 43-3

Interoperability with pre-5.0.4 releases. Lotus Notes users, as well as Domino servers which have been upgraded to release 5.0.4 and later, can authenticate and continue day-to-day operations securely with clients and servers running on earlier releases of software. However, if your organization has clients or servers running releases earlier than Notes and Domino 5.0.4, you should continue to create the same types of IDs you created with the earlier versions. International versions of releases prior to 5.0.4 do not allow users to switch to North American IDs, so when registering new international users, you shouldn’t create only North American IDs. Similarly, North American versions of earlier releases use weaker cryptography when running with International IDs, so you shouldn’t create only International IDs.

The best strategy for deciding between North American and International IDs is to continue using the decision process that was in place for earlier releases of Notes and Domino. Eventually, as you upgrade the Notes clients and Domino servers, the decision will not matter.

Mail encryption
Mail encryption protects messages from unauthorized access. Only the body of a mail message is encrypted; the header information — for example, the To, From, and Subject fields — is not. Notes users can encrypt mail sent to other Notes users or to users of mail applications that support S/MIME — for example, Microsoft Outlook Express and Netscape Communicator. Users can use Notes mail encryption to encrypt mail sent to other Notes users, encrypt mail received from other Notes users, or encrypt all documents saved in a mail database. Notes uses the recipient’s public key, which is stored in the sender’s Personal Address Book or in the Domino Directory, to encrypt outgoing and saved mail. In general, mail sent to users in a foreign domain cannot be encrypted. However, if the recipient of the mail uses Notes and the sender has access to the recipient’s public key, the sender can encrypt the mail message. The recipient’s public key can be stored in the Domino Directory, in an LDAP directory to which the sender has access, or in the sender’s Personal Address Book. Notes users can also use S/MIME to encrypt mail sent to recipients who use mail applications that support S/MIME. Senders must have the recipient’s public key in order to encrypt the message for S/MIME.
43-4 Administering the Domino System, Volume 2

Security

The recipient’s public key is stored in an Internet certificate in either a Domino Directory or LDAP directory to which the sender has access or in the sender’s Personal Address Book. The sender must also have a cross-certificate that indicates to Notes that the recipient’s public key can be trusted. For information on setting up a Notes client for S/MIME encryption, see the chapter “Setting Up Clients for S/MIME and SSL.” Encrypting a message — with either Notes mail encryption or S/MIME encryption — does not affect the speed at which the message is routed from sender to recipient. However, encryption does increase the time required to send and to open a message. The extra time is required because the message must be encrypted at the beginning of the transmission and decrypted each time the recipient opens it. The time required to send and open a message is based on the size of the message and the number of bitmaps and other graphics, objects, and attachments in the message. In most cases, the delay is not noticeable.

How outgoing Notes mail encryption works
1. The sender sends an outgoing message and selects the Encrypt option. 2. Notes generates a random encryption key and encrypts the message with it. 3. Notes encrypts the random encryption key with the recipient’s public key and appends the new key to the message. The recipient’s public key must be stored in either a Domino Directory or LDAP directory that a user can access or in the sender’s Personal Address Book. 4. If the encrypted message is addressed to multiple recipients, the message is encrypted only once with one random key, and the random key is encrypted using the public key of each recipient. 5. When the recipient attempts to open the encrypted message, the user’s mail application attempts to decrypt the random key, using the recipient’s private key. If this is successful, the random key decrypts the message. 6. If decryption is successful, the recipient can read the message. If decryption is unsuccessful, the user receives a message indicating that the decryption failed and the mail application does not allow the user to access the message.

Encryption and Electronic Signatures 43-5

How outgoing S/MIME mail encryption works
1. The sender sends an outgoing message and selects to encrypt it. (The exact option to do this depends on the mail application used.) 2. The sender’s mail application (Notes or another S/MIME-compliant mail program) generates a random encryption key and encrypts the message with it. 3. The sender’s mail application looks for the recipient’s public key. For S/MIME mail sent from Notes, the recipient’s Internet certificate must be stored in the sender’s Personal Address Book or a Domino Directory or LDAP directory to which the sender has access. a. If a certificate is found, Notes looks for a cross-certificate in the sender’s Personal Address Book to validate the Internet certificate. If a cross-certificate does not exist, Notes asks whether the client wants to create a cross-certificate on demand. b. If no certificate for the recipient is found or if a cross-certificate is not created for the certificate, the sender receives a warning that encryption is not possible for this recipient. The sender is then given a choice of not sending the message or sending it unencrypted. 4. The sender’s mail application encrypts the random encryption key with the recipient’s public key and appends the encrypted key to the message. Notes uses the recipient’s public key, found in the certificate, to encrypt the message. Some recipients may have dual Internet certificates — one certificate used for encryption and the other used for signatures and SSL. If so, Notes extracts the Internet encryption certificate, and uses it to encrypt the message. 5. If the encrypted message is addressed to multiple recipients, the message is encrypted only once with one random key, and the random key is encrypted using the public key of each recipient. 6. When the recipient attempts to open the encrypted message, the user’s mail application attempts to decrypt the random key, using the recipient’s private key. If this is successful, the random key decrypts the message. 7. If decryption is successful, the recipient gains access to the message. If decryption is unsuccessful, the user receives a message indicating that the decryption failed, and the mail application does not allow the user to access the message.

43-6 Administering the Domino System, Volume 2

Security

Encrypting mail
Encrypt outgoing, incoming, and saved mail to protect messages while they are in transit and stored in mail databases on the server. Users can encrypt outgoing mail messages sent to recipients who use either Notes or S/MIME. If recipients prefer to receive mail in MIME format, then encrypted mail will be in S/MIME format. Users can encrypt incoming and saved mail only if they use Notes mail. To encrypt outgoing mail Encrypting outgoing mail ensures that only the recipient of a message can read it while the message is in transit, stored in intermediate mailboxes, or in the recipient’s mail file. Each Notes client user must encrypt outgoing mail. The administrator cannot encrypt all outgoing mail on a server. Senders control the choice of MIME format or Notes format when sending mail directly to the Internet or for messages that are addressed to Internet addresses. Mail recipients control the format of incoming mail in their user preferences. The message format determines the choice of encryption method. Notes uses S/MIME encryption for outgoing mail in the following situations: • The user selects “directly to Internet” in the “Send outgoing mail” field in the Mail tab of the current Location document. Mail messages sent from this location will use MIME format. The user selects “MIME format” in the “Format for messages addressed to Internet addresses” field in the Mail tab of the current Location document. Mail messages sent from this location to Internet addresses that cannot be found in a Personal Address Book or Domino Directory will use MIME. The user enables the field “When receiving unencrypted mail, encrypt before storing in your mail file” on the Basics tab of the user’s Person document. Mail sent to this user will use MIME. The user creates a message using a form in which the Body field in the form’s design has “Store contents as HTML and MIME” selected in Field Properties. If the recipient can accept either Notes or MIME format (or if Notes cannot find a Person document for the recipient), the message will use MIME format.

The sender of an encrypted S/MIME mail message must find an Internet certificate for each intended recipient and a cross-certificate that verifies the Internet certificate. The Internet certificate can be stored in the Domino Directory, an LDAP directory that is accessible to the sender, or
Encryption and Electronic Signatures 43-7

in the sender’s Personal Address Book. The cross-certificate must be stored in the sender’s Personal Address Book. If a Notes recipient’s Internet certificate is not available to the sender, Notes attempts to use the recipient’s Notes public key (if available) to encrypt the message. Some recipients may have dual Internet certificates, meaning one certificate is for encryption and the other is for signatures and SSL. If the recipient uses dual certificates, Notes extracts the Internet encryption certificate and uses it to encrypt the message. The sender of an encrypted Notes mail message must have the public key for each intended recipient. The public key can be stored in the Domino Directory, in an LDAP directory that is accessible to the sender, or in the sender’s Personal Address Book. For information on encrypting outgoing mail, see Lotus Notes 6 Help. To encrypt incoming mail for a mail file If users have Editor access to their Person documents in the Domino Directory, they can encrypt all incoming mail they receive. Otherwise, the administrator must complete this procedure for them. 1. Open the user’s Person document in the Domino Directory. 2. Click Edit Person, and then click Basics. 3. In the field “When receiving unencrypted mail, encrypt before storing in your mail file,” select Yes. 4. Save the document. To encrypt saved mail Users can encrypt drafts of unsent messages and messages that they save after sending. For unsent mail, the message is encrypted only with the sender’s public key. For sent mail, the message is encrypted with the sender’s and the recipient’s public keys. Only messages saved after this option is chosen are encrypted. To encrypt previously saved messages, users must open and resave the messages. Encrypting saved mail prevents unauthorized access to messages by other users with unauthorized access to the mail server. For information on encrypting outgoing mail, see Lotus Notes 6 Help.

43-8 Administering the Domino System, Volume 2

Security

Electronic signatures
Electronic signatures are closely associated with encryption. An electronic signature verifies that the person who originated the data is the author and that no one has tampered with the data. Users can add an electronic signature to mail messages and to fields and sections of documents. A database designer controls whether or not users can sign fields and sections of a database can be signed; individual users can choose to sign mail messages. Users can sign mail messages sent to other Notes users or to users of other mail applications that support the S/MIME protocol — for example, Microsoft Outlook Express and Netscape Communicator. Domino uses the same keys used for encryption — the Notes and Internet public and private keys — for electronic signatures. You can also set up Notes to use separate keys for S/MIME signatures and encryption, by adding two Internet certificates to your Notes ID file and using one certificate for S/MIME encryption and the other for S/MIME signatures and SSL client authentication. Having dual Internet certificates lets you maintain separate public and private key pairs for encryption and electronic signatures and SSL client authentication. For information on creating signed fields and sections, see the book Application Development with Domino Designer. For information on dual Internet certificates, see the chapter “Setting Up Clients for S/MIME and SSL.”

How electronic signatures work
Notes signatures When the sender signs a message with a Notes signature, all fields of the message are signed. 1. Notes generates a “hash” of the data — that is, a number that represents the data — and then encrypts the hash with the private key of the author of the data, forming a signature. The hash is also sometimes called a message digest, and has some necessary special properties: • It is not possible to guess the original message from looking at the digest. • Even a small change in the message changes the digest in an unpredictable way, and produces a completely different value. 2. Notes attaches the signature, the signer’s public key, and the signer’s certificates to the data.
Encryption and Electronic Signatures 43-9

3. When the reader accesses the signed data, Notes verifies that the signer has a common certificate or common certificate ancestor from a certifier that the reader trusts. If so, Notes attempts to decrypt the signature using the public key that corresponds to the private key with which the data was signed. 4. If decryption is successful, Notes indicates who signed the message. If decryption is unsuccessful, Notes indicates that it cannot verify the signature. Unsuccessful decryption and comparision may indicate that the data has been tampered with. Note Certificate trust checking occurs independently of hash decryption and comparison. Decryption and comparison may succeed even if the certificate is not trusted. This might happen, for example, when a user receives mail from a user in another company and that user doesn’t have a cross-certificate. S/MIME signatures When the sender signs a message with an S/MIME signature, only the body of the message and accompanying attachments are signed. 1. Notes generates a hash of the data being signed and then encrypts the hash with the private key of the author of the data, forming a signature. 2. Notes attaches a certificate chain — that is, all certificates in the hierarchy for the certificate — and the signature to the data. 3. When the reader accesses the signed data, Notes or the mail application attempts to decrypt the signature using the public key that corresponds to the private key with which the data was signed. If successful, Notes or the application verifies that the signer has a common certificate or common certificate ancestor from a certifier that the reader trusts. Note Typically, the Notes user’s organizational certifier issues a cross-certificate to the signer’s certificate authority (CA). Trust can also be established if the Notes user issues a cross-certificate directly to the signer’s certificate or to the signer’s Certificate Authority. Or, the Notes user’s organizational certifier can issue a cross-certificate directly to the signer’s certificate. 4. Notes or the mail application compares the decrypted hash with a hash of the message generated by the reader. A match means that the signature is valid.

43-10 Administering the Domino System, Volume 2

Security

5. If the digest comparison is successful, Notes or the S/MIME mail application indicates who signed the message. If decryption is unsuccessful, the application indicates that it could not verify the signature. Unsuccessful decryption and comparision may indicate that the data has been tampered with. Note Certificate trust checking occurs independently of hash decryption and comparison. Decryption and comparison may succeed even if the certificate is not trusted. This might happen, for example, when a user receives mail from a user in another company and that user doesn’t have a cross-certificate. For more information on cross-certificates, see the chapter “Protecting and Managing Notes IDs.”

Signing sent mail
Notes client users control whether the mail they send is signed. Users can sign individual mail messages or sign all mail messages that they send. When sending signed messages to users of S/MIME mail applications, Notes users must have an additional set of Internet public and private keys. For information on obtaining Internet public and private keys, see the chapter “Setting Up Clients for S/MIME and SSL.” For more information on signing mail, see Lotus Notes 6 Help.

Encryption and Electronic Signatures 43-11

Security

Chapter 44 Setting Up a Domino Server-Based Certification Authority
This chapter describes how to set up a Domino server-based certification authority (CA) to issue server and client certificates using the CA process server task.

Domino server-based certification authority
You can set up a Domino certifier that uses a server task, the CA process, to manage and process certificate requests. The CA process runs as an automated process on Domino servers that are used to issue certificates. When you set up a Notes or Internet certifier, you link it to the CA process on the server in order to take advantage of CA process activities. Only one instance of the CA process can run on a server; however, the process can be linked to multiple certifiers. You can set up Notes and Internet certifiers to use the CA process. Consider using the CA process because it: • • Provides a unified mechanism for issuing Notes and Internet certificates. Supports the registration authority (RA) role, which you use to delegate the certificate approval/denial process to lower-echelon administrators in the organization. Does not require access to the certifier ID and ID password. After you enable certifiers for the CA process, you can assign the registration authority role to administrators, who can then register users and manage certificate requests without having to provide the certifier ID and password. Simplifies the Internet certificate request process through a Web-based certificate request database. Issues certificate revocation lists, which contain information about revoked or expired Internet certificates.

• •

44-1

• •

Creates and maintains the Issued Certificate List (ICL), a database that contains information about all certificates issued by the certifier. Is compliant with security industry standards for Internet certificates — for example, X.509 and PKIX.

To manage the CA process from the Domino console, you use a set of server Tell commands. For more information on CA process Tell commands, see the appendix “Server Commands.” Issued Certificate List (ICL) Each certifier has an Issued Certificate List (ICL) that is created when the certifier is created or migrated to the CA process. The ICL is a database that stores a copy of each unexpired certificate that it has issued, certificate revocation lists, and CA configuration documents. Configuration documents are generated when you create the certifier and sign it with the certifier’s public key. After you create these documents, you cannot edit them. CA configuration documents include: • • • Certificate profiles, which contain information about certificates issued by the certifier. CA configuration document, which contains information about the certifier itself. RA/CA association documents, which contain information about the RAs who are authorized to approve and deny certificate requests. There is one document for each RA. ID file storage document, which contains information about the certifier ID.

Another CA configuration document, the Certifier document, is created in the Domino Directory when you set up the a certifier. This document can be modified. For more information, see the topic “Modifying a certifier” later in this chapter. Certificate Revocation List (CRL) A CRL is a time-stamped list identifying revoked Internet certificates — for example, certificates belonging to terminated employees. The CA process issues and maintains CRLs for each Internet certifier. A CRL is associated with a certifier, is signed by that certifier, and resides in the certifier’s ICL database. A copy of the CRL is also stored in the Domino Directory, where it is used to assert certificate validity by entities that require certificate authentication.
44-2 Administering the Domino System, Volume 2

Security

You configure the CRL when you create a new Internet certifier. You can specify the length of time for which a CRL is valid and the interval between publication of new CRLs. After CRLs are configured, the certifier issues them on a regular basis and they operate unattended. Using CRLs, you can manage the certificates issued in your organization. You can easily revoke a certificate if the subject of the certificate leaves the organization or if the key has been compromised. HTTP servers and Web browsers check the CRLs to determine whether a given certificate has been revoked, and is therefore no longer trusted by the certifier. When you use Internet Site documents to configure Internet protocols on the Domino, you can also enable CRL-checking for each protocol. There are two kinds of CRLs: regular and non-regular. For regular CRLs, you configure a duration interval — the time period for which the CRL is valid — and the interval at which new CRLs are issued. Each certifier issues a CRL at the specified time, even if no certificates have been revoked since the last CRL was issued. This means that if an administrator revokes a certificate, it appears in the next scheduled CRL issued by the certifier. The CRL duration period should be greater than the time period between each CRL issuance. This ensures that the CRL remains valid. Otherwise, the CRL could expire before a new one is issued. However, in the event of a critical security break — for example, if the administrator needs to revoke a particularly powerful certificate or the certifier certificate is compromised — you can manually issue a non-regular CRL — that is, an unscheduled CRL — to enforce the emergency revocation. This type of revocation does not affect either the timing or the content of the next scheduled CRL. You use a Tell command to issue a non-regular CRL. For more information on revoking a certificate, see the topic “Revoking a certificate” later in this chapter. For more information on enabling CRL-checking, see the chapter “Installing and Setting Up Domino Servers.” For more information on configuring a regular CRL, see the topic “Creating an Internet CA” later in this chapter. For more information on issuing a nonscheduled CRL, see the appendix “Server Commands.”

Setting Up a Domino Server-Based Certification Authority 44-3

Administering a Domino CA
There are a number of tasks associated with managing a certifier. If you implement a certifier that uses the CA process, you can delegate Notes and Internet certificate request approval and denial to other administrators, each of whom acts as a registration authority. Note Many of the manual tasks associated with managing a CA prior to Domino 6 are now automated when you use the CA process. Domino certificate authority administrator tasks The Domino certificate authority administrator (CAA) is responsible for these tasks: • • • Create and configure certifiers. Modify certifiers. For example, only a CA administrator can edit ID recovery information for a Notes certifier. Add or remove Certification and Registration Authority administrators, or change the CA and RA roles assigned to users.

The CAA must have at least Editor access to the master Domino Directory for the domain. As a best practice, designate at least two CAAs for each certifier. You then have a backup if one leaves the organization. Note By default, the administrator who creates a certifier is automatically designated as both a CAA and an RA for that certifier. When you create additional CAAs, they must be assigned the RA role in order to register users. Domino Registration Authority administrator tasks A registration authority (RA) administrator registers Notes users and Domino servers, approves or denies Internet certificate requests, and, if necessary, revokes Internet certificates. While a CA administrator can also be a registration authority, the main advantage of having a separate RA role is to offload these tasks from the Domino and/or CA administrator. Moreover, the Domino administrator can establish one or more RAs for each certifier enabled for the CA process. An RA should approve only those requests that will be accepted by the certifier. The CA Configuration document, stored in the CA’s ICL database, describes what is acceptable. Domino administrators who register Notes users should also be listed as RAs for the Notes certifier. If you are using the Web Administrator client, you need to set up a server-based certification authority to register Notes users. The Web
44-4 Administering the Domino System, Volume 2

Security

administrator, as well as the server on which the Web Administrator database resides, must be listed as an RA for that certifier. The Domino Registration Authority (RA) administrator is responsible for these tasks: • • • Register users, servers, and additional Notes certifiers. Approve or deny Internet certificate requests. Revoke certificates if they can no longer be trusted, such as if the subject of the certificate leaves the organization, or if the key has been compromised.

Note CAs and RAs must have at least Editor access to the master Domino Directory for the domain.

Setting up a server-based Domino certification authority
To set up a server-based Domino certification authority, you must configure and enable Notes and Internet certifiers to use the CA process. You can enable only one type of certifier under the CA process — for example, set up only Internet certifiers for the CA process — or you can enable all certifiers for the CA process. If your organization has existing Domino certifiers, you can migrate them to the CA process. To set up a Domino server-based certification authority, perform the following tasks: 1. Migrate existing certifiers to the CA process. 2. Create new certifiers. 3. Add certifiers to the CA process on the server. 4. For each Internet certifier, set up the Certificate Requests database. 5. Set up SSL on the server.

Migrating a certifier to the CA process
To migrate an existing certifier to the CA process, you set up an Issued Certificate List (ICL) database and configure its certificate duration. In addition, for Internet certifiers, you configure CRL and key usage information for the certificate. 1. From the Domino Administrator, click Configuration. 2. On the Tools pane, choose Certification - Migrate Certifier. 3. In Migrate Certifier dialog box, click Select.

Setting Up a Domino Server-Based Certification Authority 44-5

4. In the “Chose ID/key ring file” dialog box, select the CERT.ID of the certifier you want to migrate. • Choose the certifier ID (CERT.ID) and click Select to migrate a Notes certifier. • Choose the certifier key ring file and click Select to migrate an Internet certifier. 5. The certifier ID’s path and filename now appear in the Migrate Certifier dialog box. Enter the password for the certifier ID or key ring file and click OK. 6. If you are migrating a Notes certifier, complete the procedure “To migrate a Notes certifier.” Otherwise, see the procedure “To migrate an Internet certifier.” To migrate a Notes certifier 1. On the Basics tab, complete these fields:
Field Action Select the Select the server that will store the migrated certifier. server where Make sure that the client location document points to this the certifier will server. run Name of ICL database to be created (Optional) ICLs are created automatically when you create a certifier, and named by default. You can modify the default name (for example: “icl\icl_Acme.nsf” for the Acme certifier). Although you can change the location of the ICL, it is recommended that you use the default directory and path.

2. For “Encrypt Certifier ID with,” choose one:
Option Security Password level required None Action required None

Encrypt ID Lowest with Server ID

Encrypt ID Medium Enter a new with password Server ID for this certifier

If you choose to encrypt the certifier ID with the server ID and password, you need to activate the certifier. Use the tell command: tell ca activate <password> continued

44-6 Administering the Domino System, Volume 2

Security

Option

Security Password level required

Action required If you choose to encrypt the certifier ID with a lock ID, the certifier is locked when you create it. Use the tell command: tell ca unlock <idfile><password>

Encrypt ID Highest Registered with Lock user ID ID and password

Note Encrypting a certifier ID with the password-protected Server ID protects only that certifier. If you use a lock ID, you have the option of using it with multiple certifiers. You then need to lock and unlock those certifiers simultaneously. 3. (Optional) In the Administrators list, enter names of additional CAAs and RAs. The name of the administrator migrating the CA is automatically included in the list as both a CAA and an RA. 4. On the Certificates tab, complete these fields:
Field Certificate duration for EE certificate Action Enter the default, minimum, and maximum duration, in months, for an end-entity (EE) certificate. An end-entity certificate is granted to servers or end users. Enter the default, minimum, and maximum duration, in months, for an certificate authority (CA) certificate. A CA certificate is granted to certifiers.

Certificate duration for CA certificate

5. Click OK. A message appears saying that you have successfully migrated the certifier. 6. Add the certifier to the CA process. To migrate an Internet certifier 1. Migrate the key ring file. 2. Complete the Migrate Certifier dialog as described in the procedure “To create an Internet certifier” later in this chapter. For more information on using CA server commands, see the appendix “Server Commands.”

Adding a certifier to the CA process
When you create a certifier specifically for the CA process, you must make sure that the CA process task is running on the server. To manage the CA process, you use Tell commands at the server console.

Setting Up a Domino Server-Based Certification Authority 44-7

To add a certifier to the CA process 1. Make sure that you have already migrated or created a certifier. 2. If this is the first certifier you are setting up to use the CA process, or if the CA process is not already running, at the server console enter:
load ca

3. If the CA process task is already running, it automatically adds newly-created certifiers when it refreshes, which takes place every 12 hours. However, the time period in which the Administration Requests database processes CA requests will vary. If you want to hasten the process, at the console enter:
tell adminp process all tell ca refresh

And then enter the following to see if the new certifier has been added:
tell ca stat

Note To load the CA task automatically, add the parameter ca to the Server setting in the NOTES.INI file. For more information on using CA server commands, see the appendix “Server Commands.”

Creating a certifier for a server-based CA
You can create additional Notes and Internet certifiers for your organization and configure them to use the CA process. To create a Notes certifier 1. Register an additional organization certifier or organizational-unit certifier. 2. Migrate the certifier to the CA process. To create an Internet certifier You create one or more Internet certifiers to issue server and client Internet certificates. 1. From the Domino Administrator, click Configuration. 2. On the Tools pane, select Registration - Internet Certifier. 3. In the Register Internet Certifier dialog box, select “I want to register a new Internet certifier that uses the CA process.” 4. In the Register a New Internet Certifier dialog box, click Basics. 5. Create the certifier name. Specify a common name and at least one additional component:
44-8 Administering the Domino System, Volume 2

Security

• Common name — Enter the certifier name. • Organizational unit (optional) — Enter the name of the certifier’s organizational unit, if applicable. • Organization (optional) — Enter the name of the certifier’s organization. • City or locality (optional) — Enter the organization’s city or locality. • State or province (optional) — Enter the full name of the state or province in which the organization resides. • Country (optional) — Enter the two-character abbreviation for the country in which the organization resides. 6. Choose the server on which to store the certifier. 7. (Optional) Modify the default ICL database name (for example: “icl\icl_Acme.nsf”). Note It is recommended that you use the default directory structure. 8. For “Encrypt Certifier ID with,” select one:
Option Security level Password required None Server ID password Action required None If you choose to encrypt the certifier ID with the server ID and password, you need to activate the certifier. Use the tell command: tell ca activate <password> If you choose to encrypt the certifier ID with a lock ID, the certifier is locked when you create it. Use the tell command: tell ca unlock <idfile><password>

Encrypt ID with Lowest Server ID Encrypt ID with Medium Server ID

Encrypt ID with Highest Lock ID

Registered user ID and password

Note Encrypting a certifier ID with the password-protected Server ID protects only that certifier. If you use a lock ID, you have the option of using it with multiple certifiers. You then need to lock and unlock those certifiers simultaneously.

Setting Up a Domino Server-Based Certification Authority 44-9

9. (Optional) In the Administrators list, enter the names of additional CAAs and RAs. The name of the administrator creating the CA is automatically included in the list as both a CA administrator and an RA administrator. For more information on certifier administrators and registration authorities, see the topic “Administering a Domino CA” earlier in this chapter. 10. On the Certificates tab, complete these fields:
Field Action Include CRL distribution (Optional) Select to enable an attribute that point extension identifies the distribution point for the certifier CRL on the server that you select in the “Using server” list. Backdate certificate validity Certificate duration Key usage Enter the date when the certificate becomes valid, as this may differ from the date on which the certificate is created. Enter the default, minimum, and maximum certificate duration in months. Choose the key usage extensions for this certificate.

Note The default certificate type is end entity certificate. This means that Internet certificates issued by this certifier apply to users of certificates and/or end-user systems that are subjects of a certificate. 11. Click Miscellaneous, and then click “Create a local copy of the certifier ID.” Specify the certifier ID file name and password, and click OK. A copy of the certifier ID is saved to the default path ...\notes\data\ids\certs\cert.id. You can select a different path. Use this local copy of the certifier ID as a backup to re-create the certifier if it become corrupted. 12. Complete these fields to specify Certificate Revocation List information for this certifier:
Field Duration of CRL (in days) Action Enter the length of time, in days, for which a given CRL is valid. It is recommended that this time period extend beyond the time period between issued CRLs, as this ensures that the CRL is always valid. Enter the time interval, in days, between issued CRLs.

Time between CRLs (in days)

44-10 Administering the Domino System, Volume 2

Security

13. Complete these fields to specify “Key and certifier certificate” information for this certifier:
Field Signing algorithm Key length Action Select the algorithm used to encrypt the certificate’s signature. Enter the key length to use for encryption. This setting determines the number of bits needed to be able to represent any of the possible values of a cryptographic key. The longer the key length, the more difficult it is to decrypt encrypted text. (Optional) Change the default certificate expiration date.

Certificate will expire on

14. Complete these fields to specify the Certifier PKIX Alternative Name(s) information for this certifier: Alternative name fields allow alternate names to be listed in certificates. Alternate subject names can appear in any certificate. If a CA has alternate names, those names should be included in the certificates it issues. For example, you can include the certifier’s e-mail address in the certificates it issues, so that users know how to contact the certifier that issued them. Note A PKIX Alternative Name is not the same as a Notes alternate name. The Notes alternate name is the foreign language version of a user name.
Field Type Value Action Enter the type of alternative name you want to use. Enter the alternative name you want to use.

15. Click Add to add the alternative name to the certifier’s certificate. 16. Click OK. A message appears saying that you have successfully set up a CA. 17. Complete these procedures: • Add the new certifier to the CA process. • Create the Certificate Requests application.

Setting Up a Domino Server-Based Certification Authority 44-11

Key usage extensions and extended key usage
Key usage extensions Key usage extensions define the purpose of the public key contained in a certificate. You can use them to restrict the public key to as few or as many operations as needed. For example, if you have a key used only for signing, enable the digital signature and/or non-repudiation extensions. Alternatively, if a key is used only for key management, enable key encipherment. The following table describes the key usage extensions available for keys created using the CA process. Note The digital signature and data encipherment key usage extensions are enabled by default for all Internet certificates.
Key usage extension Description Digital signature Use when the public key is used with a digital signature mechanism to support security services other than non-repudiation, certificate signing, or CRL signing. A digital signature is often used for entity authentication and data origin authentication with integrity. Use when the public key is used to verify digital signatures used to provide a non-repudiation service. Non-repudiation protects against the signing entity falsely denying some action (excluding certificate or CRL signing).

Non-repudiation

Key encipherment Use when a certificate will be used with a protocol that encrypts keys. An example is S/MIME enveloping, where a fast (symmetric) key is encrypted with the public key from the certificate. SSL protocol also performs key encipherment. Data encipherment Key agreement Use when the public key is used for encrypting user data, other than cryptographic keys. Use when the sender and receiver of the public key need to derive the key without using encryption. This key can then can be used to encrypt messages between the sender and receiver. Key agreement is typically used with Diffie-Hellman ciphers.

Certificate signing Use when the subject public key is used to verify a signature on certificates. This extension can be used only in CA certificates. CRL signing Use when the subject public key is to verify a signature on revocation information, such as a CRL. continued

44-12 Administering the Domino System, Volume 2

Security

Key usage extension Description Encipher only Use only when key agreement is also enabled. This enables the public key to be used only for enciphering data while performing key agreement. Use only when key agreement is also enabled. This enables the public key to be used only for deciphering data while performing key agreement.

Decipher only

Extended key usage

Extended key usage further refines key usage extensions. An extended key is either critical or non-critical. If the extension is critical, the certificate must be used only for the indicated purpose or purposes. If the certificate is used for another purpose, it is in violation of the CA’s policy. If the extension is non-critical, it indicates the intended purpose or purposes of the key and may be used in finding the correct key/certificate of an entity that has multiple keys/certificates. The extension is then only an informational field and does not imply that the CA restricts use of the key to the purpose indicated. Nevertheless, applications that use certificates may require that a particular purpose be indicated in order for the certificate to be acceptable. If a certificate contains both a critical key usage field and a critical extended key usage field, both fields must be processed independently, and the certificate be used only for a purpose consistent with both fields. If there is no purpose consistent with both fields, the certificate must not be used for any purpose.
Extended key TLS Web server authentication TLS Web client authentication Sign (downloadable) executable code Email protection IPSEC End System (host or router) IPSEC Tunnel Enable for these key usage extensions Digital signature, key encipherment or key agreement Digital signature and/or key agreement Digital signature

Digital signature, non-repudiation, and/or key encipherment or key agreement Digital signature and/or key encipherment or key agreement Digital signature and/or key encipherment or key agreement continued

Setting Up a Domino Server-Based Certification Authority 44-13

Extended key IPSEC User Timestamping

Enable for these key usage extensions Digital signature and/or key encipherment or key agreement Digital signature, non-repudiation.

Examples of required key usage extensions
Application SSL Client SSL Server S/MIME Signing S/MIME Encryption Certificate Signing Object Signing Required key usage extensions Digital signature Key encipherment Digital signature Key encipherment Certificate signing Digital signature

Creating the Certificate Requests database
Each Internet certifier you create requires a Certificate Requests database (CERTREQ.NSF) to manage server and client certificate requests. This database stores active certificate and revocation requests that have been submitted to the Administration Process for processing. Using a browser-based interface, servers and clients request certificates and pick up issued certificates. You can store Certificate Requests databases on any server in the domain, including servers that reside outside of a network firewall. For more information on using the Certificate Requests database to process certificate requests, see the chapter “Setting Up Clients for S/MIME and SSL.” To create the Certificate Requests database 1. Choose File - Database - New and select the server to store the Certificate Requests database. 2. Enter the database title and file name — for example: Certificate Requests and CERTREQ.NSF. 3. Choose the Certificate Requests (R6) template (CERTREQ.NTF). 4. Click OK. When the Certificate Requests database has been created, it will open and the “About...” document will appear. 5. Close the “About...” document, and the Database Configuration form will appear.

44-14 Administering the Domino System, Volume 2

Security

6. In the Database Administration section, complete these fields:
Field Supported CA Action Do the following: 1. In the Server field, enter the name of the server that hosts the Internet certifier. 2. In the Certifier field, enter the name of the Internet certifier to associate with the Certificate Request database. Choose one: • Client certificates only — Select this option if the certifier will issue client Internet certificates. Do not select this option if you want to create a server key ring for SSL. If you select this option, you must customize client requests. • Server certificates only — Select this if the certifier will issue server Internet certificates. If you select this option, you must customize server requests. • Both client and server certificates — Select this if the certifier will issue both client and server Internet certificates. If you select this option, then you need to customize both server and client requests.

Supported certificate types

7. (Optional) In the Client Request Customization section, complete these fields:
Field Validity period Action Enter the number of years that client requests generated with this database will specify as a validity period, beginning at the time of request submission. Default is 1 year. Choose the default key usage that will be submitted in client certificate requests generated from this database. Default settings are Key Encipherment and Digital Signature, which are sufficient for a client S/MIME certificate. Choose the default extended key usage that will be submitted in client certificate requests generated from this database. Default settings are Client Authentication and Email Protection.

Key usages

Extended key usages

Setting Up a Domino Server-Based Certification Authority 44-15

8. (Optional) In the Server Request Customization section, complete these fields:
Field Validity period Action Enter the number of years that server requests generated with this database will specify as a validity period, beginning at the time of request submission. Default is 1 year. Choose the default key usage that will be submitted in server certificate requests generated from this database. Default settings are Key Encipherment and Digital Signature, which are sufficient for an SSL server certificate. The default extended key usage that will be submitted in server certificate requests generated from this database. Default is Server Authentication.

Key usages

Extended key usages

9. For “Processing method,” choose the method by which requests are submitted to the Administration Process: • Manual (default) — Choose this if you want an RA to review requests submitted to the Certificate Requests to approve or deny each request individually. • Automatic — Choose this to have requests submitted to the Certificate Requests database processed without RA intervention. Requests will be approved or denied according to the certificate policy. If this method is chose, the “Automatic Transfer Server” field appears, in which you need to specify the server running the administration process and to which certificate requests will automatically be transferred. Note If the Automatic method is chosen, the RA must be listed in the group of users who can run unrestricted methods and operations on the server. This can be set on the Security tab in the Server document. There must also be a replica of the Certificate Requests database on the specified transfer server. 10. For “Mail notification,” choose whether or not to send e-mail notification when a certificate request has been processed by the CA. • Yes (default) — Choose this if you want the requester to be notified by e-mail when a certificate request has been processed by the CA. • No — Choose this if you do not want the requester to be notified by e-mail when a certificate request has been processed by the CA. 11. Click Save & Close.

44-16 Administering the Domino System, Volume 2

Security

Setting up SSL on a server-based CA server
Because server administrators and clients use browsers to access the CA server to request and pick up certificates, use SSL to protect the CA server. When you set up the CA server for SSL, you create the server key ring file and request a server certificate. Domino automatically approves the server certificate and merges the CA certificate as a trusted root. For information on approving server certificate requests for Domino servers that are not CA servers, see the topic “Signing server certificates” later in this chapter. To set up SSL on a server-based CA server 1. Create an Internet certifier. 2. Create the Certificate Requests application (CERTREQ.NSF). 3. Do the following to create a server key ring file to store the server certificate, and merge the CA certificate as a trusted root into the server key ring file: a. In the Certificate Requests database, choose Domino Key Ring Management - Create Key Ring. b. In the Create Key Ring form, complete these fields:
Field File name Password Key size Common name Action Enter a file name for the Key Ring file and keep the .kyr. Enter a password for the key ring file. Choose a key size. Enter the fully qualified host name — for example, server.company.com. Enter the full name of the state or province in which the organization is located. Enter a two-letter abbreviation for the country in which the organization is located.

Organization name Enter the name of the certifier organization. State or province Country

c. Verify the information in the “Key Ring Created” dialog box, then click OK to add your CA as a trusted root and generate a certificate request for the server. d. Verify the information in the “Merge Trusted Root Certificate Confirmation” dialog box and click OK.

Setting Up a Domino Server-Based Certification Authority 44-17

e. When the “Certificate received into key ring and designated as trusted root” confirmation dialog box appears, click OK. f. When the “Certificate Request Successfully Submitted for Key Ring” dialog box appears, click OK. If you chose Automatic as the processing method used by the Certificate Requests database, continue with Step 5. If you chose Manual, then complete Steps 4 through 6. 4. Do the following to transfer the certificate request to the Administration Requests database: a. In the Certificate Requests database, open the Submitted/Waiting for Approval view. If the request does not appear, press F9 to refresh the view. b. If the request has been “Submitted to Administration Process,” continue with Step 5. If the request is still Pending, highlight the request and click “Submit Selected Requests.” c. When you see “Successfully submitted 1 request(s) to the Administration Process,” click OK. 5. Have an authorized registration authority approve the request. This RA should be authorized for the certifier for which you are setting up SSL. a. Open the Administration Requests database (ADMIN4.NSF), and then open the Certification Authority Requests/Certificate Requests view and find the new request. b. Open the request and verify the information in it. c. Click Edit Request, then Approve Request. Press F9 until the request changes from “New” to “Issued.” 6. Transfer the certificate request out of the Administration Requests database: a. Close the Administration Requests database and return to the Certificate Requests database. b. Open the Pending/Submitted Certificates view and locate the request. If necessary, refresh the view. c. If the certificate has not yet been issued, click “Pull Selected Request(s).”

44-18 Administering the Domino System, Volume 2

Security

7. After the CA signs the request for a server certificate and notifies you to pick up the certificate, do the following: a. Do one: • Open the Administrator’s mail file, locate and open a message with the subject “Your certificate request has been approved,” and copy the pickup ID to the Clipboard. • From the Certificate Requests database, open the Submitted/Accepted view, then open the issued server request and copy the “Request ID” to the clipboard. b. In the Certificate Requests database, choose “Domino Key Ring Management,” then “Pickup Key Ring Certificate.” c. Enter the key ring file name and password, paste the pickup ID into the form, and click Pickup Certificate. 8. Do the following to merge the approved server certificate into the key ring file: a. When the “Merge Signed Certificate Confirmation” dialog box appears, verify the information and click OK. b. When the “Certificate received into key ring” confirmation box appears, click OK. c. Copy or use FTP (in binary mode) to transfer the new key ring file and its associated .STH file to the server’s data directory. 9. Configure the port for SSL: a. In the Domino Directory, open the Server document. In the Ports/Internet Ports section, click Edit Server and enter the name of the new key ring file. (Do not include the full path to the key ring file. Specify only the file name.) Enable the “SSL Port Status” field and then click Save and Close. Note As an optional step, while editing the Server document, enable “Session authentication” in the Internet Protocols/Domino Web Engine section. This ensures that HTTP sessions will time out in the number of minutes that are specified in the “Idle session timeout” field. The Maximum active sessions may also be specified. b. If HTTP is already running, at the console type “te http restart” to enable SSL on the server. c. To show SSL status and to verify that the HTTP server is listening on both 80 and 443, type “te http show security” at the server console.

Setting Up a Domino Server-Based Certification Authority 44-19

10. Do the following to confirm that SSL is working on the server. a. Open a browser, and enter the URL of the server — for example:
https://Server.Company.com/certreq.nsf

b. If the “New Site Certificate” dialog box appears, click Next. c. Click More Info to verify the information, then click Next. d. Decide whether or not to accept the new site certificate, and for how long, then click Next. e. Decide whether or not you want to see a warning every time you access the new site, then click Next. When the dialog box appears, click Finish. If the Security indicator (a padlock icon) is closed (locked), you have successfully established a secure session over SSL.

Signing server certificates using the Certificate Requests database
A Domino administrator can request a server certificate from a server-based CA in order to enable SSL on a Domino server. The request is entered and processed in the Certificate Request database, where a registration authority (RA) administrator approves or denies the request. Note If you chose Automatic as the processing method used by the Certificate Requests database, you only need to complete Step 3. If you chose Manual processing, then complete the entire procedure. To sign a server certificate request 1. From the Domino Administrator, open the Certificate Requests database. 2. Transfer the certificate request to the Administration Requests database: a. In the Certificate Requests database, open the Pending/Submitted Requests view. If the request does not appear, press F9 to refresh the view. b. If the request has been “Submitted to Administration Process,” continue with Step 3. If the request is still Pending, highlight the request and click “Submit Selected Requests.” c. When you see a “Successfully submitted 1 request(s) to the Administration Process,” click OK. 3. Have an RA who is listed for this certifier approve the request. a. Open the Administration Requests database (ADMIN4.NSF), and then open the Certification Authority Requests/Certificate Requests view and find the new request.
44-20 Administering the Domino System, Volume 2

Security

b. Open the request and verify the information in it. c. Click Edit Request, then Approve Request. Press F9 until the request changes from “New” to “Issued.” 4. Transfer the certificate request out of the Administration Requests database: a. Close the Administration Requests database and return to the Certificate Requests database. b. Open the Pending/Submitted Certificates view and locate the request. If necessary, refresh the view. c. If the certificate has not yet been issued, click “Pull Selected Request(s).” 5. The certifier signs the request for a server certificate and notifies the requester to pick up the certificate.

Modifying a server-based CA
After you migrate or create a certifier, you can modify it through the certifier ICL or through the certifier document in the Domino Directory. Note that how you open a certifier to modify it affects the number and type of changes you can make. Note Only CA administrators can modify a server-based CA. A CA administrator must have Editor access to the Domino Directory in order to modify a certifier. To modify a certifier through the ICL 1. Shut down the CA process used by the certifier that you want to modify. At the server console, type:
tell ca quit

2. From the Domino Administrator, click Configuration. 3. On the Tools pane, choose Certification - Modify Certifier. 4. Select the server that hosts the CA you want to modify, if necessary 5. Select the certifier to recover by doing one of the following: • Select the certifier document from the Domino Directory. • Select the certifier ICL database. Note If the certifier is protected with a lock ID, you must unlock it in order to modify it.

Setting Up a Domino Server-Based Certification Authority 44-21

6. In the Certifier dialog box, modify the certifier as needed. You can change these features: • Encryption mechanism for certifier ID • CAs and RAs, and roles of current entries • CRL distribution point extension • Enable or disable backdating of certificate • Certificate duration • Certificate key usage (Internet certifiers only) • CRL publication and duration (Internet certifiers only) • For detailed information on these options, see the topic “Creating a certifier for a server-based CA” earlier in this chapter. 7. Click OK. To modify a certifier through the Certifier document To modify a Certifier document, you must have Editor access to the Domino Directory. Full-access administrators and administrators have this access by default; however, be sure that all certificate authority (CA) administrators also have this access. 1. From the Domino Administrator, click Configuration. Note If the certifier is protected with a lock ID, you must unlock it in order to modify it. • On the Basics tab, you can modify certifier name and issuer. • Click “Modify CA configuration” to change CAA and RA associations. 2. Click Save and Close.

Disabling a certifier
To modify a Certifier document, you must have Editor access to the Domino Directory. Full-access administrators and administrators have this access by default; however, be sure that all certificate authority (CA) administrators also have this access. 1. From the Domino Administrator, click Configuration and open the Certificates view in the Server pane. 2. Select the certifier document you want to disable and double-click to open it. 3. Click Edit Certifier.

44-22 Administering the Domino System, Volume 2

Security

4. On the CA Configuration tab, disable the CA process for the certifier. 5. Click Save and Close. Caution If you disable the CA process for a certifier, and later want to enable it, you must open the certifier document and enable it. You can also repeat the CA migration process to enable it — however, this creates a new ICL database for the certifier.

Revoking a certificate
A CA administrator can easily revoke an Internet certificate if the subject of the certificate leaves the organization, or if the key has been compromised. After a certificate is revoked, it can never again be trusted. If you revoke a certificate, especially if a key has been compromised, issue a non-regular CRL so that any entity checking CRLs has the most updated revocation information. To revoke a certificate 1. From the Domino Administrator, click Files. Open the ICL directory. 2. From the list of ICL databases, open the ICL for the certifier that issued the certificate you need to revoke. 3. Open the Issued Certificates\By Subject Name view. 4. Open the Issued Certificate document for the certificate you want to revoke. The document name is the same as the subject name. 5. At the top of the document, click “Revoke Certificate.” 6. In the Revocation Reason dialog box, select the reason for revoking the certificate, and click OK. 7. Issue a non-regular CRL. The next time the CA process refreshes, the Issued Certificate document will be updated to indicate that the certificate has been revoked. When you open the Issued Certificate document again, the Revocation Information section will indicate that the certificate has been revoked, the revocation date and time, the reason for the certificate’s revocation, and date and time the certificate became invalid. For more information on issuing non-regular CRLs, see the appendix “Server Commands.”

Setting Up a Domino Server-Based Certification Authority 44-23

Viewing certifiers running under the CA process You can view a list of all the certifiers running under the CA process. At the server console type:
tell ca status

The server returns a list of all certifiers using the CA process and their current status. The number associated with each certifier is used in some CA Tell commands. For example:
10/22/2001 02:38:12 pm CA Process status: 10/22/2001 1. O=Acme 02:38:12 pm

10/22/2001 02:38:12 pm Certifier type: Notes 10/22/2001 02:38:12 pm Active: Yes 10/22/2001 02:38:12 pm ICL DB Path: icl\icl_Acme.nsf 10/22/2001 02:38:12 pm 2. CN=East/O=Acme/ST=Massachusetts/C=US 10/22/2001 02:38:12 pm Certifier type: Internet 10/22/2001 02:38:12 pm Active: Yes 10/22/2001 02:38:12 pm ICL DB Path: icl\icl_East.nsf

For more information about using CA Tell commands, see the appendix “Server Commands.”

Viewing certificate requests
Domino CAs and RAs can view information about server and client certificate requests waiting for approval, as well as approved and rejected requests. 1. From the Domino Administrator, click Files and open the Certificate Requests database for the certification authority for which you want to see certificate requests. 2. Click Pending/Submitted Requests or Issued/Rejected Certificates.

44-24 Administering the Domino System, Volume 2

Security

Backing up and recovering a certifier
Back up each certifier that you create, so that you can recover if there is a problem — for example, if error messages are generated by the certifier when you issue a “lo ca” or “tell ca refresh” command. To back up a certifier 1. When you create a new certifier, keep a local copy of the certifier ID file. 2. After you create the certifier, make a copy of the ICL database and keep it in a safe place. Back up the ICL periodically to incorporate any changes you make to the certifier. To recover a certifier 1. From the Admin client, click Configuration. 2. On the Tools pane, choose Certification - Modify Certifier. 3. Select the CA server from the list, and click OK. 4. Select the server that hosts the CA you want to modify, if necessary. 5. Select the certifier to recover by doing one of the following: • Select the certifier document from the Domino Directory. • Select the certifier ICL database. 6. You may be prompted for the certifier ID and password. Enter the path and filename for the local copy of the ID that you created when you first set up the certifier, and click OK. Note You will be prompted for the certifier ID only if the certifier determines that it cannot proceed without it. 7. In the Modify Certifier dialog box, confirm that the certifier information is correct. Click OK. If the certifier is still having problems — for example, configuration documents are corrupted or missing — replace the ICL database with the back up copy. The location of the ICL database is specified in the certifier document.

Setting Up a Domino Server-Based Certification Authority 44-25

Security

Chapter 45 Setting Up a Domino 5 Certificate Authority
This chapter describes how to set up a Domino 5 certificate authority (CA) to issue server and client certificates using a CA key ring file.

Using a Domino 5 certificate authority
You can set up a Domino certificate authority (CA), or certifier, in one of two ways: you can use a CA key ring or you can use the CA process. Using a Domino 5 certificate authority requires that you: • • • Have access to the CA key ring and password in order to administer the certifier and issue certificates. As an administrator, must administer and safeguard the certifier ID. Issue Notes and Internet certificates separately.

A CA key ring file is a binary file that is password-protected and is used to store the CA certificate. This certificate is then used to sign server and client Internet certificates. Once you have created a certifier on a Domino server, you can then enable SSL on that server to provide secure communications for certificate requests and pickups. You do this by creating a server key ring file and merging the CA certificate into it as a trusted root certificate.

Setting up a Domino 5 certificate authority
A Domino CA server hosts the Domino Certificate Authority application. Users, server administrators, and Domino CAs use the application to manage server and client certificates. Most organizations need only a single Domino CA server. To set up a Domino CA server, you must perform these tasks: 1. Set up the server as a Domino Web server. For more information, see the chapter “Setting Up the Domino Web Server.” 2. Create the Domino 5 Certificate Authority application.
45-1

3. Create a CA key ring file and CA certificate. 4. Configure the CA profile to specify key ring and mail settings. 5. Set up SSL on the CA server.

Creating the Domino Certificate Authority application
1. Set up the server as a Domino Web server. 2. Using the Domino Designer, create the Domino Certificate Authority application on the server using the Domino R5 Certificate Authority template (CCA50.NTF). To view the template file, select the option Advanced templates. You can name the application anything you wish — for example, CERTCA.NSF. 3. Edit the ACL of the Domino 5 Certificate Authority database, as follows: a. Add the names of the administrators who will issue and manage Internet certificates. Assign Editor with Delete access and the [CAPrivlegedUser] role to each administrator. b. Set the -Default- access to Author with Create documents privilege. 4. Create a CA key ring file and certificate. Tip To hide the Domino Certificate Authority application so that it doesn’t appear when users choose File - Database - Open and when Web clients browse a database list, deselect “Show in Open Database dialog” on the Tools tab in the Database Properties box.

Creating a CA key ring file and certificate
When you use the Domino Administrator to create the CA key ring file, it is stored by default in the client’s data directory. Make sure that you keep the key ring file in a secure location, especially if you copy it to a shared location. To prevent unauthorized access, only the administrators that you specify should have access to the CA’s key ring file and password. To create a CA key ring file and certificate 1. Make sure you created the Domino Certificate Authority application. 2. From the Domino Administrator, click Files, and open the Domino Certificate Authority application. 3. Click Create Certificate Authority Key Ring & Certificate.

45-2 Administering the Domino System, Volume 2

Security

4. Complete these fields:
Field Key ring file name Action Enter the explicit path and file name for the CA key ring. The default is CAKEY.KYR in the Domino Administrator’s data directory. It’s helpful to use the extension .KYR to keep server and CA key ring file names consistent. Specify a password for the key ring. Enter the password entered into the previous field. This helps ensure the password is entered correctly. Select the size of the public and private key pairs. The larger the size, the stronger the encryption. Enter a descriptive name that identifies the CA certificate — for example, Acme SSLCA. Enter the name of the certifier organization. This is usually a company name, such as Acme. (Optional) Enter the division or department in which the certifier resides. (Optional) Enter the city or town where the certifier resides.

Key ring password Password verify Key Size Common name Organization Organizational Unit City or Locality

State or Province Enter three or more characters that represent the state or province where the certifier resides, such as Massachusetts. (For U.S. states, enter the complete state name, not the abbreviation.) Country Enter the two-character representation of the country where the certifier resides — for example, US for United States or CA for Canada.

Note The Common name, Organization, Organizational Unit, City or Locality, State or Province, and Country make up the CA server’s distinguished name. Choose the CA name carefully; it is a costly process to reissue certificates if you change the name. 5. Click Create Certificate Authority Key Ring. 6. After you review the information about the key ring file and CA name, click OK. 7. Make a backup copy of the Certificate Authority key ring file, and store it in a secure location. 8. Configure the Domino Certificate Authority application profile.

Setting Up a Domino 5 Certificate Authority 45-3

To change the password for the CA key ring file To ensure the continued security of the CA key ring file, periodically change its password. 1. From the Domino Administrator, click Files, and open the Domino Certificate Authority application. 2. Click View Certificate Authority Key Ring, and then click Change CA Key Ring Password. 3. Enter the old password, and then click OK. 4. Enter a new password, and then click OK.

Configuring the Domino Certificate Authority application profile
The Domino Certificate Authority application profile identifies the CA’s key ring file and specifies the name of the CA server. Domino adds a link to the CA server when you send a message to clients and server administrators who request certificates. The clients and server administrators use this information to determine where to pick up certificates. 1. Make sure you created a CA key ring file and certificate. 2. From the Domino Administrator, click Files, and open the Domino Certificate Authority application. 3. Click Configure Certificate Authority Profile. 4. If necessary, enter the CA key ring path and file name in the CA Key File field. By default, Notes looks for the key ring file on the local hard drive. You can also specify a network drive accessible to other administrators. 5. Enter the TCP/IP DNS name of the server that runs the CA application in the Certificate Server DNS name field. Domino uses this name to indicate where to pick up signed certificates in the messages sent to administrators and clients. The following fields set default values for the Approved Client Certificates screen. You can override these when approving a certificate.
Field Use SSL for certificate transactions? Action Choose one: • Yes (default) to specify whether the e-mail message generated during the security request process includes a reference to the SSL port for secure certificate pick-up. • No to specify SSL will not be used. Certificate Server Enter the number of the TCP/IP port for the server. port number Domino uses this port when sending an e-mail notification to clients to pick up certificates. The default is 80. continued 45-4 Administering the Domino System, Volume 2

Security

Field

Action

Mail confirmation Choose one: of signed • Yes to generate an e-mail confirmation for a signed certificate to certificate request. requester? • No (default) to not send the confirmation. Submit signed certificates to AdminP for addition to the Directory? Default validity period Choose one: • Yes (default) to submit the signed certificate request to the Administration Process, which then stores this certificate in the Domino Directory. • No to not submit the certificate. Specify the period, in years, for which the signed certificate is valid. Default is 2 years.

6. Click Save & Close. 7. Set up SSL on the CA server.

Setting up SSL on the CA server
Because server administrators and clients use browsers to access the CA server to request and pick up certificates, use SSL to protect the CA server. When you set up the CA server for SSL, you create the server key ring file and request a server certificate. Domino automatically approves the server certificate and merges the CA certificate as a trusted root. 1. Make sure you configured the Domino Certificate Authority application profile. 2. From the Domino Administrator, click the Files tab, and open the Domino Certificate Authority application. 3. Click Create Server Key Ring & Certificate. 4. Complete these fields:
Field Key ring file name Action Enter the name of the server key ring file. By default, this is stored in the data directory of the Domino Administrator used to create the file. Do not use the same name as the CA key ring file. Specify a password for the key ring. Enter the password entered into the previous field. This helps ensure the password is entered correctly. Select the size of the public and private key pairs. The larger the size, the stronger the encryption. continued Setting Up a Domino 5 Certificate Authority 45-5

Key ring password Password verify Key size

Field CA certificate label Common name

Action Enter the label to display when you view the CA certificate in the server key ring file. Enter the TCP/IP fully-qualified host name — for example, www.lotus.com. Set up the server certificate so that the common name matches the DNS name, since some browsers check for this match before allowing a connection. Enter the name of the certifier organization. This is usually a company name, such as Acme. (Optional) Enter the division or department where the certifier organization resides. (Optional) Enter the city or town where the certifier organization resides.

Organization Organizational Unit City or Locality

State or Province Enter three or more characters that represent the state or province where the certifier organization resides, such as Massachusetts. (For U.S. states, enter the complete state name, not the abbreviation.) Country Enter a two-character representation of the country where the certifier organization resides — for example, US for United States or CA for Canada.

5. Click Create Server Key Ring. 6. Enter the CA key ring file password, and then click OK. The server SSL key ring file is created. 7. Copy the server key ring file to the Domino data directory on the server. The Domino Certificate Authority application creates the file locally; however, the server needs the key ring file to use SSL. Note If you choose to store the server key ring file in some place other than the Domino data directory, you must specify the full directory path to it in the Server document or Site document. 8. Configure the SSL port. Enable server authentication on the server. For more information on configuring an SSL port, see the chapter “Setting Up SSL on a Domino Server.” 9. If clients use Netscape Navigator, do the following: a. From the Domino Administrator, click the Files tab, open the Domino Certificate Authority application, and then open the Database Properties box. b. On the Basics tab, choose “Web Access: Require SSL connection” to force browsers to use SSL to connect to this database.

45-6 Administering the Domino System, Volume 2

Security

Note If clients use Microsoft Internet Explorer, do not complete this step, which forces users to use SSL to access the application. Clients who use Internet Explorer must use TCP/IP to access the Domino Certificate Authority application and merge the certificate as a trusted root. Internet Explorer does not allow clients to accept a site certificate for a server for which they do not have the trusted root certificate.

Displaying the CA key ring file
1. From the Domino Administrator, click Files, and open the Domino Certificate Authority application. 2. Click View Certificate Authority Key Ring. 3. Click Display CA Key Ring. 4. Enter the password when prompted. 5. Double-click the CA Key Pair document you want to open and view. 6. To exit the document after viewing, click Close.

Exporting the CA key ring file
Export the CA key ring to a text file to troubleshoot problems with the CA server and compare key ring files. 1. From the Domino Administrator, click Files, and open the Domino Certificate Authority application. 2. Click View Certificate Authority Key Ring. 3. Click Dump CA Key Ring to Text. 4. Enter the password when prompted. 5. Enter the name of the file to which you want to export the key ring. Notes creates this text file and places it in the data directory. 6. To view the text file, open it with a text editor.

Signing server certificates
The certificate authority signs a server certificate to add its digital signature to the certificate. A request for a server certificate appears in the Server Certificate Requests view in the Domino Certificate Authority application. When the certificate authority signs a certificate, the certificate authority can automatically notify the requesting server administrator by e-mail. The e-mail describes how to pick up the certificate and includes a pick-up ID, which the server administrator must use to identify the certificate during the pick-up process. Domino automatically generates the pick-up ID.

Setting Up a Domino 5 Certificate Authority 45-7

To sign a server certificate with a Domino 5 Certificate Authority Before you begin, make sure that: • • The requesting server administrator has merged the Certificate Authority’s certificate into the server key ring as a trusted root. You understand your organization’s policy on signing certificates. Sign certificates only if the certificate requests comply with your organization’s security policy.

1. From the Domino Administrator, click Files and open the Domino Certificate Authority application. 2. Click Server Certificate Requests. 3. Open the request to sign. 4. Review the user information and distinguished name. Make sure that the information provided complies with your organization’s security policy. If you want to deny the request, complete Step 5. Otherwise, go to Step 6. 5. To deny the request, do the following: a. Enter a reason for the denied request. b. If you do not want to notify the server administrator by e-mail, deselect “Send a notification email to the requester.” Otherwise, Domino sends the server administrator an e-mail indicating that you denied the request and the reason why you denied the request. c. Click Deny. 6. To approve the request, do the following: a. Enter a validity period. For short-term projects, 90 days is typical; for ongoing projects, you can enter several years. b. If you do not want to notify the server administrator by e-mail to pick up the certificate, deselect “Send a notification email to the requester.” Otherwise, Domino sends the server administrator an e-mail with a URL indicating the location to pick up the certificate. c. Click Approve. d. Enter the password for the CA’s key ring file, and then click OK. 7. Have the server administrator complete the procedure “Merging a server certificate into the key ring file.”

45-8 Administering the Domino System, Volume 2

Security

Viewing requests for certificates
Domino certificate authority administrators can view information about server and client certificates waiting for approval, approved requests waiting for pick-up, and requests that have been denied. 1. From the Domino Administrator, click Files and open the Domino Certificate Authority application. 2. Click Server Certificate Requests or Client Certificate Requests. 3. Use the Actions menu to display requests waiting for approval, approved requests, and denied requests.

Setting Up a Domino 5 Certificate Authority 45-9

Security

Chapter 46 Setting Up SSL on a Domino Server
This chapter describes how to set up SSL on a Domino server to allow secure Internet and intranet access at your organization.

SSL security
Secure Sockets Layer (SSL) is a security protocol that provides communications privacy and authentication for Domino server tasks that operate over TCP/IP. SSL offers these security benefits: • • • • Data is encrypted to and from clients, so privacy is ensured during transactions. An encoded message digest accompanies the data and detects any message tampering. The server certificate accompanies data to assure the client that the server identity is authentic. The client certificate accompanies data to assure the server that the client identity is authentic. Client authentication is optional and may not be a requirement for your organization.

Internet protocols supported by Domino and SSL
You must set up the Domino server and then set up SSL. You can use SSL security for Internet clients who use one of the following Internet protocols to connect to the Domino server: • • • • • • Web server and Web Navigator (HTTP) Internet Inter-ORB Protocol (IIOP) Internet Message Access Protocol (IMAP) Lightweight Directory Access Protocol (LDAP) Post Office Protocol 3 (POP3) Simple Authentication and Security Layer (SASL)

The Java applet that uses this protocol must be set up to use SSL.

46-1

Domino uses SASL automatically if SSL with client authentication is set up on the server and if the LDAP client supports the protocol. No additional configuration is necessary. • Simple Mail Transport Protocol (SMTP)

Setting up SSL on a Domino server
Set up SSL on a Domino server so that clients and servers that connect to the server use SSL to ensure privacy and authentication on the network. You set up SSL on a protocol-by-protocol basis. For example, you can enable SSL for mail protocols — such as IMAP, POP3, and SMTP — and not for other protocols. To set up SSL on your server, you need a key ring containing a server certificate from an Internet certificate authority. You can request and obtain a server certificate from either a Domino or third-party certificate authority (CA) and then install it in a key ring. A server certificate is a binary file that uniquely identifies the server. The server certificate is stored on the server’s hard drive and contains a public key, a name, an expiration date, and a digital signature. The key ring also contains root certificates used by the server to make trust decisions. This describes the process to follow if you need to set up SSL on a Domino server that is not already a Domino certificate authority server. You complete the setup process regardless of whether you request a server certificate from a Domino or third-party CA. Note You can enable SSL on a server when you register the server if you have already have a Domino server-based certification authority running in the Domino domain. For more information about enabling SSL on a server at server registration, see the chapter “Installing and Setting Up Domino Servers.”

To set up SSL on a Domino server
1. Set up the Server Certificate Admin application (CERTSRV.NSF), which Domino creates automatically during server setup. 2. Create a server key ring file to store the server certificate. 3. Request an SSL server certificate from the CA. 4. Merge the CA certificate as a trusted root into the server key ring file. 5. The CA approves the request for a server certificate and sends notification that you can pick up the certificate. 6. Merge the approved server certificate into the key ring file.
46-2 Administering the Domino System, Volume 2

Security

7. Configure the port for SSL. 8. If you are using client authentication, add the client’s name to database ACLs and access lists for design elements.

Setting up the Server Certificate Admin application
Domino automatically creates the Server Certificate Admin application during server setup. If the Server Certificate Admin application is not available after you start the Domino server, use the Server Certificate Admin template (CSRV50.NTF) to create it. Use the Server Certificate Admin application to: • • • • Request server certificates from either a Domino or third-party CA Add a CA certificate as a trusted root Manage server certificates in a key ring file Create a self-certified certificate for testing purposes

To set up the Server Certificate Admin application 1. Make sure you set up the server as a Domino Web server. For more information, see the chapter “Setting Up the Domino Web Server.” 2. Edit the ACL of the Server Certificate Admin application, as follows: • Add the names of server administrators who will need to obtain and manage server certificates. Assign Manager access. • Set -Default- access to No access to prevent others from using the database. 3. Create a server key ring file. Tip To hide the Server Certificate Admin application when users choose File - Database - Open, deselect “Show in ’Open Database’ dialog” in the Database Properties box.

Creating a server key ring file
Before you request a certificate from a CA, you must create a key ring file to store the certificates. A key ring file is a binary file that is password-protected and stored on the server’s hard drive. When you create a server key ring file (.KYR), Domino generates an unsigned server certificate and automatically includes several trusted root certificates. The unsigned server certificate is not valid until it is signed by a certifier. Domino also creates a stash file (.STH) using the same name as the key ring file, but with the file extension .STH. Domino uses the stash file to store the key ring file password for unattended access to the server key ring file.
Setting Up SSL on a Domino Server 46-3

Every server certificate includes a distinguished name used for SSL connections. You set up this distinguished name when you create the server key ring file. Some components of a distinguished name are optional; however, the more components you include, the less likely you are to encounter an identical name elsewhere on the Internet. Note If you are requesting a server certificate from a server-based certification authority, you can use the Notes client to create the server key ring and request a server certificate in the Certificate Requests database. For more information, see the topic “Requesting an SSL server certificate” later in this chapter. To create a server key ring file 1. Set up the Server Certificate Admin application. 2. From the Notes client, open the Server Certificate Admin application on the server for which you want to enable SSL. 3. Click “Create Key Ring.” 4. Complete these fields:
Field Key Ring File Name Action Enter the key ring file name. The default is KEYFILE.KYR. It’s helpful to use the extension .KYR to keep key ring file names consistent. Note The server’s key ring file name appears in any Internet Site documents that you have configured, or, if Internet Site documents are not being used, on the Ports - Internet Ports tab of the Server document. If you specified a name other than the default, you need to edit the name where it appears - in the Internet Site documents or in the Server document. Enter the password for the key ring. Specify the key size Domino uses when creating the public and private key pairs. The larger the size, the stronger the encryption. Enter the server’s TCP/IP fully-qualified domain name — for example, www.acme.com. Set up the server certificate so that the common name matches the host name since some browsers check for this match before allowing a connection. Enter the name of the organization — for example, a company name, such as Acme. continued

Key Ring Password Key Size

Common name

Organization

46-4 Administering the Domino System, Volume 2

Security

Field Organizational Unit City or Locality

Action (Optional) Enter the name of certifier division or department. (Optional) Enter the organization city or locality.

State or Province Enter the full name of the state or province in which the certifier organization resides. Country Enter the two-character abbreviation of country in which organization resides

5. Click “Create Key Ring.” 6. After you read the information about the key ring file and distinguished name, click OK. Notes creates the key ring file and stash (.STH) file and places them in the Notes data directory on the client machine used to create the key ring.

7. Copy the key ring file and stash (.STH) file to the Domino data directory on the server. Caution You must ensure that the key ring password in the stash file is protected. The key ring file password is altered in the stash file so that it cannot be recognized by a casual observer, but it is not encrypted. You should not allow unauthorized persons access to either the stash file or the key ring file. In the normal course of operation, only the server itself should have access to those files; however, administrators may also need permission to remove or replace the files. As with all server resources, managing proper file permissions and protections is vital to the security of the system. 8. Request an SSL server certificate.

Requesting an SSL server certificate
When you request an SSL server certificate, you use Public-Key Cryptography Standards (PKCS) format, an industry-standard format that many CAs, including Domino, understand. Before you request a certificate from a third-party CA, make sure the CA uses the PKCS format, not some other format, such as Privacy-Enhanced Mail (PEM). If you are unsure of the format required by a third-party CA, check with that CA. A certificate request is essentially certificate data that has not been signed by a CA. The CA turns the request into a certificate by signing it. If you are requesting a server certificate from a server-based certification authority, you can use the Notes client to create the server key ring and the server certificate in the Certificate Requests database. You must be able to access the Domino server using the Notes client.
Setting Up SSL on a Domino Server 46-5

To request a server certificate using a Notes client

1. From the Notes client, open the Certificate Requests database for the certifier from which you want to request a server certificate. 2. Do the following to create a server key ring file to store the server certificate and merge the CA certificate as a trusted root into the server key ring file: a. In the Certificate Requests database, choose Domino Keyring Management - Create Keyring. b. In the Create Key Ring form, complete these fields:
Field File name Password Key size Action Enter a file name for the Key Ring file and keep the .kyr. Enter a password for the key ring file. Choose a key size.

Common name Enter the fully qualified host name — for example, server.company.com. Organization name State or province Country Enter the name of the certifier organization. Enter the full name of the state or province in which the organization is located. Enter a two-letter abbreviation for the country in which the organization is located.

c. Verify the information in the “Key Ring Created” dialog box, then click OK to automatically add the CA as a trusted root and generate a certificate request for the server. d. Verify the information in the “Merge Trusted Root Certificate Confirmation” dialog box and click OK. e. Click OK when the “Certificate received into key ring and designated as trusted root” confirmation dialog box appears. f. Click OK when the “Certificate Request Successfully Submitted for Key Ring” dialog box appears. After an RA approves the request for a server certificate, the CA issues a server certificate and sends notification that you can pick up the certificate. 3. In the Issued/Rejected Certificates view, open the issued server request and copy the Request ID to the Clipboard. 4. Choose Domino Key Ring Management - Pickup Key Ring Certificate. 5. Enter the key ring file name and password, paste the pickup ID into the form and click Pickup Certificate.
46-6 Administering the Domino System, Volume 2

Security

6. Verify the information in the “Merge Signed Certificate Confirmation” dialog box and click OK. 7. When the “Certificate received into key ring” dialog box appears, click OK. 8. Copy or use FTP (in binary mode) to transfer the new key ring and its associated .STH file to the server’s data directory. From a Domino CA using a Web browser This procedure for generating a server certificate request is the same regardless of whether you are requesting a server certificate from a Domino server-based certification authority or a Domino 5 certificate authority. 1. Make sure you already created the server key ring file and mapped a drive to the directory that contains the server key ring file. 2. From the Notes client, open the Domino Directory of the server on which you want to create SSL, and open the Server Certificate Admin application. 3. Click “Create Certificate Request.” 4. Complete these fields:
Field Key Ring File Name Log Certificate Request Enter The name of the server key ring file, including the path to the file Choose one: • Yes (default) to log information in the Server Certificate Admin application • No to not log information Method Choose Paste into form on CA’s site

5. Click Create Certificate Request. 6. Enter the password for the server key ring file. 7. Copy the certificate request to the system Clipboard (include the Begin Certificate and End Certificate lines), and click OK. 8. On the server, use one of these methods to browse to the Domino certificate authority application (the Certificate Requests application for a server-based certification authority, and the Domino Certificate Authority for a Domino 5 Certificate Authority) on the Domino server’s Web site: • If you use Microsoft Internet Explorer, use SSL (HTTPS) to connect to the application. You need to trust server certificate in order to use SSL to access the server. To install (and trust) the
Setting Up SSL on a Domino Server 46-7

server certificate, in the IE security alert dialog box click “View Certificate” - “Install Certificate,” and follow the instructions. To trust all site certificates certified by a given CA, click “Accept this authority in your browser” before accessing the server with SSL. This option is available in both the Certificate Requests and Domino Certificate Authority applications. • If you use Netscape, use SSL to connect to the application. Then use the instructions provided by the browser software to accept the site certificate. 9. Click “Request Server Certificate.” 10. Enter your name, e-mail address, phone number, and any comments for the CA. 11. Paste the certificate request into the dialog box, and then click “Submit Certificate Request.” 12. Merge the CA certificate as a trusted root. From a third-party CA 1. Make sure you already created the server key ring file. 2. From the Notes client, open the Server Certificate Admin application on server for which you want to set up SSL. 3. Click “Create Certificate Request.” 4. Complete these fields:
Field Key Ring File Name Log Certificate Request Enter The name of the server key ring file including the path to the file Choose one: • Yes (default) to log information in the Server Certificate Admin application • No to not log information Method Choose one: • Paste into form on CA’s site (recommended) • Send to CA by e-mail Note You must choose the paste option to submit a request to VeriSign, which doesn’t use PKCS format for requests sent by e-mail. If you choose “Send to CA by e-mail,” enter the CA’s e-mail address, and your e-mail address, phone number, and location.

5. Click “Create Certificate Request.” 6. Enter the password for the server key ring file.

46-8 Administering the Domino System, Volume 2

Security

7. If you selected “Paste into form on CA’s site” in Step 4, do the following: a. Copy the certificate request to the system Clipboard (include the Begin Certificate and End Certificate lines). b. Use a browser to visit the CA’s site, and then follow the instructions that the CA’s site provides for submitting a request for a new certificate. 8. Merge the CA certificate as a trusted root.

Merging a CA certificate as a trusted root
The server certificate must contain the CA certificate as a trusted root. The trusted root allows servers and clients that have a common CA certificate to communicate. Before you merge a server certificate signed by a CA, merge the CA certificate into your key ring file as a trusted root. From a Domino CA Note This procedure is the same regardless of whether you are using a Domino server-based certification authority or a Domino 5 certificate authority. 1. Make sure that you requested the server certificate and mapped a drive to the directory that contains the key ring file. 2. Browse to the certificate authority application (the Certificate Requests application for a server-based certification authority, and the Domino Certificate Authority for a Domino 5 Certificate Authority) on the Domino CA: • If you use Microsoft Internet Explorer, use HTTP to connect to the application. • If you use Netscape, use SSL to connect to the application. Then, use the instructions provided by the browser software to accept the site certificate. 3. Click “Accept This Authority in Your Server.” 4. Highlight the certificate text and copy it to the system Clipboard (include the Begin Certificate and End Certificate lines). 5. From the Notes client, open the Server Certificate Admin application. 6. Click “Install Trusted Root Certificate into Key Ring.” 7. Enter the name of the key ring file that will store this certificate. You specified this name when you created the server certificate request. 8. Enter the name that the key ring file will use to identify this certificate. If you leave this field blank, Domino uses the distinguished name of the certificate.
Setting Up SSL on a Domino Server 46-9

9. In the Certificate Source field, choose Clipboard. Paste the Clipboard contents into the next field. 10. Click “Merge Trusted Root Certificate into Key Ring.” 11. Enter the password for the key ring file, and then click OK. 12. Have the CA sign the server certificate. From a third-party CA View the default trusted roots in the key ring file to make sure the third-party CA’s certificate is not already included. If it is already included, you do not need to complete these steps. For more information, see the topics “Default Domino SSL trusted roots” and “Viewing SSL server certificates” later in this chapter. 1. Make sure that you requested the server certificate and mapped a drive to the directory that contains the key ring file. 2. Browse to the Web site of the CA and obtain the CA’s trusted root certificate. In most cases, the trusted root certificate is in a file attachment, or the certificate is available for you to copy to the Clipboard. 3. From the Notes client, open the Server Certificate Admin application. 4. Click “Install Trusted Root Certificate into Key Ring.” 5. Enter the name of the key ring file that will store this certificate. You specified this name when you created the server certificate request. 6. Enter the name that the key ring file will use to identify this certificate. If you leave this field blank, Domino uses the distinguished name of the certificate. 7. Do one of the following: • If you copied the contents of the CA’s certificate to the Clipboard in Step 2, choose Clipboard in the Certificate Source field. Paste the Clipboard contents into the next field. • If you received a file that contained the CA’s certificate in Step 2, detach the file to your hard drive and select File in the Certificate Source field. Enter the file name in the File name field. 8. Click “Merge Trusted Root Certificate into Key Ring.” 9. Enter the password for the key ring file, and then click OK. 10. Have the CA complete the procedure “Signing server certificates.”

46-10 Administering the Domino System, Volume 2

Security

Default Domino SSL trusted roots
Domino includes several trusted root certificates by default when you create a server key ring file. You do not need to merge a third-party CA’s certificate as a trusted root if it exists in the key ring file by default.
Trusted root certificate name Organization Organizational Unit Country Class 3 Public Primary Certification Authority Class 3 Public Primary Certification Authority Class 2 Public Primary Certification Authority Class 1 Public Primary Certification Authority Test CA Secure Server Certification Authority US

VeriSign International Server VeriSign, Inc. CA - Class 3

VeriSign Class 3 Public Primary Certification Authority VeriSign Class 2 Public Primary Certification Authority VeriSign Class 1 Public Primary Certification Authority VeriSign Test Certificate Authority RSA Secure Server Certificate Authority Netscape Test Certificate Authority RSA Low Assurance Certificate Authority

VeriSign, Inc.

US

VeriSign, Inc.

US

VeriSign, Inc.

US

VeriSign, Inc. RSA Data Security, Inc.

US US

Netscape Test CA Communications Corp. RSA Data Security, Inc. Low Assurance Certification Authority

US

US

Setting Up SSL on a Domino Server 46-11

Signing server certificates
The CA creates a digital signature over the server certificate request using the CA’s private key. This action creates a server certificate. Essentially, the act of signing the certificate request turns the request into a certificate. The server certificate is then considered valid. The method used to sign a server certificate depends on whether the certificate was issued by a Domino or third-party CA. For more information on how a Domino server-based certification authority signs certificates, see the chapter “Setting Up a Domino Server-Based Certification Authority.” For more information on how a Domino 5 certificate authority signs certificates, see the chapter “Setting Up a Domino 5 Certificate Authority.” Signing methods for third-party CAs will vary. If you choose to use a third-party CA, check with that CA for information about how they sign certificates.

Merging a server certificate into the key ring file
After you merge the CA’s certificate as a trusted root and the CA approves your server certificate request, merge the signed certificate into the server’s key ring file. From a Domino CA Note This procedure is the same regardless of whether you are requesting a server certificate from a Domino server-based certification authority or a Domino 5 certificate authority. 1. Make sure the CA signed the certificate and you mapped a drive to the directory that contains the server key ring file. 2. Obtain the server certificate by doing one of the following: • If the CA gave you the URL to use to pick up the certificate in the Domino Certificate Authority database, browse to the URL provided in the e-mail. or • Obtain the pickup ID from the CA, and then do the following: a. Open the Certificate Requests or Domino 5 Certificate Authority application with a browser. b. Click Pick Up Server Certificate. c. Enter the pickup ID and click “Pick Up Signed Certificate.”

46-12 Administering the Domino System, Volume 2

Security

3. Highlight the certificate text and copy it to the system Clipboard (include the Begin Certificate and End Certificate lines). 4. From the Notes client, open the Server Certificate Admin application. 5. Click “Install Certificate into Key Ring.” 6. Enter the file name for the key ring that will store this certificate. You specified this key ring file when you created the server certificate request. 7. In the Certificate Source field, choose Clipboard. Paste the Clipboard contents into the next field. 8. Click “Merge Certificate into Key Ring.” 9. Enter the password for the key ring file, and then click OK to approve the merge. 10. Configure the SSL port. From a third-party CA 1. Make sure the CA signed the certificate and you mapped a drive to the directory that contains the server key ring file. 2. Use the instructions provided by the CA to pick up the certificate. In most cases, the CA mails the certificate as a file attachment or gives you a URL to visit to copy and paste the certificate to the Clipboard. 3. From the Notes client, open the Server Certificate Admin application. 4. Click “Install Certificate into Key Ring.” 5. Enter the file name for the key ring that will store this certificate. You created this key ring file when you created the server certificate request. 6. Do one of the following: • If you copied the certificate to the Clipboard, choose Clipboard in the Certificate Source field. Paste the Clipboard contents into the next field. • If you received a file attachment that contains the certificate, detach the file to your hard drive, and then choose File in the Certificate Source field. Enter the file name in the File name field. 7. Click “Merge Certificate into Key Ring.” 8. Enter the password for the server key ring file, and then click OK to approve the merge. 9. Configure the SSL port.

Setting Up SSL on a Domino Server 46-13

SSL port configuration
The SSL protocol always provides an encrypted, integrity-checked, communications channel and authenticated server identity. SSL servers can be optionally configured to request various forms of client identity authentication. You must enable SSL on a protocol-by-protocol basis. Some Internet protocols do not support client certificate authentication. To set up a port for SSL authentication, do the following: 1. Configure the port. 2. Determine whether you require users to access the server using only SSL or both SSL and TCP/IP. If you are using Internet Site documents, you configure most SSL port parameters in the Internet Site document for each protocol. However, you must still configure the following settings in the Server document for each Internet protocol: TCP/IP port and status, SSL port and status. You must also specify whether you want to enforce server access settings for the TCP/IP port of a given protocol.

Using server authentication only
Server authentication encrypts data and authenticates server identity. To control access to databases on the server by user name, set up name-and-password authentication. To enable SSL for server authentication only: • • The server must have a certificate from a Domino or third-party CA. The clients must have the server’s CA certificate marked as a trusted root. Clients can also trust the SSL server certificate directly, by creating a cross-certificate for it. If you are using a Notes client, the Notes client must have a cross-certificate for the server CA or the SSL server’s certificate.

For more information on name-and-password authentication, see the chapter “Setting Up Name-and-Password and Anonymous Access to Domino Servers.”

46-14 Administering the Domino System, Volume 2

Security

Using client certificate authentication
In addition to the security provided by server authentication, client certificate authentication verifies the client’s identity through the use of Internet (x.509) client certificates. Using server and client certificate authentication, you can control access to databases by specifying individual client user names in the database ACLs. To enable SSL for client certificate authentication: • • • • Complete the above requirements for server authentication. The clients must have certificates from a Domino or third-party CA. The server must have the client’s CA certificate marked as a trusted root. Each client must have a Person document in the Domino Directory that contains the SSL public key from the client certificate.

For more information on setting up client authentication, see the chapter “Setting Up Clients for S/MIME and SSL.”

Configuring a port for SSL
You can configure a port to use only server authentication or to use both server and client authentication. If you are using Internet Site documents, see the chapter “Installing and Setting Up Domino Servers.” To configure a port for SSL in the Server document 1. From the Domino Administrator, click Configuration - Servers, and open the Server document. 2. Click the Ports - Internet Ports tabs.

Setting Up SSL on a Domino Server 46-15

3. Complete these fields:
Field SSL key file Enter The file name of the server key ring file that the server uses. Note Domino does not use this field for IIOP, which uses a separate key ring file. You cannot change the name of the IIOP key ring file.

SSL protocol Choose one: version • V2.0 only to allow only SSL 2.0 connections. • V3.0 handshake to attempt an SSL 3.0 connection. If this fails and the requester detects SSL 2.0, then attempts to connect using SSL 2.0. • V3.0 only to allow only SSL 3.0 connections. • V3.0 and V2.0 handshake to attempt an SSL 3.0 connection, but start with an SSL.2.0 handshake, which displays relevant error messages. Makes an SSL 3.0 connection, if possible. • Negotiated (default) to attempt an SSL 3.0 connection. If it fails, the server attempts to use SSL 2.0. Use this setting unless you are having connection problems caused by incompatible protocol versions. Note Domino does not use this field for HTTP. Accept SSL site certificates Choose one: • Yes to allow this server to accept the site certificate and use SSL to access an Internet server, even if the Domino server does not have a certificate in common with the Internet server. • No to not allow this server to accept site certificates. Choose one: Accept expired SSL • Yes to allow clients to access the server, even if the client certificates certificate is expired. • No to not allow clients to access the server with expired client certificates.

46-16 Administering the Domino System, Volume 2

Security

4. Click the tab for the protocol that you want to configure, and then complete these fields:
Field SSL port number Enter Enter the port number on which Domino listens for SSL requests. You configure this here regardless of whether you are using Internet Sites or the Web Configurations view. Note If you change the default port number, clients must change their configurations as well. The default port number is usually changed only if a firewall proxy uses the reserved port number. SSL port status Choose Enabled to allow SSL connections on the port. You configure this here regardless of whether you are using Internet Sites or the Web Configurations view. Note Since a Domino server can be either an SMTP server or an SMTP client, you have two choices for the SSL port status field. To set up a Domino server as an SSL-enabled SMTP server, choose Enabled in the SMTP Inbound field. Client certificate Choose one: • No to not use client authentication. • Yes to use client authentication. SMTP and IIOP do not support client authentication. Choose one: • No to not use name-and-password authentication. • Yes to use name-and-password authentication. Choose one: • Yes to allow anonymous access. You must choose Yes if you want users to connect using server authentication only. • No to prevent anonymous access. If you choose Yes for both Anonymous and Client certificate, Domino first tries to authenticate the client. If that fails, Domino tries to connect the user anonymously. If you choose Yes for Anonymous, Client certificate, and Name & password, Domino first tries to authenticate the client using the client certificate. If that fails, Domino tries to use name-and-password authentication. If that fails, Domino tries to connect the user anonymously. LDAP must be configured to allow anonymous SSL connections in order to do name lookups. IMAP, POP3, and SMTP do not support anonymous access.

Name & password Anonymous

Setting Up SSL on a Domino Server 46-17

For information on how Domino authenticates clients when anonymous, client authentication, and name and password are enabled, see the chapter “Setting Up Name and Password and Anonymous Access to Domino Servers.”

Requiring an SSL connection to a server
Require SSL connections when you want to make sure that clients use a secure connection to access databases on the server. You do this by redirecting connection requests that come in over the TCP/IP port to the SSL port. If you do not require an SSL connection, clients can use either SSL or TCP/IP to connect to the server. You can set up the redirection of TCP/IP to SSL for the HTTP, IMAP, and LDAP protocols only. POP3 and SMTP do not support the “Redirect to SSL” setting. You enable “Redirect to SSL” in one of two ways: • For Domino 6 servers, use a Web Site document for requiring SSL connections for HTTP clients. For IMAP and LDAP, you do this in the Server document. For all protocols on Domino 5 servers, configure this in the Server document.

To require SSL connections to a server in the Server document 1. From the Domino Administrator, click the Configuration tab, and open the Server document. 2. Click the Ports - Internet Ports tab. 3. Click the tab for the protocol for which you want to require SSL. 4. In the TCP/IP port status field, select “Redirect to SSL.” For individual databases You can also require clients to use SSL to connect to the server on a database-by-database basis, by configuring the requirement to connect with SSL in the database application itself. 1. Start the Notes client. 2. Select the database for which you want to force clients to use SSL. 3. Open the Database Properties box. 4. On the Basics tab, click Web Access: Require SSL connection.

46-18 Administering the Domino System, Volume 2

Security

Setting up database access for SSL clients
After you set up SSL on a Domino server, you must give the clients access to databases on the server. For anonymous users If you set up a client for server authentication only, you cannot enter the user’s name in a database ACL since the client does not use a user name to access the server. Instead, you add the entry Anonymous to database ACLs and design element access lists. If you do not specify Anonymous access, Domino gives anonymous users -Default- access. For client authentication If you set up a client for client and server authentication, you can control the client’s access to databases by adding the client’s name to database ACLs and design element access lists. You must use the first name listed in the User name field of the Person document for the client. For example, if a User name field contains the entries Alan Jones/Acme, ajones, Alan, AJ; add the name Alan Jones/Acme to the ACL and design element access lists. Alan Jones can authenticate with the server using any of the names listed, but Domino uses the first name in the User name field to verify entries in ACL and design element access lists. It is strongly recommended that the first name be in hierarchical name format. For more information, see the chapter “Controlling User Access to Domino Databases.”

SSL session resumption
SSL session resumption greatly improves performance when using SSL by recalling information from a previous successful SSL session negotiation to bypass the most computationally intensive parts of the SSL session key negotiation. HTTP is the protocol that benefits the most from SSL session resumption, but other Internet protocols may benefit as well. By default, the server caches information from the 50 most recently negotiated sessions. This number can be modified by setting the variable SSL_RESUMABLE_SESSIONS in the NOTES.INI file. Increasing that number may improve performance on servers that tend to carry large numbers of concurrent SSL sessions. SSL session resumption can be disabled by setting SSL_RESUMABLE_SESSIONS=1 on the server. SSL_RESUMABLE_SESSIONS has no effect on the Notes client. The Notes client will cache the most recent SSL session. Note You cannot configure SSL sessions to time out and expire.
Setting Up SSL on a Domino Server 46-19

Managing server certificates and certificate requests
Do the following to manage your server certificates and certificate requests: • • • • • View SSL server certificates Renew an expired certificate View requests for certificates Mark or unmark a CA’s certificate as a trusted root Change the password for the server key ring file

Viewing SSL server certificates
Each SSL server certificate contains this information: • • • • The expiration date. The default trusted roots that come with Domino do not have expiration dates. The distinguished name of the server that requested the certificate. The distinguished name of the CA that signed the certificate. The size of the public key. The size determines the strength of the encrypted public key.

To view an SSL server certificate 1. Map a network drive to the directory that contains the key ring file. 2. From the Notes client, open the Server Certificate Admin (CERTSRV.NSF) application. 3. Click “View & Edit Key Rings.” 4. Click “Choose Key Ring to Display.” 5. Enter the name of the key ring file that contains the certificates you want to view. 6. Enter the password for the key ring file. 7. Do one of these: • To view the server certificate, select a document in the Site Certificates category. • To view a trusted root certificate, select a document in the Certification Authorities category.

46-20 Administering the Domino System, Volume 2

Security

Renewing expired certificates
After a certificate expires, you can no longer use it to communicate with servers and clients. If you obtained a server certificate from a Domino certificate authority, request a new one. If you obtained a server certificate from a third-party certificate authority, you may be able to renew it by submitting a request to the third-party CA’s Web site, which often includes your user name, password, and a challenge phrase. If it is possible to renew your server certificate, this information is accepted and you will be prompted to renew. If you cannot renew your server certificate, you will have to submit a request for a new one.

Viewing requests for certificates
Server administrators can view information about certificate requests that they sent to a CA to keep track of the request. The request document tracks the method used to submit the certificate, date and time of the request, the key ring file for the certificate, information about the certificate, and, if used, the e-mail address to which the server administrator sent the request. To view certificate requests 1. From the Notes client, open the Server Certificate Admin application. 2. Click “View Certificate Request Log.” 3. Open the request document.

Marking or unmarking a CA’s certificate as a trusted root
Remove a CA’s certificate as a trusted root from the server certificate when you no longer want to communicate with servers and clients that use certificates signed by that CA. 1. Map a drive to the directory that contains the key ring file. 2. From the Notes client, click the Files tab, and open the Server Certificate Admin application. 3. Click “View & Edit Key Rings.” 4. Click “Choose Key Ring to Display.” 5. Enter the name of the key ring file that contains the certificates you want to view. 6. Enter the password for the key ring file.

Setting Up SSL on a Domino Server 46-21

7. In the Certification Authorities category, open the document that contains the certificate you want to edit. 8. Click one: • “Trust This Certificate” to mark a certificate as a trusted root. • “Do Not Trust This Certificate” to unmark a certificate as a trusted root. Domino marks the certificate as untrusted but does not remove the certificate from the database. To delete a certificate permanently from the key ring file, click Delete. After you delete the certificate, you cannot recover it. Instead, you must merge the certificate as a trusted root again. 9. Enter the password for the key ring file.

Changing the password for the server key ring file
1. From the Notes client, click the Files tab, and open the Server Certificate Admin application. 2. Click “View & Edit Key Rings.” 3. Click “Change Key Ring password.” 4. Enter the name of the key ring file, and then click OK. 5. Enter the current password, and then click OK. 6. Enter the new password of at least 12 alphanumeric characters, and then click OK.

Creating a self-certified certificate to test SSL certification
You can create a self-certified certificate to test the certificate procedure at your organization. Because this certificate is not certified by a CA, use it only for testing purposes. 1. From the Notes client, open the Server Certificate Admin application, and then click “Create Key Rings & Certificates.” 2. Click “Create Key Ring with Self-Certified Certificate.” 3. Complete these fields, and then click “Create Key Ring with Self-Certified Certificate”:
Field Key ring file name Key ring password Enter A file name with the extension .KYR. At least 12 case-sensitive, alphanumeric characters. continued 46-22 Administering the Domino System, Volume 2

Security

Field Common name Organization Organizational Unit City or Locality

Enter A descriptive name that identifies the server certificate — such as, Acme SSLCA. The name of the organization — for example, a company name, such as Acme. (Optional) Name of certifier division or department. (Optional) The organization city or locality.

State or Province Three or more characters that represent the state or province in which the organization resides — for example, Massachusetts. (For U.S. states, enter the complete state name, not the abbreviation.) Country A two-character representation of the country in which the organization resides — for example, US for United States or CA for Canada.

4. Copy the key ring file and stash (.STH) file to the Domino data directory of the server. 5. Configure the port for SSL. 6. Set up database access.

Modifying SSL cipher restrictions
SSL uses public, private, and negotiated session keys. Every SSL certificate has one pair of keys — a public key and private key — that are created when the SSL certificate is generated, and enable certificate owners to identify themselves over the network and to use S/MIME to encrypt and sign messages. Certificates contain only the public key. The private key is kept in the ID file for the Notes client, and is kept in the key ring in the case of the SSL server. The session key is negotiated during the handshake — the main purposes of the handshake are to generate the session key and to identify the server to the client and, optionally, the client to the server. The size of the session key is determined by the cipher being used. For example, the cipher RSA_WITH_RC4_128_MD5 uses a 128-bit session key. The cipher RSA_EXPORT_WITH_DES40_CBC_SHA uses a 40-bit session key. What ciphers are available are also limited by the size of the server’s public key. The RSA_EXPORT_ ciphers can only be used with 512-bit RSA keys and smaller. The RSA_EXPORT1024_ ciphers can only be used with 1024-bit RSA keys and smaller. Ciphers that do not contain the EXPORT designation do not have any RSA key size restrictions.

Setting Up SSL on a Domino Server 46-23

You can restrict the use of SSL ciphers for Internet protocols. You can specify the use of a 128-bit cipher only for the HTTP service, for example, to require users to access a server using a domestic browser version. If no configuration parameters are set, then there is no restriction on the SSL ciphers used for that protocol. There are three ways to configure SSL ciphers, depending on how you choose to configure Internet protocols on your Domino server: • • In an Internet Site document. If you use Internet Site documents, you can specify a different set of SSL cipher restrictions for each protocol. Through the Server document. However, if you use the Server document you can restrict SSL ciphers for HTTP only. You must use the NOTES.INI variable SSLCipherSpec to restrict ciphers for protocols other than HTTP. Through the NOTES.INI variable SSLCipherSpec. All SSL cipher settings configured in either Site documents or in the Server document will be superseded by the INI variable.

For information about changing SSL cipher restrictions in Internet Site documents, see the chapter “Installing and Setting Up Domino Servers.” To modify SSL cipher restrictions in the Server document 1. From the Domino Administrator, click Configuration and open the Server document in the Domino Directory. 2. Click Ports - Internet Ports - Web. 3. In the SSL Ciphers field, click Modify. This displays a list of available SSL cipher specifications. 4. Select the cipher specification(s), then click OK. 5. Save and close the document. To modify SSL cipher restrictions using the NOTES.INI file Use the NOTES.INI setting SSLCipherSpec to specify SSL restrictions for all protocols. Ciphers are specified by a 2-digit code. You can add as many ciphers as you need. For example, to enable 3DES and RC4128SHA ciphers, enter the following line in the NOTES.INI file:
SSLCipherSpec=050A

where 05 = 3DES and 0A = RC4128SHA. Caution Using SSLCipherSpec overrides all SSL cipher restrictions in Internet Site documents and in the Server document. For more information, see the appendix “NOTES.INI File.”
46-24 Administering the Domino System, Volume 2

Security

Authenticating Web SSL clients in secondary Domino and LDAP directories
When a Web client authenticates with a server, by default, the server checks the primary Domino Directory to see if the client certificate exists in the Person document. If your organization uses a secondary Domino Directory and/or an LDAP directory to verify client certificates, you can set up Domino to check those additional directories. To do so, you set up the secondary Domino and LDAP directories as trusted domains in the Directory Assistance database. When you mark the domain as trusted, Domino searches the primary Domino Directory for the user and then searches the trusted secondary Domino and LDAP directories. When you set up directory assistance, you specify the order in which Domino searches the secondary directories. In addition, Domino checks the primary Domino Directory and secondary directories you trust when you add SSL client certificates to the Domino Directory using the Domino Certificate Authority application. You cannot, however, add client certificates to an LDAP directory even if the LDAP directory is set up on a Domino server. It is recommended that you use SSL to secure information sent between the server and the LDAP directory server. For information on adding client certificates to the Domino Directory and using SSL to secure LDAP directory lookups, see the chapter “Setting Up Clients for S/MIME and SSL.” For information on using SSL for LDAP directory lookups, see the chapter “Setting Up Directory Assistance.” The hierarchical name returned by the Domino Directory or LDAP directory is checked against the trusted rule in the Directory Assistance database to verify that the organization and organizational units match the specified rule. For example, if the user name returned is Dave Lawson/Acme, the Directory Assistance document must include the rule */Acme. Searching multiple directories is also available for authenticating users who use name-and-password authentication. For more information on setting up secondary Domino and LDAP directory authentication of SSL clients, see the chapter “Setting Up Directory Assistance.”

Setting Up SSL on a Domino Server 46-25

Security

Chapter 47 Setting Up Clients for S/MIME and SSL
This chapter describes how to set up a Notes client to use SSL and send secure S/MIME messages. It also describes how to set up an Internet client to use SSL to connect to a Domino server.

SSL and S/MIME for clients
Clients can use a Domino certificate authority (CA) application or a third-party CA to obtain certificates for secure SSL and S/MIME communication.

Authenticating clients and servers using SSL
Notes and other Internet clients use the SSL protocol to encrypt data, authenticate server identity and, optionally, authenticate client identity when a Notes or other Internet client connects to an Internet server — for example, a Web server or an LDAP server. On the server, SSL is set up on a protocol-by-protocol basis. You can enable SSL on all protocols or enable SSL on some protocols but not others. For example, you can enable SSL on mail protocols (IMAP, POP3, SMTP) and disable it for HTTP. Server authentication lets clients verify the identity of the server to which they are connecting, to make sure that another server is not posing as the server they want to access. Client certificate authentication lets server administrators identify the client accessing the server and control access to applications based on that identity. For example, if you want Alan Jones to have Editor access to a database and all others accessing the database to have no access, you can set up the application database ACL to include Alan Jones as an Editor and Anonymous as No Access.

47-1

Notes and other Internet clients that use client certificate authentication have an Internet certificate that is stored in the Notes ID file for Notes client, and in a local file for Internet clients. The certificate includes a public key, a name, an expiration date, and a digital signature. The corresponding private key is stored in the ID file, but is stored separately from the certificate. For Notes clients, the client certificate is also stored in the Domino Directory so that others can access the public key. Notes and Internet clients can obtain Internet certificates from either a Domino certification authority or a third-party certifier. How you set up the client depends on whether the server requires client certificate authentication. As an administrator, you should carefully consider whether you want to require client certificate authentication. If you do not need to identify Internet users who access the server, you do not need to set up client authentication. In fact, in some cases, requiring an Internet certificate may deter users from accessing a server — for example, a server that hosts a Web site. If you require an Internet certificate, users need to perform additional steps to obtain the certificate and set up client certificate authentication. Note By enabling the setting “Accept SSL Site Certificates” in the Location record, the Notes client can ignore cross-certificates and server authentication entirely. The user can also choose to create cross-certificates on the fly when connecting to a server using SSL.

Securing messages with S/MIME
S/MIME is a protocol used by clients to sign mail messages and send encrypted mail messages over the Internet to users of mail applications that also support the S/MIME protocol — for example, Microsoft Outlook Express and Netscape Communicator. The Notes client uses the public key stored in the Internet certificate in the Personal Address Book, Domino Directory, or LDAP directory to encrypt messages. Encrypted mail messages cannot be read by unauthorized users while the message is in transit. Electronically signed messages show that the person who signed the message had access to the private key associated with the certificate stored in the signature. For more information on S/MIME signatures and encryption, see the chapter “Encryption and Electronic Signatures.”

47-2 Administering the Domino System, Volume 2

Security

Setting up Notes and Internet clients for SSL authentication
You can set up Notes or other Internet clients for server authentication to encrypt data and authenticate the server identity when connecting to an Internet server. You do not need an Internet certificate if you set up a client for server-only authentication. On the server, SSL is set up on a protocol-by-protocol basis. You can choose to enable SSL on all protocols, or enable SSL on some protocols but not others. For example, you can enable SSL on mail protocols (IMAP, POP3, SMTP) and disable it for HTTP. You must also enable the port for anonymous access; otherwise, Domino requires an Internet certificate or a name and password from the client. To access an Internet server using SSL, clients must have: • • • Software, such as a Web browser or a Notes client, that supports SSL. A trusted root certificate from a Domino or third-party certifier. (Notes client only) A cross-certificate created using the trusted root certificate for the Domino or third-party certifier. The trusted root certificate is no longer necessary after you create a cross-certificate.

Note Secure transactions are indicated by the use of the term https:// in URLs for SSL-secured sites. A browser user can specify this when initiating a secure transaction. More likely, the user will navigate to a login page, where it is necessary to log in with a name and password in order to access the secure Web page.

Obtaining a trusted root certificate for SSL authentication
The copy of the CA’s certificate is called a trusted root certificate. After obtaining the trusted root certificate and — if you are using a Notes client — an Internet cross-certificate for the root certificate, the client will trust the CA and by extension, any certificates issued by this CA. If you are setting up server authentication for an Internet client, you add this trusted root to a local file. If you are setting up server authentication for a Notes client, you add this trusted root to a Domino Directory that users can access to generate a cross-certificate in their Personal Address Book. Notes clients can also obtain a trusted root certificate and cross-certificate to gain access to the server; however, adding the trusted root certificate to the Domino Directory simplifies the process of setting up server authentication for users.

Setting Up Clients for S/MIME and SSL 47-3

Note A users can accept certificates automatically, without having to obtain the roots or cross-certificates, by enabling the option “Accept site certificates” in the location document for the Notes client. However, accepting certificates from unknown servers is a security risk. If a user doesn’t know the sources of the certificates being accepted, it is possible to accept certificates from malicious sources. To obtain a trusted root certificate for a Notes client 1. Make sure that you have a trusted root certificate for the CA. In the Domino Administrator, click Configuration - Certificates Certificates, and view the certificate in the Internet Certifiers category. 2. Instruct clients to complete the procedure “Creating an Internet cross-certificate for a CA.” To obtain a trusted root certificate for an Internet client You can use the following procedures to obtain a trusted root certificate for an Internet client. If the trusted root certificate is for a Domino CA, the Internet client performs these steps: 1. Browse to the Domino Certificate Requests (for Domino 6) or Certificate Authority (Domino 5) application. 2. Select “Accept This Authority In Your Browser.” Note If you use an SSL connection to browse to the application, the server prompts you to accept the site certificate. Check the CA properties to make sure that the certificate that is presented is from a source you trust before accepting the certificate as a trusted root. If the trusted root certificate is for a third-party CA, the Internet client follows the third-party CA’s established procedure to merge the trusted root certificate for the CA. If both the client and server have certificates issued from the CA or already have a CA in common, then this step is not necessary.

Creating an Internet cross-certificate for a CA
Before a Notes client can authenticate servers or send secure S/MIME messages, the client must first create a cross-certificate for the CA server and store it in the Personal Address Book. This allows the Notes client to trust servers or clients that have certificates issued by that CA. The client uses a trusted root certificate to create the cross-certificate. Once the cross-certificate is created, the client no longer needs the trusted root certificate.

47-4 Administering the Domino System, Volume 2

Security

SSL server authentication for Internet clients other than Notes does not require a cross-certificate. A Notes client can also create a cross-certificate for a server or client; however, this allows the Notes client to trust only that server or client. The Notes client does not then trust other servers and clients with certificates issued by a CA. To create an Internet cross-certificate 1. Make sure the CA created a trusted root certificate in the Domino Directory. 2. Instruct clients to retrieve an Internet cross-certificate through the User Security dialog box. For information on how Notes users can retrieve Internet cross-certificates, see Lotus Notes 6 Help. To view Internet cross-certificates Notes users can view the Internet cross-certificates contained in their Personal Address Book. For information on how Notes users can see their Internet cross-certificates, see Lotus Notes 6 Help.

Internet certificates for SSL and S/MIME
Before Internet and Notes clients can use client authentication or send signed mail, they must have an Internet certificate. To send encrypted mail using S/MIME, they must have the recipient’s Internet certificate. You need to complete these steps for Internet and Notes clients who are creating new public and private keys for the Internet certificate. You do not need to complete these steps if you are using a Notes client and the CA issued certificates in the Person document of the Domino Directory. Notes automatically adds Internet certificates stored in the Person document to the Notes ID file when the user authenticates with the server. You can also set up Notes clients to use different certificates for signing and encryption. You designate one Internet certificate authentication and signing, and another for encryption. For more information, see the topic “Dual Internet certificates for S/MIME encryption and signatures” later in this chapter.

Setting Up Clients for S/MIME and SSL 47-5

To obtain an Internet certificate for a Notes client
The procedure that Notes clients follow to request an Internet certificate is same whether a Domino CA or third-party CA is issuing the certificates. 1. Have users request an Internet certificate. 2. The CA approves the request, and Domino automatically adds the client’s Internet certificate to the user’s Person document. 3. Have users merge the Internet certificate into their ID file. For information on how Notes users request and merge Internet certificates, see Lotus Notes 6 Help. You can also issue Internet certificates for Notes clients without requiring them to submit an Internet certificate request. See the topic “Issuing Internet certificates in a Person document” later in this chapter.

To obtain an Internet certificate for an Internet client
The procedure you follow to request an Internet certificate depends on whether you want to request a certificate from a Domino CA or a third-party CA. Domino CA 1. If you are using a Domino server-based certification authority, browse to the Certificate Request application. If you are using a Domino 5 certificate authority, browse to the Domino Certificate Authority application. • If you use Microsoft Internet Explorer, use HTTP without SSL to connect to the Certificate Authority application. Internet Explorer does not allow you to accept site certificates into your browser. • If you use Netscape, use SSL to connect to the Domino Certificate Authority application. When the browser asks whether you want to accept the server certificate as a trusted root, follow the steps provided by the browser to accept the certificate. 2. Click “Request Client Certificate” in the left pane. 3. Enter your name and organizational information. This information will appear on your Internet certificate. 4. Enter any additional contact information that you want to send to the CA. 5. Enter the size for the public and private keys. The larger the number, the stronger the encryption. 6. Click “Submit Certificate Request” to send the request to the CA.
47-6 Administering the Domino System, Volume 2

Security

Third-party CA The third-party CA determines how you request an Internet certificate. Browse to the third-party CA’s site, and enter the certificate request. A dialog box appears that allows you to request the certificate.

Signing an Internet client certificate and adding the certificate to the Domino Directory
When a CA signs an Internet client certificate, the CA adds a digital signature to the certificate and, if you are using a Domino CA, adds the public key to the Domino Directory. If you are using a third-party CA, you must complete additional steps to add the public key to the Domino Directory. You do not need to complete these steps if you are using a Notes client and the CA issued certificates in the Person document of the Domino Directory. Notes automatically adds Internet certificates stored in the Person document to the Notes ID file when the user authenticates with the server. The steps you follow to sign and add an Internet client certificate to the Domino Directory depend on whether the certificate is issued from a Domino server-based certification authority, a Domino 5 Certificate Authority, or a third-party CA. Before you approve client certificates for signing: • Make sure you understand your organization’s policy on signing certificates. Sign client certificates for clients if the certificate requests comply with your organization’s security policy. Make sure you have the Administration Process set up on the server. If you are signing a certificate for an Internet client, make sure you created a Person document.

Domino server-based certification authority The steps are completed by the Domino CA. You must be a registration authority (RA) to approve client certificates for signing. 1. From the Domino Administrator, click Files, and open the Domino Certificate Requests application. 2. Transfer the certificate request into the Administration Requests database. a. In the Certificate Requests database, open the Pending/Submitted Requests view. Press F9 to refresh the view if the client request does not appear there.

Setting Up Clients for S/MIME and SSL 47-7

b. If the view shows that the request has been “Submitted to Administration Process,” go to the next step. If it is still in the Pending state, highlight the request and click “Submit Selected Requests.” c. You should see a “Successfully submitted 1 request(s) to the Administration Process” message. Click OK. 3. Approve or deny the request. a. Open the Administration Requests database (ADMIN4.NSF), open the Certification Authority Requests/Certificate Requests view, and find the new client request. b. Open the request and verify the information in it. c. Click Edit Request, and then click Approve Request or Reject Request. Press F9 to make sure that the request changes state, from New to Approved (or Rejected). 4. Transfer the certificate request out of the Administration Requests database. a. Close the Administration Requests database and return to the Certificate Requests database. b. Open the Issued/Rejected Certificates view and locate the client request (you may need to refresh the view). 5. Notify the user who requested the client certificate. a. If you enabled the option for e-mail confirmation upon completion of the client request, then the once, the CA automatically notifies the requester to pick up the certificate. If it is denied, it sends the requester e-mail indicating that the request was rejected. b. If you did not enable the option for e-mail confirmation upon completion of the client request, then you need to click “Send Confirmation Mail” to notify the requester of the outcome. Note If the Certificate Requests database is configured for automatic request processing, then client requests are sent to the Administration Requests database automatically by the database. The Registration Authority only to approve or reject the request. Domino 5 Certificate Authority The Internet certificate request appears in the Client Certificate Requests view in the Domino Certificate Authority application. When the CA signs a certificate, the CA can automatically send e-mail to the client. This e-mail describes where to pick up the certificate and includes a pickup ID, which the client must use to identify the certificate during the pickup process. Domino automatically generates the pickup ID.
47-8 Administering the Domino System, Volume 2

Security

Note The steps below apply to signing client certificates issued by a Domino CA. The steps are completed by the Domino CA. 1. From the Domino Administrator, click Files, and open the Domino Certificate Authority application. 2. Click “Client Certificate Requests” in the left pane. 3. Open the request you want to sign. 4. Review the user information and distinguished name. Make sure the information provided complies with your organization’s security policy. 5. Leave the option “Register certificate in the Domino Directory” selected to add the client’s public key automatically to the Person document. If you want to deny the request, complete step 6. Otherwise, go to step 7. 6. To deny the request: a. Enter a reason for the denied request. b. If you do not want to send the person e-mail, deselect “Send a notification e-mail to the requester”; otherwise, the Domino Certificate Authority application sends the person e-mail indicating that you denied the request and the reason why you denied the request. c. Click Deny. 7. To approve the request: a. Enter a validity period. For short-term projects, 90 days is typical; for ongoing projects, you can enter several years. b. If you do not want to send the client e-mail indicating that the client can now pick up the certificate, deselect “Send a notification e-mail to the requester”; otherwise, the Domino Certificate Authority application sends an e-mail with a URL indicating the location to pick up the certificate. c. Click Approve and enter the password for the CA key ring file. This places a request in the Administration Requests database. When the Administration Process next runs, it processes the request and adds the certificate to the client’s Person document in the Domino Directory. Note The client cannot use the certificate to authenticate against database ACLs until the Administration Process completes the request.

Setting Up Clients for S/MIME and SSL 47-9

Third-party CA If a user obtains an Internet certificate from a third-party CA using the Notes client, the certificate is automatically added to their Person document. If a user obtains an Internet certificate from a third-party CA through a browser, the certificate must then be added to their Person document. For more information, see the topic “Publishing third-party CA client certificates in a Person record” later in this chapter.

Issuing Internet certificates in a Person document
If you need to issue Internet certificates for Notes clients and you do not want to require each user to submit an Internet certificate request and merge the certificate into the ID file, you can issue the Internet certificate using the existing public and private keys in the Notes ID file and add it to the user’s Person document. Using the Domino Directory to issue Internet certificates simplifies the process of distributing Internet certificates to users. The server on which you issue Internet certificates must be set up for the Administration Process, and the users must have an Internet address specified in their Person documents. In addition, you must add Internet certificates that are created using a Domino certifier. To issue an Internet certificate in a Person document 1. Make sure you have the Administration Process set up on the server. 2. From the Domino Administrator, click People & Groups. 3. Select the names of the users who need Internet certificates. 4. Choose Actions - Add Internet Cert to Selected People. 5. Check to make sure that the name of the correct registration server appears at the top of the dialog box next to the Server button. If it does not, click Server to choose the correct registration server. 6. Choose whether to supply the certifier key ring file and password, or to use the CA process. • If you choose to supply the certifier key ring file and password, select the CA’s key ring file, and when prompted, enter the password. • If you choose to use the CA process, choose a certifier from the drop-down list. 7. In the “Add Internet Certificates to Selected Entries” dialog box, confirm that the expiration date is valid. If not, enter the correct date. 8. Click Certify.
47-10 Administering the Domino System, Volume 2

Security

9. The certifier processes the request. If you chose to provide a certifier ID, Domino creates a certificate for each selected user and stores it in an “Add Internet Certificate to Person Record” request in the Administration Request database. If you chose to use the CA process, a certificate request is created in the Administration Request database for each selected user. When the CA processes the request, it creates the “Add Internet Certificate to Person Record” request. a. When the Administration Request database replicates with the Domino Directory’s administration server, the Administration Process places the certificate in the user’s Person document. b. After the Domino Directory replicates with the user’s mail server and the user subsequently accesses the mail server, Notes recognizes there is a certificate in the Domino Directory that is not in the user’s ID file. Notes automatically places the Internet certificate in the user’s ID file.

Exporting and importing Internet certificates
Users can only use Internet certificates in the browser in which they requested them. However, you can export Internet certificates from a Person document and make them available to other users. You can also import other’s Internet certificates into Person documents in the Domino Directory. You can also import and export Internet certificates for use between other Internet applications, such as Microsoft Outlook. To export an Internet certificate from a Person document 1. From the Domino Administrator, click People & Groups, and open the People view. 2. Open the Person document from which you want to export Internet certificates. 3. Click Action - Export Internet Certificates. 4. In the Export Internet Certificates dialog box, select the certificate that you want to export from the list box and click OK. 5. In the Select Export File Format dialog box, choose the file format in which to save the exported certificate, and click OK. The default is PKCS 12 encoded. 6. In the Export Options dialog box, enter a user-friendly name for the exported file. Domino will suggest a default name.

Setting Up Clients for S/MIME and SSL 47-11

7. In the “Password for Export File Containing Internet Certificates,” enter a password to protect the export file. If you choose not to assign a password to this file, click No Password. However, it is highly recommended that you assign a password to protect this information. 8. In the Specify Export File dialog box, choose the directory path and file name for the file that contains the exported certificates, and click OK. The certificates are successfully exported to the specified file. 9. Note the file name and password of the exported file for future reference. To import an Internet certificate into a Person document 1. From the Domino Administrator, click People & Groups, and open the People view. 2. Open the Person document for which you want to import Internet certificates. 3. Click Action - Import Internet Certificates. 4. In the Specify Export File dialog box, choose the directory path and file name for the file that contains the exported certificates, and click OK. Note that the file may not appear with the assigned file extension. It is recommended that you choose the all files option in the “Files of type” field to ensure that the exported files are displayed in the file selection list box. 5. In the Select Import File Format dialog box, choose the file format in which to save the imported Internet certificate, and click OK. The default is PKCS 12 encoded. 6. In the “Enter Password” dialog box, enter the file password. 7. In the “Import Internet Certificates” dialog box, choose the Internet certificate that you want to import, if there is more than one. Or you can click “Accept All” to import all certificates in the file.

Viewing and deleting Internet certificates
When you no longer want an Internet client to use SSL client authentication to access a Domino server or a Notes client to send S/MIME encrypted mail to a specified recipient, delete the Internet certificate from the Internet client’s Person document or the specified recipient’s Person document in the Domino Directory. The client still has the Internet certificate, but without the Internet certificate in the Person document, the Internet client cannot use client authentication to access a Domino server, and the Notes client cannot send S/MIME encrypted mail to the specified recipient.

47-12 Administering the Domino System, Volume 2

Security

An Internet client can still access the Domino server anonymously if you have anonymous access set up on the server, or use name-and-password authentication to access the server. A Notes client can still send unencrypted mail messages to the user. You can also view information about Internet certificates in the Domino Directory. To view or delete an Internet certificate 1. From the Domino Administrator, click People & Groups, and edit the Person document for the Internet user whose certificate you want to view or delete. 2. Click Examine Internet Certificate(s). 3. To delete the Internet certificate, select the certificate and click Delete. Note that the certificate will remain displayed until you exit or save the document.

Setting up Notes clients for S/MIME
You can set up a Notes client to use S/MIME encryption and electronic signatures when sending mail to other users of mail applications that support S/MIME. For information on selecting MIME format for sent mail, see the chapter “Encryption and Electronic Signatures.” Setting up Notes clients to send encrypted messages Notes clients need the following to send encrypted messages: • The recipient’s Internet certificate stored in the Personal Address Book, Domino Directory, or LDAP directory. If the Internet certificate is stored in a Domino Directory in another domain or in an LDAP directory, the directory needs to be accessible using directory assistance. A cross-certificate issued for either the recipient or the CA that issued the recipient’s Internet certificate. This cross-certificate must be stored in the client’s Personal Address Book. Note It is not necessary to have the cross-certificate prior to sending S/MIME encrypted mail. Users will be prompted to generate the cross-certificate when they try to send the message. For more information, see the topic “Adding a recipient’s Internet certificate and cross-certificate for encrypted S/MIME messages” later in this chapter.

Setting Up Clients for S/MIME and SSL 47-13

Setting up Notes clients to decrypt encrypted messages and send signed messages To decrypt sent messages and send signed messages, Notes clients need an Internet certificate stored in the Notes ID file. For more information, see the topic “Creating Internet certificates for Notes S/MIME clients” later in this chapter. Setting up Notes clients to verify signed messages To verify the signature on a signed message, Notes clients need a cross-certificate issued for either the sender of the message or the CA that issued the sender’s Internet certificate. This cross-certificate must be stored in the client’s Personal Address Book. For information on creating cross-certificates, see the topic “Creating an Internet cross-certificate for a CA” later in this chapter.

Creating Internet certificates for Notes S/MIME clients
The procedure you complete to create Internet certificates is the same, whether you use Domino or a third-party CA to issue the certificates. To set up Notes clients with certificates for S/MIME The CA and client complete these steps to add a Domino Internet certificate to the Notes ID file. A Notes client can use one Internet certificate or use dual Internet certificates for S/MIME encryption and signatures. 1. Before issuing certificates, the CA must determine if Internet certificates should be created using the existing public and private keys from the Notes ID file or if the CA wants to issue certificates based on new keys generated from a browser certificate request. If clients use a browser that supports PKCS #12, clients can also import an existing Internet certificate into the Notes ID file. Depending on the environment, the administrator may choose to use a combination of these options for different users. For more information on importing Internet certificates in a Notes client, see Lotus Notes 6 Help. 2. The CA adds a trusted root certificate to a Domino Directory that the client can access. The client can also add a trusted root certificate to the Personal Address Book; however, adding a trusted root certificate to the Domino Directory simplifies the process of setting up Notes clients for S/MIME because the trusted root is accessible to many clients. 3. The client creates a cross-certificate using the trusted root certificate for the CA and stores it in the Personal Address Book.
47-14 Administering the Domino System, Volume 2

Security

4. To create a certificate using the existing public and private keys in the Notes ID file, do the following: a. The CA adds an Internet certificate to the Person document. b. The client authenticates with the home server. Notes automatically merges the Internet certificate into the ID file. 5. To use new public and private keys to create an Internet certificate, do the following: a. The client requests the Internet certificate from the CA. b. The CA approves the request, and Domino automatically adds the client’s Internet certificate to the user’s Person document. c. The client merges the Internet certificate into the ID file. For more information on how Notes clients merge Internet certificates into their ID files, see Lotus Notes 6 Help.

Adding an Internet certificate and cross-certificate for encrypted S/MIME messages
To send an S/MIME-encrypted message, the sender must have the recipient’s Internet certificate in the Personal Address Book, Domino Directory, or LDAP directory. The sender must also have a cross-certificate issued for the recipient or for the certifier who issued the recipient’s Internet certificate. If a cross-certificate is issued for a recipient’s Internet certificate, only messages to that recipient can be encrypted. If a cross-certificate is issued to the recipient’s CA, you can send encrypted messages to all recipients who have certificates issued by that CA, if you have the recipients’ Internet certificates. If the Internet certificate is stored in a Domino Directory in another domain or in an LDAP directory, the directory needs to be accessible using directory assistance. To add an Internet certificate and cross-certificate for encrypted S/MIME messages 1. The recipient must send an S/MIME signed message to you. For information on signing mail, see Lotus Notes 6 Help.

Setting Up Clients for S/MIME and SSL 47-15

2. When you open the signed message, Notes asks if you want to add a cross-certificate if you do not already have a cross-certificate issued for either the author or the CA who issued the certificate to the author. Complete these fields and then click Cross Certify:
Field Certifier Enter The certifier ID that is cross-certifying the certificate. By default, the certifier is your ID. If you have access, you can choose an ID that is higher in the hierarchical name scheme. The registration server that holds the cross-certificate that is created. By default, it is stored locally in your Personal Address Book. Do not change this setting, since the cross-certificate must be stored in your Personal Address Book in order to validate the Internet certificate of the person to whom you are sending an encrypted message. The certificate that is being cross-certified. You can choose to cross-certify the sender of the signed message or you can cross-certify the CA that issued the certificate to the sender. If a cross-certificate is issued to the sender of the signed message, you can encrypt messages to only that person. If a cross-certificate is issued to the sender’s CA, you can send encrypted messages to anyone who has an Internet certificate issued by that CA and for whom you have an Internet certificate. Alternate names attached to the ID, if any. The date that the cross-certificate expires.

Server

Subject name

Subject alternate name list Expiration date

3. To add the author’s Internet certificate to the Personal Address Book, choose Tools - Add Sender to Address Book. Notes creates a Contact document for the person and adds an Internet certificate to the document. For information on adding an Internet certificate and cross-certificate when users have dual certificates, see the topic “Dual Internet certificates for S/MIME encryption and signatures” later in this chapter.

47-16 Administering the Domino System, Volume 2

Security

Dual Internet certificates for S/MIME encryption and signatures
You can add two Internet certificates to your Notes ID file and then use one certificate for S/MIME encryption and another for S/MIME signatures and SSL client authentication. Doing so lets you maintain separate public and private key pairs for encryption and electronic signatures and SSL client authentication.

Adding multiple certificates
To add multiple Internet certificates to your Notes ID file when the certificates are issued by different CAs, follow the procedure provided by the CA. If the Internet certificates you want to add are issued by the same CA, add one of the certificates by following the CA’s procedure and add the second certificate by importing it into the ID file. If you try to add multiple Internet certificates issued by the same CA and you do not import the certificate, Notes uses the last certificate added to the ID file for S/MIME encryption and signatures. For information on importing certificates, see Lotus Notes 6 Help.

Specifying the default signing certificate
Once the Internet certificates are added to the ID file, you can specify a default certificate to use for S/MIME signatures. You specify this certificate in the User Security dialog box. If the Internet certificate you select is used for both signatures and encryption, then Notes uses this certificate as the default for signatures and encryption. Otherwise, Notes uses the Internet certificate you specify for signatures and the last Internet certificate added to the Notes ID file for encryption. The default signing certificate is also the certificate used for SSL client authentication. For information on specifying a default signing certificate, see Lotus Notes 6 Help.

Adding an Internet certificate to the Personal Address Book
If you send a signed message and you have two different certificates for signatures and encryption, Notes sends the recipient the default Internet certificates used for encryption and signatures. When the recipient chooses Tools - Add Sender to Address Book, Notes adds a Contact document and adds the Internet certificates for encryption and signatures to the Contact document. When you send an encrypted message, Notes extracts only the Internet certificate for encryption from the Contact document.

Setting Up Clients for S/MIME and SSL 47-17

Adding a cross-certificate on demand
When a recipient receives a signed message, Notes checks the Personal Address Book for a cross-certificate that indicates that the signing certificate included with the message is trusted. If the cross-certificate is not present, Notes displays a dialog box that allows the recipient to cross-certify “on demand.” You can create a cross-certificate to either the leaf certificate or to the CA. Creating a cross-certificate to a leaf certificate indicates trust for only the owner of the certificate, in this case the sender of the signed message. A cross-certificate to a CA indicates trust for all people who have a certificate issued by that CA. When you cross-certify on demand, Notes creates a cross-certificate for the signing certificate, but does not create a cross-certificate for the encryption certificate. However, if the signing and encryption certificates are issued from the same CA and you create a cross-certificate for the CA, the cross-certificate created for the signing certificate can also be used to validate the encryption certificate. If the signing and encryption certificates are issued from different CAs, then you must create a cross-certificate for the CA that issued the encryption certificate before you can send an encrypted message. For more information on adding an Internet certificate and creating a cross-certificate on demand, see the topic “Adding a recipient’s Internet certificate and cross-certificate for encrypted S/MIME messages” in this chapter.

Setting up Notes and Internet clients for SSL client authentication
You can set up a Notes or Internet client for client authentication with a server. You cannot use client authentication for SMTP and IIOP connections. For SSL client authentication, the Notes or Internet client must have: • • • An Internet certificate issued by a Domino or third-party certifier. A trusted root certificate for a Domino or third-party certifier. (Notes clients only) A cross-certificate for the Domino or third-party certifier created from the trusted root certificate. The trusted root certificate is not necessary for Notes clients after you create the cross-certificate. Software, such as a Web browser or a Notes workstation, that supports the use of SSL.

47-18 Administering the Domino System, Volume 2

Security

If an LDAP client supports the Simple Authentication and Security Layer protocol (SASL), Domino automatically uses this protocol when the client uses SSL client authentication to connect to the server. SASL is not supported for TCP/IP connections or SSL connections with only server authentication. To set up Notes clients with certificates issued by a Domino CA The CA and client complete these steps. 1. Before issuing certificates, the CA must determine if Internet certificates should be created using the existing public and private keys from the Notes ID file or if the CA wants to issue certificates based on new keys generated from a browser certificate request. If clients use a browser that supports PKCS #12, clients can also import an existing Internet certificate into the Notes ID file. Depending on the environment, the administrator may choose to use a combination of these options for different users. 2. The CA adds a trusted root certificate to a Domino Directory that the client can access. The client can also add a trusted root certificate to the Personal Address Book; however, adding a trusted root certificate simplifies the process of setting up Notes clients for SSL because the trusted root is accessible to many clients. 3. The client creates a cross-certificate using the trusted root certificate for the CA and stores it in the Personal Address Book. 4. To create a certificate using the existing public and private keys in the Notes ID file: a. The CA adds an Internet certificate to the Person document. b. The client authenticates with the home server. Notes automatically adds the Internet certificate to the ID file. 5. To use new public and private keys to create an Internet certificate, do the following: a. The client requests the Internet certificate from the CA. b. The CA approves the request, and Domino automatically adds the client’s public key to the user’s Person document. c. The client merges the certificate into the ID file. d. The CA adds an Internet certificate to the user’s Person document.

Setting Up Clients for S/MIME and SSL 47-19

To set up Internet clients with certificates issued by a Domino CA 1. The CA administrator creates a Person document for the Internet client. 2. The client obtains the trusted root certificate for the server’s CA. 3. The client requests the Internet certificate from the CA. 4. The CA approves the request, and Domino automatically adds the client’s public key to the user’s Person document. 5. The client merges the certificate into the local file. To set up Notes and Internet clients with certificates issued by a third-party CA The CA and client complete these steps. 1. (Internet clients only) The CA administrator creates a Person document for the client. 2. Using any browser, the client follows the third-party CA’s established procedure to request and merge the Internet certificate. For example, to obtain an Internet certificate from VeriSign, visit the site http://digitalid.verisign.com and follow the instructions provided. 3. The Internet client follows the third-party CA’s established procedure to merge the trusted root certificate for the CA. 4. The CA adds the client’s public key to the Person document.

Setting up a Person document for an Internet user using SSL client authentication
In the Domino Directory on your Domino server, set up a Person document for Internet clients using SSL client authentication to connect to a Domino server. The Person document for the user stores the user’s Internet certificate, which is used to verify the user’s identity. The Person document also lists the names that a Domino server can use to authenticate an Internet user. When an Internet user tries to connect to a server, Domino looks for the Internet certificate name in the User name field in the user’s Person document. Domino compares the Internet certificate presented with the one stored in the Person document. The comparison lets Domino authenticate the user, even if there are multiple users with the same name, since each user’s public key is unique. If Domino finds a match and the public key is valid, then the first name listed in the User name field is used to check database ACLs and design element access lists.

47-20 Administering the Domino System, Volume 2

Security

For example, if the User name field contains these entries: Alan Jones, AJones, Alan, Al Jones and the client uses the name Al Jones to access the server, Domino authenticates the user, verifies that the public key presented matches the public key in the Person document, and uses the name Alan Jones to check database ACLs and design element access lists. For more information, see the chapter “Controlling User Access to Domino Databases.” To set up a Person document 1. Create a new Person document in the Domino Directory. 2. Enter the client’s first, middle, and last names in the First name, Middle initial, and Last name fields. 3. Enter the client’s common name on the certificate in the User name field. 4. (Optional) Enter additional information about the client in the Work/Home tab. 5. Save the document. Tip If the client wants to authenticate with a Domino server in another domain, add the user’s Person document to the Domino Directory for that domain. Make sure you set up directory assistance so Domino can find the client in the Domino Directory for the domain. For information on setting up directory assistance, see the chapter “Setting Up Directory Assistance.”

Publishing third-party CA client certificates in a Person record
Notes and Internet users who have a client certificate from a third-party certifer may want to have this certificate published in their Person record so that, if a user authenticates with a Domino server over SSL with that certificate, Domino will be able to determine the user’s Notes identity. The server can the use the Notes identity to check server database ACLs to determine the user’s access to those databases. If the certificate with which a user authenticates isn’t in a Person document, Domino gives the user anonymous access, even though the user has authenticated using SSL authentication. To publish a third-party client certificate in a user’s Person record, use the Certificate Publications Request database. Clients submit certificate publication requests to the database, where they are approved by an administrator. After a request is approved, a publication request is

Setting Up Clients for S/MIME and SSL 47-21

created automatically in the Administration Process database. When the request is completed, the third-party client certificate is published in the requester’s Person record. In order to use this database, the server on which it is hosted must: • • Be configured for SSL, accepting both client certificates and anonymous access Have trusted root certificates installed in its server key ring for any certifier whose certificates you want to accept for publication

In order for users to make a publication request, they must be able to authenticate to the Certificate Publications database with the certificate they want to have published. Note The user does not have to have a Person document in the Domino Directory to make a publication request. The administrator can create a Person document once the request has been entered, and it has been decided that the certificate’s owner can be trusted. To create the Certificate Publications Request database 1. From the Domino Administrator, click File - Database - New. 2. Create a new database using the Domino Certificate Publications Request template (CERTPUB.NTF). To publish a third party CA client certificate in a Person record 1. The client opens the Certificate Publications Request database using a browser, completes the Certificate Registration Request form, and submits it. 2. The administrator approves or denies the publication requests in the Waiting for Approval view. 3. If the request is approved, it is submitted to the Administration Process and the client certificate is published in the requester’s Person record.

Setting up SSL for Notes or Domino using SMTP
A Notes client or Domino server can act as an SMTP client when routing mail to an SMTP server. The Notes client or Domino server can use SSL to connect to a Domino server running the SMTP service or to another type of SMTP server. You cannot set up a Notes client or Domino server for SSL client authentication when connecting using SMTP. For more information on SMTP, see the chapter “Setting Up Mail Routing.”

47-22 Administering the Domino System, Volume 2

Security

If you do not have the server’s CA marked as a trusted root in the server key ring file for the Domino server, Domino automatically adds the certificate and logs the condition in the log file. Other Internet protocols do not allow users to proceed unless they have the server’s CA marked as a trusted root. You should, however, mark the CA certificate as a trusted root instead of automatically adding the trusted root to ensure that the trusted root you receive is valid. For information on setting up a Notes client to use SSL to connect to an SMTP server, see Lotus Notes 6 Help. Or got to www.lotus.com/ldd/doc to download or view Lotus Notes 6 Help. To set up SSL for a Domino server routing mail to an SMTP server 1. From the Domino Administrator, click the Configuration tab, and open the Server document. 2. Select the Ports - Internet Ports - Mail tab. 3. In the SMTP Outbound column, select Disabled in the TCP/IP port status field. Note If you do not select Disabled in the TCP/IP port status field, Domino always connects to the SMTP server without using SSL. 4. In the SMTP Outbound column, select Enabled in the SSL port status field. 5. Save and close the document. 6. Add the trusted root certificate for the CA of the SMTP server.

Using SSL when setting up directory assistance for LDAP directories
Directory assistance allows you to extend directory services from a server’s primary Domino Directory to other Notes directories, such as secondary Domino Directories, and to remote LDAP directories. To set up directory assistance, you create a directory assistance database from the DA50.NTF template, and then create Directory Assistance documents in the database to configure services for specific directories. When setting up directory assistance for an LDAP directory, you can instruct a Domino server to use SSL when connecting to the LDAP directory server. This helps secure communications between the Domino server and the LDAP server. You should use SSL if a Domino server uses the remote LDAP directory to authenticate Internet clients, or to look up groups for database authorization.

Setting Up Clients for S/MIME and SSL 47-23

When a Domino server uses SSL to connect to an LDAP directory server, both servers must have certificates trusted by the other. If this is not the case, you must add a trusted root certificate to the server’s key ring file before your server can connect to the LDAP server. For more information on directory assistance for LDAP, see the chapter “Setting Up Directory Assistance.” For more information on adding a trusted root certificate, see the chapter “Setting Up SSL on a Domino Server.”

47-24 Administering the Domino System, Volume 2

Chapter 48 Rolling Out Databases
This chapter describes the tasks involved in rolling out a database for production after it has been designed. Be sure to test the database application thoroughly before announcing its location to users.

Database Management

Database design, management, and administration
The tasks involved with application design, database design, database management, and Lotus Domino system administration may overlap, depending on the size of your organization and the structure of job responsibilities. In some organizations, an application developer may be responsible for both application and database design, while in others, a database manager may handle all database design and management tasks. In addition, database management overlaps with Domino system administration. Therefore, depending on your organization, make sure you work closely with the people who are responsible for design, management, and administration tasks. For example, controlling user access is primarily a Domino system administrator’s responsibility, yet the application developer may determine these access levels because they are often integral to the database design. If design changes are necessary after a database is in production, be sure to: • • Work with the application developer or database designer to implement and coordinate design changes Consider server resources and the connections between servers when putting databases on servers

For more information on designing or redesigning databases, see the Release Notes and the book Application Development with Domino Designer.

Rolling out a database
The following tables list mandatory and optional tasks for a Domino administrator to complete before putting a database into production. You must have Manager access in a database access control list (ACL) to perform these tasks.
48-1

Mandatory tasks
Perform these tasks before copying a new database or database replica to a production server.
Task Considerations

Set up the database ACL If you plan to make replicas of a database, make sure for users and servers that that the database ACL lists the name of each server containing a replica. If the database uses roles, require access assign all roles to each server. If you assign ACL settings on the original database before copying it to a server, assign yourself Manager access on the original. Otherwise, you won’t have Manager access to the new copy. Verify that server ACLs are set up correctly Verify that the Domino Directory contains the necessary Group documents Copy the new database to a server Verify that the database appears in the Open Database dialog box Without proper access in a server ACL, users and servers won’t have access to databases on the server. Create a Group document in the Domino Directory before adding a Group name in a database ACL. If you must create a Group, make sure that the Group document replicates before you copy the database to a server. Consider server disk space, topology, and network protocols. Placing a database on a cluster requires that you consider cluster resources. While designing a database, the database designer often removes the database title from the list that appears in the Open Database dialog box. This deters users from opening the database. After the database is completed, make sure that the database title appears in the Open Database dialog box. To make this decision, consider the purpose and size of the database, the number and location of users who need access to the database, and the existing replication schedules between servers. Server documents are, by default, enabled for replication, but to avoid any problems, verify this.

Decide which servers require replicas of the database and then create the replicas Verify that Server documents in the Domino Directory are enabled for replication Create or edit Connection documents Set up a replication schedule

If several servers have a replica of the database, make sure that any necessary Connection documents are set up so that replication can occur. Consider the location and time zones of users and the frequency of database updates.

48-2 Administering the Domino System, Volume 2

Optional tasks
The following tasks are not required, but you may want to perform them after your database is in production. Whether or not you need to do these tasks depends on the type of database you are rolling out to the production server and the roles assigned to an application developer, database manager, or Domino administrator in your organization.
Task Considerations

Database Management

Create About This Database Provide the name, phone number, and e-mail and Using This Database address of database managers in the About This documents Database document. Provide information about the application in the Using This Database document. For more information, see Application Development with Domino Designer. Create an index for the database Create a full-text index for the database if users need to search the database for information. If you create the index before you copy a new copy of the database or a replica to a server, the index settings carry over to the new copy or replica. If the database design includes encrypted fields, distribute encryption keys to users. For more information, see the book Application Development with Domino Designer. If the database is designed to receive mail, you must create a Mail-In Database document in the Domino Directory. By default, all databases except mail databases are listed in the default views of the database catalog. You can add categories to control how the database appears in the catalog views and to help users narrow the scope of a domain search. Create a library of selected databases on one server or several servers for users. Sign a database to provide a signature for it. Do this, for example, so that an Execution Control List (ECL) can evaluate the signature. If an application database will be useful to a wide audience, include the database in the Domain Index. Provide the database title, file name, and server location.

Distribute encryption keys

Create a Mail-In Database document List the database in the database catalog

Publish the database in a database library Sign the database

Add the database to the Domain Index Notify users that the database is available

Rolling Out Databases 48-3

Copying a new database to a server
Plan the deployment of new databases before copying them to a server. Tasks to perform include: • Setting up all appropriate Server documents in the Domino Directory, including a Mail-In Database document if the database is designed to receive mail. Making sure that users and other servers are listed in the server’s access control list. Otherwise, they won’t be able to access the database. Using subdirectories to group related databases rather than copy them to the root directory. Users can find related databases more easily if they are in one location. This also helps administrators by allowing them to replicate “like” databases, because Connection documents let you replicate according to directory.

For more information on replication, see the chapter “Creating Replicas and Scheduling Replication.”

To copy a new database to a server
1. Make sure that you have Manager access in the database ACL or the Create new databases privilege in the Server Access section of the Server document in the Domino Directory. 2. Select the database icon from your bookmarks page, choose File Database - Properties, click the Design tab, and make sure that “Show in ’Open Database’ dialog” is selected. 3. Choose File - Database - New Copy. 4. Next to Server, click the arrow to display a list of servers. Then select the server on which you want to place the copy. 5. Next to Title, enter a title for the database. The database icon and the Open Database dialog box display this title. 6. Next to File Name, enter the path and file name of the database. Limit the file name to eight characters plus the NSF extension. 7. Choose one: • “Database design and documents” to copy the database design and all documents • “Database design only” if you do not want to copy any existing documents

48-4 Administering the Domino System, Volume 2

8. Optional steps: • Choose “Access Control List” to copy the ACL. You can assign ACL settings (including roles) before or after copying a local database to a server. Before copying the database, assign yourself Manager access to the ACL so that you will have Manager access to the new copy. If you do not copy the ACL when you copy the database to a server, the ACL in the new copy automatically lists you with Manager access. • Select “Create Full Text index” to create a full-text index on the new copy. Note You can also create a full-text index later. • Choose “Encryption” to encrypt the new copy of the database. This option is intended to prevent unauthorized users from accessing a database from a workstation, laptop computer, or server. If you use this option, Notes encrypts the database using a specified ID so that only a user with that ID can gain access to the database directly from a server or workstation. You can choose one of three encryption levels. This encryption setting also carries over to copies of the database made at the operating system level. Note The maximum database size is 64GB on Windows and UNIX. For more information on encryption, see the book Application Development with Domino Designer.

Database Management

Creating a Mail-In Database document for a new database
If a database is designed to receive mail, you must create a Mail-In Database document in the Domino Directory. This document must exist in the Domino Directory of every server that stores a replica of the database. The database cannot receive mail until you create this document. When replicating Mail-in databases to servers in another Domino domain, create a matching Mail-in database document in the Domino Directory of the target server. 1. Make sure you have at least Author access with the Create Documents privilege selected. 2. From the People & Groups tab of the Domino Administrator, choose Create - Server - Mail-in Database.

Rolling Out Databases 48-5

3. On the Basics tab, complete these fields and then save the document: • Mail-in name — The entry for this database in the Domino Directory. Users and applications use this name to send documents to the database. • Internet message storage — The message storage preference: No preference (default); Prefers MIME or Prefers Notes Rich Text. • Internet address — SMTP address in the format mailfile@organization.domain. Complete this field if you want Internet users to be able to send messages to the database. 4. On the Database Information tab, complete these fields: • Domain — Domino domain of the server where the database resides. • Server — The fully-distinguished hierarchical name of the server where the database resides; for example, Server1/Sales/Acme. • Filename — The path and filename of the database relative to the Domino Directory. For example, if the database named MAILIN.NSF is in the MAIL directory of the DATA directory, enter MAIL\MAILIN.NSF. 5. On the Administration tab, complete these fields and then click Save & Close: • Owners — Fully distinguished hierarchical name of users allowed to modify this document. • Administrators — Users or groups who can edit this document. • Foreign directory sync allowed — “Yes” allows entry to be exchanged with foreign directories — for example, a cc:Mail® directory — so that users on the other system can look up the mail-in database in the cc:Mail post office directory and send mail to it. • Encrypt incoming mail — Mail sent to the mail-in database is encrypted with the Notes certified public key entered in the next field. • Notes certified public key — The certified public key to use when encrypting mail sent to this database. To copy a certified public key from the Domino Directory to this field, click “Get Certificates” and choose a name. 6. Give the name of the database to users so they can enter it in the To: field of messages destined for the database. For more information on setting up a database to receive mail, see the book Application Development with Domino Designer.

48-6 Administering the Domino System, Volume 2

Adding a database to the Domain Index
If an application database will be useful to a wide audience, include the database in the Domain Index. 1. From the Domino Administrator, choose File - Database - Open. 2. Select the database that you want to add to the Domain Index, and click Open. 3. Choose File - Database - Access Control, and make sure you have Manager access. 4. Choose File - Database - Properties. 5. Click the Design tab. 6. Make sure that the “List in Database Catalog” option is selected, and enter one or more categories. Note These categories appear on the Domain Search form to provide a user with a way to narrow a search. Categories are also displayed in views of the database catalog and Domain Catalog. 7. Select “Include in multi-database indexing.”

Database Management

Signing a database or template
You can sign a template or database to vouch for its integrity. You might want to do this, for example, to sign an agent so that the Agent Manager on a server can verify that the signer has the rights to execute the agent. Or you might sign a database or template so an ECL on a Notes client can evaluate which database actions to carry out. If you sign a template, any databases created from the template inherit the signature. Note If you want to sign only one specific design document or one design element in a document, for example, a specific agent, you must first determine the Note ID for the document. To determine the Note ID for a document, select the document, choose File - Document Properties, click the last tab of the properties box. The bottom line is the Note ID, for example NT00000902. 1. Select the server that stores the databases or templates that you want to sign. 2. On the Files tab, select the databases or templates that you want to sign. 3. Choose Tools - Database - Sign.

Rolling Out Databases 48-7

4. Choose one of the following: • Active User’s ID to sign using your ID. • Active Server’s ID to sign using the ID of the server that stores the database or template. 5. Choose one of the following options to specify which elements to sign: • All design documents to sign every design element. If you sign multiple databases or templates and select this option, the signing process may take a while. • All data documents to sign all active content (Hotspots) found in the data documents. • All documents of type to sign a specific type of design element • This specific Note ID to sign a specific design element. 6. Select “Update existing signatures only (faster)” to update only design elements that have been signed previously. Use this to change the signature on previously signed design elements. 7. Click OK. A dialog box shows the number of databases processed and the number of errors that occurred (if any). See the Notes Log for details.

48-8 Administering the Domino System, Volume 2

Chapter 49 Organizing Databases on a Server
This chapter discusses how to organize databases that are in the Domino data directory or on another server and how to create links to directories and databases that are not in the Domino data directory.

Database Management

Organizing databases on a server
When organizing databases on a server, you can: • • • Store databases in the Domino data directory. This is the default. Create subdirectories of the Domino data directory to store groups of related databases. Create directory folders to store databases outside the Domino data directory and create links to the databases from the Domino data directory. Restrict access to the server’s data directory

When you create directory and database links, you can increase database security by specifying the ACL access for an individual user or group in the Create New Link dialog box. The database ACL, not the database link, controls access to individual databases that have database links.

Directory links
You can store databases in a directory outside the Domino data directory to take advantage of disk space available on other servers. Then you create a link in the Domino data directory that points to that directory. In the Domino data directory, users see the directory link MKTG.DIR as the subdirectory MKTG, with a directory folder icon next to it. Users who do not have access to a linked directory can see the directory link, but cannot access the directory. You can use a directory link on a Web server to point browser users to a directory outside the Domino data directory. When you create this link, you must specify access for browser users — for example, you can specify access for anonymous users or enter the names of users who use name-and-password or SSL client authentication.

49-1

Database links
You can store a single database outside the Domino data directory and create a database link to it from the Domino data directory. A database link appears in the Domino data directory as a database icon followed by the name of the linked database. You can use a database link on a Web server to point browser users to a database in a directory outside the Domino data directory. If the database link points to a database on another server, browser users cannot access the database.

Creating directory folders
When you create a directory folder, enter only the folder name. After you create the directory folder, you can create directory or database links to the folder. To create a directory folder 1. From the Domino Administrator Server list, select the name of the server on which you want to create the directory folder. The server can be local or remote. 2. Click the Files tab, and then choose Tools - Folder - New. 3. In the Create New Folder dialog box, enter the name of the new directory, and then click OK. 4. To verify that the directory was created, click the refresh icon. 5. Move designated databases into the directory you just created, and then create a directory or database link. To delete a directory folder After you delete a directory folder that is no longer needed, delete the links that point to it. 1. From the Domino Administrator Server list, select the name of the server. The server can be local or remote. 2. Click the Files tab, and then select the directory to delete. 3. Choose Tools - Folder - Delete. 4. In the Delete Folder dialog box, click Yes. 5. To verify that the directory was deleted, click the refresh icon. 6. Delete the links that point to the deleted directory folder.

49-2 Administering the Domino System, Volume 2

Creating directory and database links
Directory links and database links are text files that appear as directory or database icons in the Domino data directory. In the Domino Administrator and in the Open Database dialog box in the Notes client, directory links appear to the user as a directory folder icon, and database links appear as a database icon. Create the directory link to point to a subdirectory, not to a root directory. For example, create the directory link PROJECTS.DIR to point to the directory D:\PROJECTS\SALES. On a Domino Server for NetWare, a DIR file can point to SYS:SALES but not to SYS:. On a Domino Server for UNIX, a DIR file can point to /sales but not to /. Create the database link using the complete path and file name of the database you want to link to. For example, create the database link SALES.NSF to point to the database D:\PROJECTS\SALES\SALES.NSF. Domino automatically appends the NSF extension to the database name. If you want to move a linked database to another location, delete the old link, create a new database link, and move the database to the new location. When you delete the database link, you remove the link, but not the database link references. To create or update a link Use links to organize databases on servers. Create a directory folder link to point users to multiple databases stored in the Domino data directory, in subdirectories of the Domino data directory, or in directories outside of the Domino data directory. Create a database link to point users to a single database stored in the Domino data directory, in subdirectories of the Domino data directory, or in a directory outside the Domino data directory. 1. From the Domino Administrator Server list, select the name of the server on which to create the link. This server can be local or remote. 2. Click the Files tab, and then choose Tools - Folder - New Link or Tools - Folder - Update Link. 3. In the Link name box, enter a name for the link as the link name should appear to the user. Domino automatically appends a DIR extension to the file name for a directory link and an NSF extension for a database link. 4. Next to “Link to a,” choose Folder for a directory link or Database for a database link. 5. In the “Path and filename to that folder or database” box, enter the complete path to the directory or database to which the link points.

Database Management

Organizing Databases on a Server 49-3

Be sure to move the database named in this step to the directory you specify here. For example, for a directory link, enter the directory path, D:\PROJECT\SALES. For a database link, enter the complete directory and file name path, D:\PROJECT\SALES\SALES.NSF. 6. (Optional) To restrict access to a linked directory, enter the names of specific users to whom you want to grant access in the “Who should be able to access this link?” box. Click the person icon to select the names or groups from the Domino Directory that you want to have access to the link. Note The database ACL, not the database link, controls access to individual databases that have database links. 7. Click OK. 8. To verify that the link was created, click the refresh icon. 9. (Optional) To prevent Web browser users from using directory links, edit the NOTES.INI file to include this setting:
DominoNoDirLinks=1

To delete a link 1. From the Domino Administrator Server list, select the name of the server. 2. Click the Files tab, and then select the directory or database link to delete. 3. Choose Tools - Folder - Delete, and then click Yes. 4. To verify that the link was deleted, click the refresh icon. View the result in the Results pane.

Restricting access to a server’s data directory
You can restrict Notes user access to a server’s data directory or a subdirectory of the data directory by defining an access list for it. By default any Notes user who can access a server can access the server’s entire data directory. Creating a data directory access list To restrict access to a server’s data directory: 1. Make sure you have at least database administrators access to the server. 2. From the Domino Administrator, connect to the server. 3. Click the Files tab.

49-4 Administering the Domino System, Volume 2

4. In the left pane, select the directory to which you are restricting access. The access restrictions apply to any subdirectories of the directory as well. 5. In the Tools pane on the right, select Database - Directory ACL. 6. Below “Who should be able to access this directory?” click the person icon. 7. In the dialog box that opens, do the following for each name that you want to allow to access the directory: a. Select the name from a Domino Directory, or type the name in the “Add name not in list” box. You can specify the name of a user, server, group or a wildcard, for example, */Sales/Acme. b. Click Add. 8. When you are finished defining the access list, click OK. 9. Click OK again. In the left pane, the directory now displays a lock icon. Changing or deleting a data directory access list To change or delete a data directory access list: 1. Make sure you have at least database administrators access to the server. 2. From the Domino Administrator, connect to the server 3. Click the Files tab. 4. In the left pane, select the directory with the access list. 5. In the Tools pane on the right, select Database - Directory ACL. 6. Do one of the following: • To remove a name from the access list, below “Who should be able to access this directory?” select the name and click the red X. To delete the access list entirely, remove each name from the list. • To add a name to the access list, below “Who should be able to access this directory?” click the person icon, select or type the name, click Add, then click OK. 7. Click OK to save your changes.

Database Management

Organizing Databases on a Server 49-5

NOTES.INI file settings used to organize databases on a server
The following table lists the NOTES.INI setting you can use to organize databases on a server. For more information on NOTES.INI settings, see the appendix “NOTES.INI File.”
NOTES.INI file setting DominoNoDirLinks Description Prevents Web browser users from using directory links.

49-6 Administering the Domino System, Volume 2

Chapter 50 Setting Up and Managing Full-text Indexes
You must index a database for full-text searches to allow users to quickly search and locate information within that database.

Database Management

Full-text indexes for single databases
You can create full-text indexes to allow users to quickly search for information in databases. To search in a database, users enter a word or phrase in the search bar of the database to locate all documents containing the word or phrase. To create an index for a single database, you must have at least Designer access to the database. Sometimes the application developer of the database has already created an index. You can find out whether or not a database is indexed by looking at the Database Properties box (Full Text tab, “Last Index Time” from the Files tab of the Domino Administrator.) The Domino Administrator lets you create single indexes for more than one database at a time. Users can create full-text indexes for local databases.

Database indexes and replication
Because full-text indexes don’t replicate, you must create a full-text index for each database replica. When you create the replica, you have the option to create a full-text index on the replica. The index options on the replica are the same as the index options for the full-text index of the original database. For more information, see the chapter “Creating Replicas and Scheduling Replication.”

Database indexes and the Domain Index
You can also include the full text of databases in the Domain Index, a centralized full-text index of multiple databases on subjects of widespread interest across a Notes domain that allows users to search on a word or phrase when they don’t know which database contains the information. To search in the Domain Index, users click the arrow beside the Search icon on the right-hand side of the Notes menu bar and choose “Domain Search.”
50-1

The Domain indexing process is completely separate from that for individual databases, and including a database in the Domain Index does not preclude the need to create a separate index for a popular database. For more information on adding the full text of a database to the Domain Index or on setting up the Domain Index, see the chapter “Setting Up Domain Search.”

Security and full-text indexes for single databases
When you create a full-text index for a single database, selecting the option “Index encrypted fields” can compromise system security in the following ways: • Search results might display a list of all documents that contain a specific word or phrase, even in encrypted fields. The user won’t be able to read the field but will know that the document contains the word or phrase. For example, the Employee form in the Personnel database contains the encrypted field Salary. Any user can search the full-text index for “50,000,” and documents that contain that figure are included in the search results. However, the user cannot read the contents of the field without the encryption key. A full-text index file is unencrypted plain text; therefore, anyone with access to the server can read the file. A user may be able to read text that was previously encrypted. The encryption key, which is part of the server ID, is active for all databases on the server. If you index a different database and do not deselect “Index encrypted fields,” any fields using that encryption key are compromised.

For more information on encrypted fields, see the chapter “Encryption and Electronic Signatures.”

Creating and updating full-text indexes for single databases
As you create a full-text index for a database, select indexing options and update frequency options carefully, as they can affect server disk space and processing speed. Lotus Domino stores the index file in a subdirectory of the directory where the database file is located, usually the Domino data directory. The name of this subdirectory is filename.FT, where filename is the file name of the indexed database — for example, /EMPLOYEE.FT. Domino can also store the index file in a directory to which you have created a link. For more information on directory and database links, see the chapter “Organizing Databases on a Server.”

50-2 Administering the Domino System, Volume 2

You must periodically update full-text indexes on servers to keep them synchronized with changes to the databases. When you create an index, you can either accept the default schedule for updating it (nightly at 2 AM) or specify a different schedule. You can modify this setting at any time. You can also do manual index updates for server databases at any time from the Domino Administrator.

Database Management

Note Users update full-text indexes for local databases whenever they replicate with the server. Users can also do manual index updates for local databases at any time. To create one or more indexes 1. From the Domino Administrator, select the server that stores the database or databases you want to index. 2. Click the Files tab. 3. In the Tools pane, make sure that you have at least Designer access in the ACL of any database you want to index. 4. Select one or more databases to index. 5. In the Tools pane, choose Database - Full Text Index. 6. Select Create. 7. (Optional) Select any of the following indexing options (all of which increase index size). Index size is also dependent on the amount of text in the database (non-text elements such as bitmaps, buttons, and agents are not indexed). To check index size after indexing a database, look on the Full Text tab of the Database Properties box.
Indexing option Description Index attached files Indexes attachments. Also choose either “With found text” to include just the ASCII text of attachments, or “With file filters” to include the full binary content of attachments. Choosing “With found text” creates the index faster than choosing “With file filters,” but is less comprehensive. Index encrypted fields Indexes text in encrypted fields. Selecting this option can compromise system security.

Index sentence and Includes sentence and paragraph breaks in addition to paragraph breaks word breaks to allow users to do proximity searches. Enable case sensitive searches Allows searches by exact case match. This option increases the size of the index by about 15%, as each word must be indexed twice — for example, apple and Apple.

Setting Up and Managing Full-text Indexes 50-3

Note You can view your indexing selections later on the Search tab of the Database Properties box. 8. (Optional) Change the default setting for index update frequency. Update frequency options are described in the following table.
Update frequency Updates occur option Daily (the default) Select when

Nightly when the Updall The database is very large, server program runs at 2 because updating a large AM. index can take some time. To change the time that Updall performs automatic daily index updates, use the ServerTasksAthour setting in the NOTES.INI file. Every hour, as scheduled by Frequent changes are made to the database contents. If the Chronos server task. subsequent monitoring of the database and server reveals slow performance of either, change to another frequency setting. As soon as possible after you close the database. Very frequent changes are made to the database contents. If subsequent monitoring of the database and server reveals slow performance of either, change to another frequency setting. None of the update frequency options described here meet your needs.

Hourly

Immediate

Scheduled

As scheduled by a Program document for the Updall server task in the Domino Directory. If you select the Scheduled option, you must specify a schedule for Updall in a Program document; otherwise, scheduled updates will not occur.

9. Click OK. 10. Inform users that the database or databases are indexed.

50-4 Administering the Domino System, Volume 2

Setting a schedule for Updall in a Program document
When creating a full-text index for a single database, if you select the index update frequency option “Scheduled,” you must set up a Program document in the Domino Directory to specify the schedule you want for the Updall server task. 1. From the Domino Administrator, click the Configuration tab and expand the Server section. 2. Click Programs. 3. Create or edit a Program document. 4. On the Basics tab: a. Type Updall in the “Program name” box. b. Type any optional arguments in the “Command line” box. c. Type the server name on which the full-text indexed database resides in the “Server to run on” box. 5. On the Schedule tab: a. Select Enabled in the Enabled/disabled box. b. Select the time for Updall to update the index in the “Run at times” box. c. Select a repeat interval, if any, in the “Repeat interval of” box. d. Select the days of the week for Updall to update the index in the “Days of week” box. 6. Save and close the Program document.

Database Management

Changing update frequency for a database’s full-text index
If a database is already full-text indexed, you can change the existing frequency setting on the Full Text tab of the Database Properties box. 1. From the Domino Administrator, select the server that stores the database. 2. On the Files tab, select the database for which you want to change the index update frequency. 3. Using the Tools pane, make sure that you have at least Designer access in the database ACL. 4. Choose File - Database - Properties, and click the Full Text tab. Note If you know you want multiple indexes to have the same frequency setting, you can select the databases and use the Tools pane’s Databases - Full Text Index command to change all their indexes to that setting, but the Tools pane does not provide a means
Setting Up and Managing Full-text Indexes 50-5

to check whether databases are indexed or verify current update settings. 5. In the “Update frequency (servers only)” box, select one of the options described here.
Update frequency option Updates occur Daily Hourly Immediate Scheduled Nightly when the Updall server program runs by default at 2 AM Every hour, as scheduled by the Chronos server task As soon as possible after you close the database Note As scheduled by a Program document for the Updall server task in the Domino Directory If you select the Scheduled option and do not create a Program document for Updall, scheduled updates do not occur.

6. Click OK.

Manually updating full-text indexes for single databases
You can use Domino Administrator to update indexes manually after new information or documents have been added to databases. You can update a single index in the Database Properties box, or update one or more indexes from the Tools pane. Note The Database Properties box (Full Text tab) provides useful information about an index, such as the number of unindexed documents currently in the database, the last time the index was updated, and its size. To update an index in the Database Properties box 1. From the Domino Administrator, select the server that stores the database. 2. On the Files tab, select the database whose index you want to update. 3. Choose File - Database - Access Control and make sure that you have at least Designer access in the database ACL. 4. Choose File - Database - Properties. 5. Click the Full Text tab. 6. Click Update Index.

50-6 Administering the Domino System, Volume 2

To update one or more indexes from the Tools pane 1. From the Domino Administrator, select the server that stores the databases. 2. Click the Files tab. 3. From the Tools pane, make sure that you have at least Designer access in the ACL of any database for which you want to update the index.

Database Management

4. Select all the databases for which you want to update the index. 5. From the Tools pane, choose Tools - Database - Full Text Index. 6. Select Update. 7. Click OK.

Deleting full-text indexes for single databases
Delete a full-text search index when you no longer need it, when you need to the change the index options, or when you discover problems with the index. 1. From the Domino Administrator, select the server that stores the database or databases. 2. Click the Files tab. 3. Using the Tools pane, make sure that you have at least Designer access in the ACL of any database for which you want to delete the index. 4. Select all the databases for which you want to delete the index. 5. From the Tools pane, choose Tools - Database - Full Text Index. 6. Select Delete. 7. Click OK.

Setting Up and Managing Full-text Indexes 50-7

Chapter 51 Setting Up Database Libraries and Catalogs
This chapter discusses setting up and managing database libraries — which administrators create to help particular groups of users find pertinent databases — and database catalogs — which list for users all databases on a given server. This chapter does not cover the Domain Catalog, which lists databases on all servers across a Domino domain. For information on the Domain Catalog, see the chapter “Setting Up Domain Search.”

Database Management

Database libraries
You can create a database library that contains databases that pertain to a specific collection of users or to a specific topic. For example, a corporate database library might include all databases that deal with corporate policies and procedures, and a marketing database library might include databases that are useful to the marketing staff. The main view in a library lists the databases it contains alphabetically by title, and gives a short description of each database. Each database document displays the database’s title, short and long descriptions, replica ID, and database manager, as well as buttons that let users browse the database or add it to their bookmarks. Note Instead of creating database libraries to point users to the databases they need, you can use Desktop policy settings to add bookmarks directly to their workspaces. For more information on Desktop policy settings, see the chapter “Using Policies.”

Server libraries
The databases you choose to include in a library can be located on any server. More than one library can reside on a server. When a user opens a database from a database library, Lotus Domino uses the database’s replica ID number to search for it. Domino first searches for the database on the user’s workspace, then on the user’s home server, and finally looks for a Domain Catalog to find a path to a replica of the database on
51-1

another server. If a database is moved to another server, Domino automatically opens the database at its new location and then updates the database’s replica ID in the database library. When you create a database library on a server, you automatically become the librarian for that database library with Manager access in the library ACL. The -Default- access in the library ACL is Reader. If a user with Reader access in the database library ACL attempts to publish a database, Domino automatically sends the librarian an e-mail containing the request to publish the database. The librarian then publishes the database for the user. If you want users to be able to publish databases in the library themselves, change -Default- access to Author.

Local libraries
You can create a local library for your own use, which lists databases on your own hard drive as well as databases on servers. The only difference between a local library and libraries on servers is that no other users can use your local library or become librarians for it.

Creating a database library and assigning librarians
To use the library template to create a library on a server, you must have “Create new databases” access in the Server Access section of the Server document. If you plan to create many libraries on a server, create a subdirectory in the Domino data directory to store them. Then users can easily locate all available libraries.

To create a database library
1. From the Domino Administrator, choose File - Database - New. 2. Enter a location for the database library (server or local), title, and file name for the library. 3. Select “Show advanced templates” at the bottom of the dialog box. 4. Select the Database Library template (DBLIB4.NTF), and click OK. If you do not see the template in the list, click the “Template server” arrow, and choose a server that contains the advanced templates from the list. Note You are automatically listed in the database as a librarian.

51-2 Administering the Domino System, Volume 2

To assign librarians
You must be a librarian of a database library in order to make other users librarians. 1. If someone other than you created the library, make sure you have Editor or higher access in the library ACL. 2. Make sure that the users to whom you are giving librarian status have at least Author access in the database library ACL. 3. From the Domino Administrator, select the server that holds the database library. 4. On the Files tab, double-click the title of the database library. 5. In the Librarians view, click “Edit Librarians.” 6. Type the names of all users who will be librarians, pressing ENTER after each name. 7. Close and save the Librarians document.

Database Management

Publishing databases in a library
To publish a database in a database library means to add a database to the library. Unlike a database catalog, which lists all the databases on a server, a library contains links to selected databases from one or several servers. For the convenience of different user groups, there can be more than one library on a server.

To publish a database in a library
1. Make sure you have Author or higher access in the database library ACL. 2. From the Domino Administrator, select the server that holds the database you want to publish to the library. 3. On the Files tab, select the title of the database you want to publish to the library. 4. Choose File - Database - Publish. 5. Select the database library title from the “Available libraries” list, and click OK.

Setting Up Database Libraries and Catalogs 51-3

6. Enter information in the following fields, and then close and save the database document: • In the Abstract field, type a short description of the database to serve as the description that appears next to the database’s title in the database library. • In the “Long Description” field, type a more complete description of the database contents that appears when you open the database document.

To delete a database from a library
1. In the database library ACL, make sure you have Author access to a database to delete the database documents you’ve created and Editor or higher access to delete documents others have created. 2. From the Domino Administrator, select the server that holds the database library. 3. On the Files tab, double-click the title of the database library. 4. In the Databases by Title view, select the database you want to delete. 5. Choose Edit - Delete.

Database catalogs
A database catalog provides a list of all databases on a server. You use the server Catalog task to create a database catalog. The Catalog task bases the catalog file (CATALOG.NSF) on the CATALOG.NTF template and adds the appropriate entries to the catalog’s ACL. All databases on a server are included in the catalog when the Catalog task runs. Only administrators can see listings for some databases (those with the “List in Database Catalog” option selected in the Database Properties box), as these databases are not included in the default views. For databases in the default views, you can specify categories in the Database Properties box to determine how the databases appear in the categorized view of the catalog. For large catalogs, you can create a full-text index to make searching the catalog faster. To help users locate databases across an organization, or to keep track of all the replicas for each database, you must set up a Domain Catalog — a catalog that combines the information from the database catalogs of multiple servers — on one of your servers. You can set up a Domain Catalog regardless of whether you plan to implement Domino’s Domain Search capability. For more information on the Domain Catalog, see the chapter “Setting Up Domain Search.”
51-4 Administering the Domino System, Volume 2

Uses for a server’s database catalog
Besides allowing users to see what databases are on a particular server, catalogs provide useful information about databases. For each database in a view, a Database Entry document provides information such as file name, replica ID, design template, database activity, replication, full-text index, and ACL, as well as buttons that let users browse the database or add it to their bookmarks. In addition, the document displays a link to the database’s Policy (About This Database) document, which, for databases users are not authorized to access, they can view by sending an e-mail request to the database manager.

Database Management

Administering a server’s database catalog
Lotus Domino runs the Catalog task daily at 1 AM by default to create or update a database catalog on every server. The Catalog task creates a CATALOG.NSF database from the CATALOG.NTF template and populates the catalog with a list of all databases on the server. You can populate the catalog at any time by typing the following server command at the server console:
load catalog

To view the documents in the database catalog, open the catalog from the Domino Administrator or the Web Administrator tool (Files tab).

Setting up a server’s database catalog
You create a server’s database catalog by running the Catalog task. Then you can make the catalog more useful for your users by: • • • Creating your own categories to control the list of databases that appear in the Databases by Category view of the catalog. Determining if there are any databases to exclude from the catalog’s default views (such as mail files). Notifying users that the catalog exists and is ready for use.

To create a database catalog
From the server console, type the following server command:
load catalog

Note The Catalog task assigns Manager access in the ACL to administrators and to the server that stores the catalog.

Setting Up Database Libraries and Catalogs 51-5

To assign a category to a database
Assign one or more categories to a database to determine how the catalog groups the databases listed in the Databases by Category view. If you do not specify categories, then the Databases by Category view is blank. 1. Make sure you have at least Designer access in the database ACL. 2. From the Domino Administrator, select the server that holds the database that you want to assign a category to. 3. On the Files tab, select the database that you want to categorize. 4. Choose File - Database - Properties. 5. Click the Design tab, and select “List in Database Catalog.” 6. In the Categories box, type one or more categories for the database. Separate category names with a comma or semicolon.

To exclude a database from a catalog’s default views
All databases on the server are listed in the catalog’s default views. You might want to exclude some databases, such as mail databases, from the default views by performing the following steps for each database that you want to exclude. Note Excluding a database from a catalog’s default views does not prevent administrators from creating views that display a complete listing of databases on the server. 1. Make sure you have at least Designer access in the database ACL. 2. From the Domino Administrator, select the server that holds the database that you want to exclude from the catalog. 3. On the Files tab, select the database that you want to exclude. 4. Choose File - Database - Properties. 5. Click the Design tab, and then deselect “List in Database Catalog.”

51-6 Administering the Domino System, Volume 2

Chapter 52 Monitoring the Domino Server
This chapter explains how monitor the statistics and events that occur on the Domino server and how to view and analyze performance statistics.

Monitoring the Domino system
Domino generates statistics that you can use to monitor system activity and platform use, and includes many server-monitoring features that work together to inform you about the processes, networks, and use of the Domino system. Using one of three tools — the Domino Administrator, the Web Administrator, or the server console — you can monitor the system. For example, from the Domino Administrator, you can use the Domino server monitor and statistics charts to view graphical representations of system status; and from the server console, you can view a representation that uses your predefined colors and text attributes to illustrate the status of a process. The Domino Administrator includes these system-monitoring tools that you use to configure, view, and track the Domino system: • Monitoring databases — Store monitoring documents, information, and results. The Monitoring Configuration database (EVENTS4.NSF) stores the documents you use to set up monitoring. It also includes information about statistics, statistic thresholds, and event messages. The Monitoring Results database (STATREP.NSF) stores the gathered statistics reports and can be configured to store information about logged events. The log file (LOG.NSF) stores the server’s log documents. Monitoring Configuration documents — Define and configure what constitutes an event, and how the event is handled. Also allow you to customize the messages that appear on the console when an event occurs. Server tasks — Collect and record information about the Domino system. The Event Monitor task determines if an Event Handler has been configured for the event, and if so, routes the event to the specified person, database, or server-management program for processing. The Statistic collector task gathers Domino server statistics and creates statistics reports in the Monitoring Results

Monitoring

52-1

database (STATREP.NSF) or to another database you can specify. The ISpy task executes TCP server and mail-routing event generators. • Statistics — Domino gathers statistics that show the status of processes currently running on the system — for example, the statistic “Free space on drive C” indicates the amount of free space available on drive C. You use these statistics along with the predetermined statistics thresholds to monitor both your Domino system and platform statistics. Domino server monitor — Provides a visual representation of the status of the servers you are monitoring.

Monitoring Configuration database
The Monitoring Configuration database (EVENTS4.NSF) includes a set of default documents you use to set up system-monitoring. You can edit the default documents or use the configuration wizards in the Monitoring Configuration database to create new ones. The Monitoring Configuration database includes these documents:
Document Event Generator Event Handler Event Notification Method Log Filter Server Console Configuration Server Statistic Collection Description Defines the parameters of an event. Describes what action to take when an event occurs. Defines the notification method to use when the Event Handler document prescribes notification. Specifies events that you do not want to log. Sets the text, background, and color attributes for the Domino server console. Specifies one or more servers from which statistics are collected and identifies the server that performs the collecting.

Statistic Description Describes a statistic.

Monitoring events on the Domino system
Every occurrence that happens on the Domino system is an event. Events signal both that the system is working smoothly, processing data, and performing tasks; and that the system is malfunctioning, perhaps by not processing data or performing required tasks.

52-2 Administering the Domino System, Volume 2

Domino generates events continuously. Therefore, to monitor the Domino system efficiently, you must decide which events you want to know about. For example, the event “Replicating files with servername” occurs every time a file replicates with a specified server; consequently, you may want to know about the event only if it fails. You configure events that you want to know about, based on what type of information is important to you. To configure an event, you determine three critical pieces of information: what type of event it is, what the severity level is, and how you want it handled. You configure your events using Event Generator and Event Handler documents. Event generators describe the condition that must be met for an event to be generated; event handlers describe what happens when the event occurs. After deciding which events you want to know about, decide what will happen when the event occurs. You have several choices. You can log the event to the log file (LOG.NSF); you can mail a notification of the event to a file or an administrator; or mail the event to another application for further processing. You create an Event Handler document to specify to log the event to a specified destination, and simultaneously receive notification of the event’s occurrence and run a program for additional processing. You can also prevent the event from being logged or handled at all. However, if you want to know about an event, you must have an Event Handler document. Otherwise the event is not recorded. There is no default way of handling an event. So if you do not create event handlers, then events are not logged or stored anywhere (except for server or add-in task events, which are stored in the log). After an event is passed to the Event Monitor task, it can invoke one or more configured Event Handlers.

Monitoring

Event generators
Event generators gather information by monitoring a task or a statistic or by probing a server for access or connectivity. Each event generator has a specified threshold or condition, which, when met, causes an event to be created The event is passed to the Event Monitor task, which checks whether an associated event handler has been defined. If an event handler has not been defined, the Event Monitor task does nothing. If an event handler has been defined, the Event Monitor carries out the instructions in the event handler. The Event Monitor task, formerly know as the Event task, starts automatically when you start the server and must run on all servers that you want to monitor. For more information about event handlers, see the topic “Event handlers” later in this chapter.
Monitoring the Domino Server 52-3

The Domino Administrator includes a set of default event generators, which are listed in the Event Generators view of the Monitoring Configuration database (EVENTS4.NSF). To monitor other events that are important to you, you must create an event generator and define the type and severity of the event. The following table lists the types of event generators you can create. If you purchased an add-in product designed to work with server-management programs, you may see additional types of events listed.
Event generator Database event generator Description • Monitors database activity and free space • Monitors frequency and success of database replication • Reports on ACL changes, including those made by replication or an API program Domino server response event generator Mail routing event generator • Checks connectivity and port status of designated servers in a network • Sends a mail-trace message to a particular user’s mail server and gathers statistics indicating the amount of time, in seconds, it takes to deliver the message • Monitors a specific Domino or platform statistic

Statistic event generator

Task status event generator • Monitors the status of Domino server and add-in tasks TCP server event generator • Verifies the availability of Internet ports (TCP services) on servers and generates a statistic indicating the amount of time, in milliseconds, it takes to verify that the server is responding on the specified port

Event severity levels
The severity of an event indicates the level of required action.
Severity level Fatal Failure Warning (high) Warning (low) Normal Meaning Imminent system crash Severe failure that does not cause a system crash Loss of function requiring intervention Performance degradation Status messages

52-4 Administering the Domino System, Volume 2

Creating a database event generator
Create a database event generator to monitor database use and ACL changes. 1. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 2. Open the Event Generators - Database view, and then click New Database Event Generator. 3. On the Basics tab in the “Databases to monitor” section, complete these fields:
Field File name Servers Action Enter the name of the database. Choose one: • All in the domain • Only the following. Then select one or more servers to monitor.

Monitoring

4. In the “What to monitor” section, choose one or more of the following: • Monitor ACL Changes — To monitor all ACL changes, including those made by replication. • Monitor replication — To monitor the frequency and success of database replication. Then complete these fields on the Replication tab:
Field Server(s) with which the database must replicate Action Choose one: • All in the domain. • Only the following. Then select one or more servers from the list.

Replication timeout Enter a time-out value. The default is 24 hours.

• Monitor unused space — To monitor the amount of white space (free space) in one or more selected databases on a server. Then complete these fields on the Unused Space tab:
Field Trigger the event when unused space exceeds Automatically compact the database when the above condition is met Action Enter a percent. The default is 30%. (Optional) Select this option (the default) to compact the database.

Monitoring the Domino Server 52-5

• Monitor for user inactivity — To monitor database activity and to determine which databases are not being used. Then complete these fields on the user Inactivity tab:
Field Time periods to monitor Action Choose one: • Daily • Weekly • Monthly Enter a minimum number of sessions that will trigger an event. The defaults are: • Daily — 10 sessions • Weekly — 50 sessions • Monthly — 300 sessions

Minimum sessions

5. On the Other tab, complete these fields, and then save the document:
Field Action Generate a database event Select a severity level. of severity Create a new event handler for this event Click this button to launch the Event Notification Wizard and create an event handler.

Creating a Domino server event generator
Create a Domino server event generator to configure a server that checks connectivity and port status of designated servers in the network every three minutes. 1. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 2. Open the Event Generators - Domino Server Response view, and then click New Domino Server Event Generator. 3. On the Basics tab, complete these fields:
Field Target server(s) Probing server (source) Action Choose one or more servers to probe. Choose the server that will probe the target servers.

4. For the field “Interval n minutes,” enter an interval in minutes at which you want to send the probe. The default is three.

52-6 Administering the Domino System, Volume 2

5. Choose one of the following options: • Check just the ability to access the destination server • Check the ability to access the destination server and open this database, and then enter a file name 6. Click the Probe tab, and then complete these fields:
Field Ports Action Do one: • Enable the field to use any configured port to check access. • Disable the field, and specify the port to use. Time-out threshold Enter a number that represents the allocated amount of time (in milliseconds) to open the database or access the server. The default is 1000 milliseconds.

The Resulting Statistic field, which is not editable, shows the name of the statistic that is generated. 7. Click the Other tab, complete these fields, and then save the document:
Field Action

Monitoring

On time-out, generate a Server Select a severity level. event of severity Create a new event handler for Click to launch the Event Notification this event Wizard and create an event handler.

Creating a mail-routing event generator
Create a mail-routing event generator to test and gather statistics on mail routes. To test a mail route, the ISpy task sends a mail-trace message to a specified user’s mail server. This event generator creates a statistic that indicates the amount of time, in seconds, it takes to deliver the message. If the mail-routing trace fails, the statistic has the value -1. If the Statistic Collector task is running, the Monitoring Results database (STATREP.NSF) stores the statistics. The format of a mail routing statistic is:
QOS.Mail.RecipientName.ResponseTime

In addition, the ISpy task monitors the local mail server by default and generates events for traces that fail. To monitor other Domino mail servers, create an event generator and set up an event handler to notify you when an event has occurred.

Monitoring the Domino Server 52-7

To create a mail-routing event generator 1. Make sure that you started the ISpy task on the server. For more information on the ISpy task, see the topic “Starting and stopping the ISpy task” later in this chapter. 2. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 3. Open the Event Generators - Mail view, and click New Mail Routing Event Generator. 4. On the Basics tab, complete these fields:
Field Action All Domino servers in Do one: the domain will probe • Check this option to have each server to probe themselves only the local mail box. • Uncheck this option to probe specified servers. Recipient Enter the address of the recipient for which you want to check the mail route or use the drop-down box to select a recipient from a Domino Directory or Address Book. Do not enter more than one user and do not enter a group name. Select the name of the server from which to start the probe. Enable this option to track intermediate hop times.

Probing servers (source) Show intermediate hop times

5. Click the Probe tab, and complete these fields:
Field Send interval Time-out threshold Action Enter the number of minutes between probes. The default is 15. Enter the number of minutes the probing server (source) waits for a response before logging a failure.

6. Click the Other tab, complete these fields, and then click Save & Close.
Field Action On time-out, generate Select the severity level. a Mail event of severity Create a new event Click this button to launch the Event Notification handler for this event Wizard and create an event handler.

52-8 Administering the Domino System, Volume 2

Creating a statistic event generator
The Monitoring Configuration database (EVENTS4.NSF) includes a definition of each Domino system and platform statistic. Each definition also includes a default threshold value. To monitor a statistic, create a statistic event generator. In the statistic event generator, you can change the default threshold and specify how you want the event to be handled when the threshold is met. To generate statistic events, statistic alarms must be enabled on either the Domino Server or the Domino Administrator. Enabling statistic alarms instructs the Collector task to periodically check the value of configured statistics with the thresholds specified in their event generator documents. When a threshold is exceeded an alarm document is created in the Monitoring Results database (STATREP.NSF). The first time an alarm is reported, a statistic event is generated. Alarms continue to be reported at the alarm interval specified when you enabled alarms. However, after the first alarm, subsequent events are generated, by default, once daily until you clear the alarm in the Statistics - Alarms view of the Domino Administrator. You enable alarms in the Domino Administrator by setting Administration Preferences. You enable alarms on the server, in the Server Statistic Collection document. For more information on enabling statistics alarms in the Domino Administrator, see the chapter “Setting Up and Using Domino Administration tools.” For more information on enabling alarms on the Domino Server, see the topic “Creating a Server Statistic Collection document,” later in this chapter. To create a statistic event generator 1. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 2. Open the Event Generators - Statistic view, and click New Statistic Event Generator. 3. Under Servers to monitor, choose one: • All in the domain • Only the following. Then select one or more servers you want to monitor. 4. Under Statistic to monitor, select a statistic, and then choose one: • Monitor as a percent of the whole (Disk.C.Size). Then click the Threshold tab and enter the percentage of the total (Disk.C.Size) that is the threshold value. • Monitor as a number (bytes). Then click the Threshold tab, and enter a threshold value in bytes.
Monitoring the Domino Server 52-9

Monitoring

5. For the “Generate the event when” field, choose one: • The statistic is less than the threshold value • The statistic is greater than the threshold value • The statistic is a multiple of the threshold value 6. Click the Other tab, complete these fields, and then click Save & Close.
Field Generate a statistic event of severity Action Select a severity level.

Create a new event Click this button to launch the Event Notification handler for this event Wizard and create an event handler.

Creating a task status event generator
Create a task status event generator to monitor when a task starts, stops, or stalls. 1. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 2. Open the Event Generators - Task Status view, and click New Task Monitor. 3. On the Basics tab under Tasks to monitor, complete these fields:
Field Task name Servers Action Select the name of the task. Choose one: • All in the domain • Only the following. Then select the name of one or more servers What to monitor • • • • Monitor task down Monitor task up Monitor task not responding Monitor task resumed responding

4. Click the Other tab, complete these fields, and then save and close.
Field Generate a monitor event of severity Action Select a severity level.

Create a new event Click this button to launch the Event Notification handler for this event Wizard and create an event handler.

52-10 Administering the Domino System, Volume 2

Creating a TCP server event generator
Create a TCP server event generator to verify the availability of the services on Internet ports on one or more servers. A TCP server event generator uses the Ispy task to send a probe to test whether the server is responding on a port. The probe generates a statistic that indicates the amount of time, in milliseconds, it takes to verify that the server is responding on the specified port. If the probe fails, the statistic has the value -1. The format of a server probe statistic is:
QOS.TCPservice.ServerName.MonitorId.ResponseTime

If the Collector task is running, the Monitoring Results database (STATREP.NSF) stores the Internet port statistics. By default, the ISpy task monitors all enabled Internet ports (TCP services) on the server on which it is running. When you create a TCP server event generator, you can have each server probe its own configured ports and all services that are running on those ports, or you can select which servers and services to probe. To verify the statistic name and the type of event generated upon failure, click the tab for each service. To create a TCP server event generator 1. Make sure that the ISpy task is running on the server. For more information on the ISpy task, see the topic “Starting and stopping the ISpy task” later in this chapter. 2. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 3. Open the Event Generators - TCP Server view, and click New TCP Server Event Generator. 4. On the Basics tab for the field “All Domino servers in the domain will probe themselves,” do one: • Check the option to have each server probe all services on its own configured ports. Then continue with Step 6. • Uncheck the option to specify the server ports and services to probe. 5. Under Target Servers, choose one: • All in the domain (default) — To probe the ports of all servers in the domain. • Only the following — To probe the ports of selected servers in the domain. Then select one or more servers. 6. Under Probing servers (source), select the server from which the probes will be sent.
Monitoring the Domino Server 52-11

Monitoring

7. Click the Probe tab, and complete these fields:
Field Probe interval Service time-out threshold Action Enter the number of minutes between probes. Default is 15. Enter the number of seconds the probing server (source) waits for a response before logging a failure. Default is 30.

8. If all servers are probing themselves, continue with Step 8. If you chose to specify services, choose one. • Probe all configured TCP services • Probe these services. Then check the services to probe. 9. If all servers are probing themselves or if you selected the HTTP service to probe, click the HTTP tab and choose one • Probe just the port — To probe the availability of the HTTP service on the port. • Fetch this URL — To probe for the availability of a Web server. Then enter a URL specifying the file path. Do not include the server in the URL address. 10. If all servers are probing themselves or if you selected the NNTP service to probe, click the NNTP tab and choose one: • Probe just the port — To probe the availability of the NNTP service on the port. • Send this command — Then enter the command and the news group name. 11. Click the Other tab, complete these fields, and then click Save & Close:
Field Action On time-out, generate Select the severity level. an event severity Create a new Click this button to launch the Event Notification notification profile for Wizard and create an event handler. this event

Disabling an event generator
You may want to use some event generators only temporarily. For example, if you suspect that server performance is slow, you can set up a statistic event generator document to report if more than five server sessions are dropped (Server.Sessions.Dropped), and then disable this event generator after you monitor dropped server sessions for a week.
52-12 Administering the Domino System, Volume 2

To disable an event generator 1. From the Domino Administrator, click the Configuration tab, and then open the Monitoring Configuration view. 2. Open the Event Generators view, and select the event generator to disable. 3. Click the Other tab. 4. Check the field “Disable this event generator.” 5. Save and close.

Starting and stopping the ISpy task
You must start the ISpy task before you can create server and mail routing event generators. The ISpy task does not start automatically. Use any of these methods to start and stop the ISpy task. Because the ISpy task is case-sensitive, you must enter it exactly as shown in this table.
To do this Perform this task

Monitoring

Start the ISpy task automatically Edit the ServerTasks setting in the when the server starts NOTES.INI file to include RunJava ISpy. Start the ISpy task manually Stop the ISpy task Enter the command load runjava ISpy at the console. Enter either the command tell runjava ISpy quit or tell runjava quit at the console.

For more information about NOTES.INI settings and server commands, see the appendices.

Using event generator and event handler wizards
If you know the type of event generator you want to create and are familiar with the options available in that event generator document, use the following wizards in the Monitoring Configuration database (EVENTS4.NSF) to create event generators and event handlers: • • • Event handler wizard — Creates an event handler. Database and statistic wizard — Creates database and statistic event generators. Mail-routing and server response wizard — Creates mail-routing, Domino server, and TCP event generators.

To start a wizard 1. From the Domino Administrator, click the Files tab. 2. Open the Monitoring Configuration database, and then choose the Setup Wizards view. 3. Click the wizard you want to use.
Monitoring the Domino Server 52-13

Viewing event generators
Event Generator documents are stored in the Monitoring Configuration database (EVENTS4.NSF). Each type of event generator has a view that provides a list of all event generators, plus additional configuration information. To view event generator documents 1. From the Domino Administrator, click the Configuration tab, and open the Monitoring Configuration database (EVENTS4.NSF). 2. Open the Event Generators view, and select the type of event generator documents to view. 3. Double click an event generator document to display additional information.

Event handlers
An event handler defines the action that Domino takes when a specific event occurs. You can define an event handler to do one or more of the following: • • • • Log the event to a configured destination Notify you that the event occurred and specify the method of notification Forward the event to another program for additional processing Prevent the event from being logged to the server console or to a specified destination

The Monitoring Configuration database (EVENTS4.NSF) includes default event handlers for server tasks. However, to customize how events are handled, you may want to create a custom event handlers. You can enable or disable an event handler, so you can easily disable a default event handler and replace it with a custom one. When you create an event handler, you specify the condition — for example, when an event meets or exceeds a threshold or meets a specified severity level — that triggers it. To specify event handler conditions, you define a set of criteria, specify a task, or select a custom event generator that triggers the event handler. For example, suppose you create an event handler that defines the criteria as a replication event with a severity level of Fatal. Then any replication event that matches that criteria is handled based on the event handler you created. Or, you can create an event handler for all events of any type that have a severity level of Fatal. An event handler is generated only if the specified task creates an event. And event handlers
52-14 Administering the Domino System, Volume 2

based on custom event generators are triggered only if the associated event generator creates the event. You can also create different handlers for different severities. For example, you may want to be notified immediately if an event has a severity level of Fatal or Failure and choose to write the information to the log file or to the Monitoring Results database (STATREP.NSF). Normal levels of events may not interest you, so you may want to create a log filter to prevent normal events and severity levels from being logged to the log file or the server console.

Event handler notification methods
Depending on the type or severity of an event, you may want to be notified immediately by an alarm, e-mail message, or server-console message. When you specify a handler notification method, you also specify where events are reported. Domino provides the notification methods listed in the table below.

Monitoring

Notification method Result Broadcast Log to database Reports the event to all users logged onto the server or to a specified group of users. Logs the event to a database, typically STATREP.NSF, on a local server. Select this method only if the specified server is reporting events to its own collection database. Mails the event to a person or to a mail-in database (typically STATMAIL.NSF) on a server in a different domain or one that uses an incompatible mail protocol. Reports the event to the Windows NT Event Viewer. Uses the mail address of an alphanumeric pager to report a modified version of an event to a pager. Runs an add-in program or specified command to correct problems automatically. Relays the event to another server that is in the same Domino domain and that runs a common protocol. These events are collected in a database, typically STATREP.NSF. Sounds an alarm on the designated server when the event occurs. Sends the event as an SNMP trap. Select this method only if the specified server is running the Event Interceptor task and the Domino SNMP Agent. Reports the event to the UNIX system log.

Mail

NTLog Pager Prog Relay

Sound SNMP Trap

UNIXLog

For more information on SNMP agents, see the chapter “Using the Domino SNMP Agent.”
Monitoring the Domino Server 52-15

Using an API to create an event notification method If you use an API, there may be additional types of notification methods. To use one of these methods, create a notification based on the name and description provided by the API. 1. From the Domino Administrator, click the Configuration tab, and open the Monitoring Configuration view. 2. Open the Names & Messages (Advanced) - Notification Methods view, and click New Notification Method. 3. Enter a description of the notification method. 4. Enter the name of the notification method.

Event types used to specify event criteria
When you create an event handler based on matching the event criteria, you must specify the type of event.
Event type Add-in Adminp Agent Client Comm/Net Compiler Database Directory (LDAP) Mail Misc Monitor Network Replica Resource Router Security Generates Messages related to the Add-in task. Messages related to the Adminp task. Messages related to agents. Messages related to the client. Messages related X.PC. Messages related to compute and compile functions. Messages related to databases. Messages related to directory services. Messages related to mail routing. Miscellaneous messages not in another event category. Messages related to events generated on the Domino Administrator by Server Monitoring. Messages related to the LAN. Messages related to replication, including event handler notifications generated by a database event generator. Messages related to system resources. Messages related to mail events. Messages related to ID files and server and database access, including event handler notifications generated by a database event generators. continued

52-16 Administering the Domino System, Volume 2

Event type Server

Generates Messages related to conditions on a particular server or server connectivity. These messages can include event handler notifications generated by Domino server event generators. Messages related to statistic alarms. Messages that have an unknown prefix and are not listed in another event category. Messages related to indexing.

Statistic Unknown Update

Web Messages related to the HTTP task. (HTTP/HTTPS)

Creating an event handler
When you create an event generator, you can launch the event handler wizard to create an event handler at the same time. You can also manually create an Event Handler document in the Monitoring Configuration database (EVENTS4.NSF). For more information on the wizard, see the topic “Using event generator and event handler wizards,” earlier in this chapter. To create an Event Handler document 1. From the Domino Administrator, click the Configuration tab, and open the Monitoring Configuration view. 2. Open the Event Handlers - All view, and click “New Event Handler.” 3. On the Basics tab in the “Server(s) to monitor” field, choose one: • Notify of the event on any server in the domain • Notify of the event only on the following servers. Then select the server from a list. 4. Under Notification trigger, choose one: • Any event that matches a criteria. Then complete these fields on the Event tab:
Field Event type Action Choose one: • Events can be any type • Events must be this type. Then select the type from the list. Event severity Choose one: • Events can be any severity • Events must be one of these severities. Then select a severity level from the list. continued Monitoring the Domino Server 52-17

Monitoring

Field Message text

Action Choose one: • Events can have any message • Events must have this text in the event message. Then type the message text.

For more information about event types and event severity levels, see the topics “Event types used to specify event criteria,” and “Event generators,” earlier in this chapter. • A built-in or add-in task event. Then click Select Event, select the event from the list, and choose one: • Events can have any message • Events must have this text in the event message. Then type the message text. • A custom event generator. Then select it from the list or click New to create a new custom event generator. (Optional) Click “Details” to view a custom Event Generator document. 5. Click the Action tab and choose the notification method. For more information on event notification methods, see the topic “Event handler notification methods,” earlier in this chapter. Note If you purchased an add-in product designed to work with server-management programs, you may see additional notification methods. 6. Choose one enablement option: • Enable this notification — To enable the notification during all hours. • Enabled only during these times — Then click the clock and move the slider to select the start and end time during which this event handler is enabled. 7. Click Save & Close.

Disabling an event handler
You may want to disable an event handler that you created. For example, if you create an event handler to help you troubleshoot replication problems, after you resolve the problems, you can disable the event handler. Then, when you need to do replication troubleshooting again, just enable the event handler.

52-18 Administering the Domino System, Volume 2

To disable an event handler 1. From the Domino Administrator, click the Configuration tab, and open the Monitoring Configuration view. 2. Open the Event Handlers - All view. 3. Open the event handler you want to disable in edit mode. 4. Click the Action tab, and choose the field “Disable this notification.” 5. Save and close.

Creating log filters
By default, Domino logs all events to the log file (LOG.NSF), which can become quite large, depending on the log level set for each event. To prevent events from being logged either to the log file or to the server console, create a log filter that specifies both the type and severity of the event to filter. Then only events that meet the specified criteria appear in the log file.

Monitoring

To create a log filter 1. From the Domino Administrator, click the Configuration tab and then open the Monitoring Configuration - Log Filters view. 2. Click “New Event Filter.” 3. On the Basics tab, select the name of the server on which you want to set log filters. 4. Click the Database tab. For the field “Log unknown types/severities?” select Yes or No to filter events from the log file. 5. Choose one: • Log All Types — Then specify a severity level. • Select types — Then check each type of event to log. 6. Click the Console tab. For the field “Log unknown types/severities?” select Yes or No to filter events from the console. 7. Choose one, and then Save & Close: • Log All Types — Then specify a severity level. • Select types — Then check each type of event to log. Tip You can also create a log filter from the server console. For more information about setting log levels, see the chapter “Using Log Files.”

Monitoring the Domino Server 52-19

Viewing event handlers and log filters
You can view default and custom event handlers and log filters. To view an event handler 1. From the Domino Administrator, click the Configuration tab. 2. Open the Monitoring Configuration - Event Handlers view. 3. Open one of these views: • All • By Action • By Author • By Severity • By Type 4. Double-click the Event Handler document to open it. To view an event filter 1. From the Domino Administrator, click the Configuration tab. 2. Open the Monitoring Configuration - Log Filters view. 3. Double-click the Log Filter document to open it.

Viewing an event report
The Monitoring Results database (STATREP.NSF) stores statistic and event information, depending on how you configured the Statistic Collector server task and event handler documents. For each event, a report records the server that originated the event; the time, severity, type and error code of the event; and a brief description of the event. To view a report 1. From the Domino Administrator, click the Server - Analysis tab. 2. Click the Monitoring Results - Events view. 3. Double-click a report to view the information.

Viewing event messages, causes, and solutions
Each event that occurs on the Domino system has an associated event message that is stored in the Monitoring Configuration database (EVENTS4.NSF). The message text often provides information about possible causes and solutions. You can view event messages by text or by type.
52-20 Administering the Domino System, Volume 2

To view an event message 1. From the Domino Administrator, click the Configuration tab. 2. Open the Names and Messages view, and choose one of these views: • Event Messages — To view all messages, sorted by type and then by severity level. • Event Messages by Text — To view all messages, sorted alphabetically by message text.

Customizing the appearance of the Domino server console and Domino Administrator console
By creating a Server Console configuration document for the server you are monitoring, you can specify the text, background, and color attributes that the Domino server console uses to display monitoring information. By default, the Domino Administrator server console uses the same attributes, but you can override the defaults and customize the appearance of the Domino Administrator server console. To customize the appearance of the Domino server console 1. From the Domino Administrator, click the Server - Status tab. 2. Open the Server Console view. 3. From the menu, select Live Console - Server - Set Server Console Attributes. 4. Select the server whose attributes you are configuring. 5. Click the color palette to select a color attribute for the background and event text. Look at the console display beneath the palette to view your choices in real time.
Console display Console Background Normal Events Fatal Events Failure Events Warning (High) Events Warning (Low) Events Default color Black Light grey Red Magenta Yellow White

Monitoring

6. (Optional) To reset the colors to the defaults, click Reset to Defaults. 7. Click Save & Close.

Monitoring the Domino Server 52-21

To customize the appearance of the Domino Administrator server console 1. From the Domino Administrator, click the Server - Status tab. 2. Open the Server Console view. 3. From the menu, select Live Console - Local - Set Console Properties. 4. Click the Color tab. For the field “Use server default,” do one: • Check the field to use the defaults set in the Server Console Configuration document for the server. This is the default. • Clear the check box, and then select a color for background, text, and severity levels. 5. Click the Filters tab, and clear the check box for any status level you do not want to log to the Domino Administrator server console. The default is all levels are checked. 6. Click the Attributes tab, and then select the font, size, and appearance for the local console text. To view a Server Console Configuration document 1. From the Domino Administrator, click the Configuration tab. 2. Open the Monitoring Configuration - Console Attributes view.

Using the Domino Administrator server console to monitor events
When you use the Domino Administrator server console to monitor events, you can set a stop trigger for an event. The stop trigger causes the console to pause and display only the event and the next 10 lines of console text when the event occurs. In addition, you can retrieve additional information about error messages, including possible causes and solutions, and create event handlers. To set or remove a stop trigger After you troubleshoot the problem for which you set the stop trigger, be sure to remove it. 1. From the Domino Administrator, click the Server - Status tab. 2. Open the Server Console view. 3. Click Pause or Stop to stop the logging of information to the console. 4. Do one: • To remove a stop trigger, select Live Console - Local - Remove Stop Trigger. • To set a stop trigger, select the event for which to set a stop trigger. Then from the menu, select Live Console - Set Watch.

52-22 Administering the Domino System, Volume 2

5. Do one to restart the Domino Administrator server console: • If you clicked Pause, click Resume. • If you clicked Stop, click Live. To get error information 1. From the Domino Administrator, click the Server - Status tab. 2. Open the Server Console view. 3. Click Pause or Stop to stop the logging of information to the console. 4. Select the event error message for which you want more information. 5. Select Live Console - Lookup Error. 6. Do one to restart the Domino Administrator server console: • If you clicked Pause, click Resume. • If you clicked Stop, click Live. To create an event handler 1. From the Domino Administrator, click the Server - Status tab. 2. Open the Server Console view. 3. Click Pause or Stop to stop the logging of information to the console. 4. Select the event for which you want to create an event handler. 5. Select Live Console - Create Local Event Handler. 6. If an event handler for the specified event already exists, you are prompted to edit the Event Handler document or create a new one. 7. Do one to restart the Domino Administrator server console: • If you clicked Pause, click Resume. • If you clicked Stop, click Live. For more information on event handlers, see the topic “Creating an event handler,” earlier in this chapter. To start or stop the Domino Administrator server console 1. From the Domino Administrator, click the Server - Status tab. 2. Open the Server Console view. 3. Click Live to start the console, or click Stop to stop it.

Monitoring

Monitoring the Domino Server 52-23

Statistics and the Domino system
Domino continuously generates and updates server statistics, which you can collect and monitor in a number of ways. From the server, you can use the Show Statistic or Show Platform Statistic commands. From the Domino Administrator, you can create statistics profiles and charts.

Monitoring from the server
To collect server statistics and store them in the server’s Monitoring Results database (STATREP.NSF), the Statistic collector task (also called the Collector task) must be running on the server or on a server designated to collect statistics from one or more other servers.

Monitoring from the Domino Administrator
To use the Domino Administrator to monitor statistics, you must set up statistic Administration Preferences to generate statistics reports, which are stored in the local Monitoring Results database (STATREP.NSF). Then you can use the Domino Administrator to monitor and chart the statistics. In the Domino Administrator, the Collector task collects statistics locally from specified servers and saves them to memory. For example, when you create real-time charts, it collects statistics from the servers listed in the statistics profiles or those selected for charting. For more information on setting Administration Preferences, see the chapter “Setting Up and Using Domino Administration Tools.”

Statistic Collector task
The Statistic Collector task, formerly known as the Collector task, gathers statistics for one or more servers in a domain and, by default, creates statistic reports in the Monitoring Results database (STATREP.NSF). There are two ways to set up statistic collection. You can start the Statistic Collector task on each server, which then collects its own statistics and creates reports in the local Monitoring Results database. Or you can start the Statistic Collector on one server that you set up to collect statistics from one or more servers and create reports in a specified Monitoring Results database. For example, if you use one designated server to collect statistics from other servers, you start the Statistic Collector task only on that server and create a Server Statistic Collection document to identify the servers from which to collect statistics. Reports are created in the Monitoring Results database (STATREP.NSF) on the designated server. The Statistic Collector task loads automatically on a server if it is in the task line of the NOTES.INI file.
52-24 Administering the Domino System, Volume 2

In the Domino Administrator, the Statistic Collector starts when you start the Domino server monitor, when you chart real-time statistics, or when you access the Server - Statistic tab. You can also set a Monitoring Administration Preference so that the Statistic Collector task starts automatically when you start the Domino Administrator. The Statistic Collector task continually adds new servers from which it gathers statistics as you monitor or chart statistics from additional servers. For example, in the Domino server monitor, if you begin monitoring the servers in the Acme1monitoring profile, the Collector task begins collecting statistics from the servers listed in the Acme1 profile. Then if you switch to charting and chart the statistics in the AcmeEast statistics profile, the Statistic Collector task simply adds the servers in the AcmeEast statistics profile to the list of servers from which it is gathering statistics. It does not stop gathering statistics from the servers in the first group you monitored in the Acme1 profile.

Setting Administration Preferences for monitoring and statistics
You must set monitoring Administration Preferences to generate statistics and reports and to specify the location from which you are monitoring statistics. You set statistics Administration Preferences to enable the reporting of statistics to the local Monitoring Results database (STATREP.NSF), which is used when creating statistics charts. To generate statistic event generators, you must enable statistics alarms. For information on setting preferences, see the chapter “Setting Up and Using Domino Administration Tools.”

Monitoring

Creating a Server Statistic Collection document
You use a Server Statistic Collection document to designate one collector server and one or more other servers from which the collector server collects statistics. By default, the collector server reports the statistics to the local Monitoring Results database (STATREP.NSF), unless you specify a different database. To create a Server Statistic Collection document 1. From the Domino Administrator, click the Configuration tab, and open the Monitoring Configuration - Server Statistic Collection view. 2. Click “New Statistics Collection.” 3. On the Basics tab, select the collecting server.

Monitoring the Domino Server 52-25

4. Choose one of the following: • All servers in this domain — To collect statistics from all servers connected to the collector server. • All servers that are not explicitly listed to be collected — To collect statistics from all servers in the domain from which statistics are not currently being collected. • From the following servers — Then choose the servers from which to collect statistics. 5. To log statistics to a database click the Options tab. Check the field “Log statistics to a database” and then complete these fields:
Field Database to receive reports Action Enter the name of the database to store the reports. The default is STATREP.NSF.

Collection report interval Enter the number of minutes between reports. The minimum is 15; the default is 60. Collection alarm interval Enter the number of minutes between alarms. The minimum is 15; the default is 60. Statistic filters Select the types of statistics to omit from the report.

6. Click Save & Close.

Platform statistics
In addition to tracking server statistics, Domino tracks operating-system performance statistics. You can view these statistics from the Domino Administrator, along with your Domino statistics, which helps you with Domino server monitoring and tuning. You can include platform statistics in any statistic monitoring task you perform with the Domino statistics, including using them in monitoring and statistic profiles, and charting them. There may be slight overhead incurred while running platform statistics, however the overhead is insignificant. No disk space is consumed by enabling platform statistics, since no log files are created. As with Domino statistics, disk space is used only if you log platform statistics to the log file or to the Monitoring Results database (STATREP.NSF). The amount of disk space used depends on the frequency of capture.

52-26 Administering the Domino System, Volume 2

By default, the Statistic Collector task continuously gathers these statistics: • • • • • Logical disk — Statistics for individual disks and total percent use of all disks Paging file — Statistics that show use of paging files Memory — Statistics showing memory allocation and use, including available memory Network — Statistics for individual network adapters and cumulatively for all the network adapters on the system Process — Statistics that show the percent of CPU use, along with process ID of Domino tasks, if the task is present. (Information for idle tasks is reported as zero.) System — Statistics on the information captured — for example, a summary of system CPU use and queue length.

Platform statistics on partitioned servers
When collecting statistics from a partitioned server, Domino collects platform statistics that pertain to the system as a whole, not to an individual partition. For example, memory use or CPU use statistics are the same value on a partitioned and non-partitioned server. The only statistics that are specific to a partition are those that reflect tasks, such process statistics, where one partition might run 10 tasks, while another partition runs 15 tasks. Confirming platform statistics metrics using other performance monitoring tools Because of the differences in sampling intervals, you cannot use native monitoring tools to confirm platform statistics. There will be discrepancies between platform statistics and those obtained using Perfmon (for Windows NT or Windows 2000) or a system command, such as this UNIX command:
iostat /vmstat/ netstat

Monitoring

Viewing platform statistics
From the console, you can use the Show Stat Platform command to view all platform statistics or just a subset of them. When you show all the platform statistics, they display alphabetically in these categories: • • • • Logical disk Memory Network Paging file
Monitoring the Domino Server 52-27

• •

Process System

To view a list of all statistics To view a list of all statistics, use the Show Stat command. For more information on server commands, see the appendix “Server commands.”

Controlling platform statistics reporting
From the console, you can use the Platform command to set a sampling period that determines how often statistics are gathered, and you can pause and resume the collection of platform statistics. In addition, you can control how often statistics are reset to zero and samplings are gathered. Three types of statistic values are reported: • Fixed — Statistic values that do not change. They include information such as number of disks, or an assigned name. For example, in the statistic Platform.LogicalDisk.<identifying number>.PctUtil, the identifying number is a variable that identifies the disk. This information does not change when you issue a Platform Reset command. Primary — Statistic metrics from which secondary statistics are derived. For example, the total paging file utilization statistic (Platform.PagingFile.TotalPctUtil) is the basis for secondary statistics that calculate the average and the peak values (Platform.PagingFile.TotalPctUtil.Avg and Platform.PagingFile.TotalPctUtil.Peak). Secondary — Statistic values that are a combination of or are derived from primary statistics. For example, these are often average, minimum, or peak statistics.

For information on using the Platform command, see the appendix “Server Commands.”

Evaluating platform statistics
Use this information to help you evaluate platform statistics.

Using Perfmon on Windows 2000 and Windows NT systems
If you use Perfmon on Windows NT or Windows 2000, some counters may report inaccurate information because of the way that Perfmon collects statistics. Logical disks that are actually very busy may report average queue lengths of zero. Unplugged network adapters may show traffic.
52-28 Administering the Domino System, Volume 2

Network statistics
On Solaris, AIX, and OS/400®, Domino provides statistics for a maximum of ten network adapters. On Windows 2000 and Windows NT, there is no limit on the number of network adapters. The loopback interface is not included in the list of adapters. On AIX, only Ethernet and token ring network adapters are supported.

Process statistics
On Windows 2000 and Windows NT, when you view process statistics, the Percentage Total Domino CPU Utilization value may be greater than the Total System CPU Utilization. This is because the CPU utilization value for each individual process is calculated based on the total number of processes used in a sampling interval. On Windows 2000 and Windows NT, Domino process names include the letter “n” as a prefix. For example, in Perfmon, Adminp — the process name for the Administration Process — is nadminp. To maintain platform-independence in naming, Domino does not include the prefix on any platform statistics. On Solaris, AIX, and OS/400 platforms, process statistics indicate how busy the processes are, but these are not absolute values. On these platforms, the utilization is based on how busy the processes are in the current sampling period as compared to how busy they were in the previous sampling period. For example, if a process reports 30% utilization in the first sampling and 60% in the second, the process is twice as busy. On all platforms, by default, the performance statistics for processes that are idle have the value zero.

Monitoring

Logical disk statistics
On Windows NT, Windows 2000, and Solaris, the values for disk utilization counters may exceed 100%, indicating that the disks are being heavily utilized. Similarly, on multiprocessor systems, the individual CPU utilization for a process may exceed 100%, depending on the number of processors in the system. On OS/400, there are statistics for a maximum of ten logical disks (auxiliary storage pools).

Monitoring the Domino Server 52-29

System statistics
On Windows 2000 and Windows NT, the value of the combined CPU utilization statistic (Platform.System.PctCombinedCpuUtil) is not defined as sum of the user and privileged CPU utilization values (Platform.PctUserCpuUtil and Platform.PctPrivilegedCpuUtil). However, on Solaris and AIX, the value of the combined CPU utilization statistic is defined as sum of the user and privileged CPU utilization values.

Viewing information about platform statistics
To view information about platform statistics, open the Monitoring Configuration database (EVENTS4.NSF), which includes a complete list of platform statistics and average and peak values, where applicable. In addition, the Monitoring Configuration database also lists equivalent metrics from other performance-monitoring tools, as well as displays statistic descriptions and reports. To view a list of platform statistics and definitions 1. Click the Files tab. 2. Open the Monitoring Configuration database (EVENTS4.NSF). 3. Open the view Names & Messages (Advanced) - Platform Statistic Names. 4. Select one: • Domino 6 — To view platform statistics available for both Domino 5 and Domino 6 servers. • R5 — To view platform statistics available only for Domino 5 servers. 5. Select a statistic, and click the triangle to expand the view for average and peak values, if available. 6. Double-click the name of the statistic to open the Statistic Description document. To view statistics reports You can view a predefined set of platform statistics reports for each server. For more information on viewing platform statistics reports, see “Viewing statistics reports” later in this chapter.

Disabling platform statistics
By default, platform statistics are enabled. To disable platform statistics, enter this setting in the NOTES.INI file, and then restart the Domino server:
Platform_Stastics_Disabled=1 52-30 Administering the Domino System, Volume 2

Using the Domino Administrator to monitor statistics
Using the Domino Administrator, you can create a statistic profile that you use to monitor the same set of statistics periodically or to compare performance on different servers. You can view statistic reports or view real-time statistics. You can also chart statistics in real time or historically. You can monitor statistics in the following ways: • • • • • • • View statistic reports of the most commonly used statistics. View default statistic thresholds Define new statistics View a list and description of all statistics Export statistics to a spreadsheet Mail statistics to a mail-in database Create a statistic profile

Monitoring

Viewing statistics reports
Domino includes these default statistics reports: • • • • • • • • Calendaring and Scheduling Clusters Communications Mail and Database Network Platform System Web Server & Retriever

The information in these reports provides a subset of statistics in each category. To view all statistics, use the Show Statistic command at the console or from the Domino Administrator, click the Server - Statistics tab. To view statistics reports 1. From the Domino Administrator, click the Server - Analysis tab. 2. Click the Monitoring Results view, and select Statistics Reports. 3. Select a report.

Monitoring the Domino Server 52-31

Viewing default statistic thresholds
Each Domino statistic has an associated default threshold that you use when you create an event generator. Statistic thresholds are stored in the Monitoring Configuration database (EVENTS4.NSF). To view a default statistic threshold 1. From the Domino Administrator, click the Configuration tab. 2. Open the Names and Messages view, and then open the Default Statistic Threshold view

Viewing descriptions of statistics
The Monitoring Configuration database (EVENTS4.NSF) includes a complete list of statistics. For more information on a statistic, select the statistic and view the Statistic Description document. To view a statistic description 1. Click the Files tab. 2. Open the Monitoring Configuration database (EVENTS4.NSF). 3. Open the view Names & Messages (Advanced) - Statistic Names. 4. Double-click the name of a statistic to open the corresponding Statistic Description document.

Creating a new statistic
You can create a new statistic and then use it in statistic profiles and statistic charts. To use a new statistic to create a statistic event generator, you must specify a threshold. You can create an operating system statistic for use as a template. You can create a new statistic template that includes a variable. For example, you can create a statistic that includes the variable <portname>. Then to collect statistics on more than one port, copy the statistic and replace the variable with the actual port name. When you create a statistic, you define the type of data the statistic will collect and the measurement unit. You also specify whether it is an operating system statistic or a trended statistic. Trended statistics are gathered by the Activity Trends Collector task, and used to provide activity trends statistics information. The Activity Trends Collector task is used by the IBM Tivoli Analyzer for Lotus Domino. For more information on the IBM Tivoli Analyzer for Lotus Domino and resource balancing, see the topic Activity Trends for IBM Tivoli Analyzer for Lotus Domino.
52-32 Administering the Domino System, Volume 2

For more information on the IBM Tivoli Analyzer for Lotus Domino and resource balancing, see the chapter “Using IBM Tivoli Analyzer for Lotus Domino.” To create a new statistic 1. From the Domino Administrator, click the Configuration tab, and open the Monitoring Configuration - Names & Messages (Advanced) - Statistic Names view. 2. Click “New Statistic.” 3. On the Basics tab, complete these fields:
Field Statistic name Data type Action Enter the name of the new statistic. Choose one: • Text • Number • Time Statistic unit Enter one: • The unit in which the statistic is measured — for example, bytes or minutes • The word “none,” if this is a text statistic Statistic description Enter a description of the statistic

Monitoring

4. Click the Advanced tab, and do one of the following: • If you selected Text or Time as the data type, go on to Step 5. • If you selected Number as the data type, in the Normal values field, enter a normal value for this statistic — for example, 350KB — or the word “varies,” if the normal value of the statistic varies. 5. For the field “Is an OS statistic?” the default is No. Check Yes if the statistic is an operating system or platform statistic. 6. For the field “Is an Activity statistic?” the default is No. Check Yes if the if the statistic is generated using the Activity Trends Collector task, and then check one or more of the following: • Has trended values — If the statistic has both trended and last-occurrence values. • Has prime/24-hour values — If the statistic includes values for the prime shift and for a 24-hour period. • Is user selectable — If the statistic will be used as a selection — for example, in a dialog box. • Used in resource balancing — If the statistic will be used when balancing resources using the IBM Tivoli Analyzer for Lotus Domino.
Monitoring the Domino Server 52-33

7. For the field “Is a statistic template?” the default is No. Check Yes if the statistic will be used to create other statistics using a variable — for example, <portname>. 8. For the field “Useful for thresholds?” the default is No. Check Yes if this statistic will be used to generate statistic alarms. To use this statistic in a statistic event generator, you must define a threshold. Complete these fields:
Field Threshold operator Action Select the condition against which to evaluate the threshold: • • • • Threshold value Event severity Suggested response Useful in setup Less than Greater than Multiple of Percentage of

Enter a number. Select the severity that will cause an alarm. (Optional) Enter an explanation of a how to resolve the event that caused the alarm. Click Yes to use the statistic during setup and include this statistic when a new Monitoring Configuration database (EVENTS4.NSF) is created.

9. Click Save & Close.

Exporting statistics to a spreadsheet
To perform further analysis, you can export a statistics report to a spreadsheet. 1. From the Domino Administrator, click the Server - Analysis tab. 2. Open the Monitoring Results - Statistics Reports view. 3. Select the report you want to export, and click File - Export. 4. In the Export dialog box, enter a name for the file, and select a file type. 5. Click Export. 6. For “How much to export,” choose one: • All documents • Selected documents 7. For “Detail to incorporate,” check “Include view titles” to include titles.

52-34 Administering the Domino System, Volume 2

Using mail-in statistics
If you can access Notes mail on a server, you can collect statistics from the server and mail them to yourself. Use mail-in statistics when the Domino Administrator is not available or you do not have administrator access to a server. When you start the Stats task, Domino creates a mail-in database (STATMAIL.NSF) for the server. The title of the mail-in database is server Stats/org. For example, for the Everest server in the Acme organization, the mail-in database is titled Everest Stats/Acme. By default, during server registration, a Mail-in Database document is created. This document, which is stored in the Domino Directory, defines the properties and location of a database that can receive mail. To open the document from the Domino Administrator, click the People & Groups tab, and then open the Mail-in Databases & Resources view. You can mail all or a subset of statistics to yourself. The names of all statistics are listed on the Configuration tab in the Monitoring Configuration - Names & Messages (Advanced) view. The category for a statistic is the first part of the statistic name. For example, the category for the statistic Disk.C.Free is Disk. To mail statistics to yourself 1. Open the Monitoring Configuration database (EVENTS4.NSF). 2. Choose Create - Mail - Message. 3. Complete these fields, and then send the message:
Field To Subject Action Enter the title of one or more mail-in databases for one or more servers. Do one: • Enter a statistic category — for example, disk or platform — to get a subset of statistics. • Enter the name of one statistic — for example, Disk.C.Free. • Use an asterisk to indicate a group of specific statistics. For example, enter Disk.C.* to report all disk statistics for drive C. • Leave the field blank to mail all server statistics.

Monitoring

Monitoring the Domino Server 52-35

Charting statistics
You can graphically display the statistics generated by Domino, by creating statistics charts. To chart sets of statistics on a regular basis, you can define statistics profiles. Using statistics charts you can track and visualize statistics in real time or historically. Real-time charts reflect the current server activity. Historical charts pull information from the local Monitoring Results database (STATREP.NSF). You can also create statistic profiles so that you can chart a specified set of statistics routinely. To create statistics charts you must enable the field “Generate statistic reports while monitoring or charting statistics” in Administration Preferences, and the Domino server monitor must be running. For more information on setting Administration Preferences for statistic monitoring, see the chapter “Setting Up and Using Domino Administration Tools.” When you chart statistics, you choose the servers and the statistics to chart. Using the charting feature you can: • • • • • • • Create and edit statistic profiles Remove existing statistic profiles or combine them into a new one Gather historical statistics over a specified period of time View the details of each statistic View an isolated statistic Start and stop real-time charting dynamically Use right-click functionality to add a statistic event generator

Note Charting is not available in the Web Administrator.

Creating statistic profiles
You can create a statistic profile to capture information about specific performance patterns or problems. For example, if your system has a slow response time, create a profile to gather statistics on memory, buffer pool size, database cache, and number of users. Then save the statistic profile so that you can later run the same analysis. Note Statistic profiles are not available in the Web Administrator.

52-36 Administering the Domino System, Volume 2

To create a statistic profile 1. From the Domino Administrator, click the Server - Performance tab. 2. Do one: • If there are no statistics profiles displayed in the statistic profiles list, click Add. • If there is a statistic profile currently displayed, choose Performance Monitor - Saved Statistics Profiles - New to clear the list, and then click Add. 3. Select the domain and server for which you are creating the statistic profile. 4. Choose one: • Bundled statistics — To create a group made up of predefined sets of statistics. • Individual statistics — To create a new group made up of selected individual statistics.

Monitoring

5. Click the arrow to open a statistic category. Select the specific statistic, and then click Add. 6. Click Done, choose Performance Monitor - Saved Statistics Profiles Save As, and then type a name for the statistic profile.

Displaying and manipulating statistic charts
You can view a chart of historical or real-time performance statistics. Use a real-time chart to view a current performance problem or assess current peak usage. Use a historical chart to monitor statistics over period of time. Note The charting feature is not available in the Web Administrator. To scale the data Before you chart statistics that are in vastly different number ranges — for example, dead mail, which has a usual range of 0 to 10, and disk space, which might be in gigabytes — enable Autoscale. Disable Autoscale when you chart statistics that all have a low number range — for example, from 0 to 500 To change the color of a statistic 1. From the Domino Administrator, click the Server - Performance tab. 2. Click the color bar on the statistic list. 3. In the Line Color dialog box, click the arrow, and do one of the following: • Click the Notes tab, and select a predefined color. • Click RGB and then use the sliders or dropper to create a custom color. When you have the color you want, click the color that displays in the box.
Monitoring the Domino Server 52-37

To change the layout of the panes You can change the layout of the chart display using the Performance Monitor menu or the layout button:

1. From the Domino Administrator, click Server - Performance. 2. From one of the Statistics charting views, choose Performance Monitor - Layout, and then choose one: • Maximized — To display only the statistic chart. • Maximum Width — To display the list of statistics and the statistic chart. • Maximum Height — To display the statistic chart and the server pane. • Restore — To restore the original layout. To manipulate statistic performance charts The following table describes ways to view the information on statistics performance charts.
Task Stop or start the charting Action Click the Stop/Start button.

Get a numerical representation of Click the statistic in the profile list. Then a graphical statistic look at the bar area between the profile list and the chart. Get a textual representation of the statistic chart Chart an isolated statistic Double-click the chart to display a document that you can edit and print. Double-click a graph line.

52-38 Administering the Domino System, Volume 2

To add or remove a statistic You can add or remove a statistic or a server from a statistic chart without affecting the statistic profile. 1. Select the statistic profile. 2. Do any of the following:
Task Dynamically remove a statistic from the chart displayed Dynamically add a statistic Dynamically add a server Dynamically remove a statistic Action In the profile list, clear the check box next to the statistic. Click Add, and then select a statistic. Click the down arrow, and then select a server. Select a statistic in the profile list, and then click Remove.

Note Save the profile to keep any changes.

Monitoring

Modifying statistic profiles
To modify a statistic profile, you can add or delete statistics, add servers, or save or delete the entire profile. To add or remove statistics and servers from a profile for the current session only, make the changes, but don’t save the profile. To modify a statistic profile 1. From the Domino Administrator, click the Server - Performance tab. 2. Select a statistic profile from the list, and do any of the following:
Task Add a statistic Action 1. Click Add. 2. Select the Domain and server, and then select the statistic. 3. Click Add Statistic. 1. Click the down arrow next to the Add button, and then click Add Server. 2. Specify the Domain and server, and then click Add. Select the statistic, and click Remove. 1. Select the name of the profile in the Statistics profile field. 2. Click Performance Monitor - Saved Statistics Profiles - Delete.

Add a server

Delete (remove) a statistic from a profile Delete the entire profile

Monitoring the Domino Server 52-39

3. To save the profile, do one: • Click Performance Monitor - Saved Statistics Profiles - Save — To overwrite the original statistic profile with the changes. • Click Performance Monitor - Saved Statistics Profiles - Save As — To save the modified statistic profile under a new name, leaving the original statistic profile intact.

Domino server monitor
The Domino server monitor displays real-time statistics and provides a visual representation of the status of servers and server tasks. You can view all servers or a subset of servers, and you can view the status by state or by timeline. The Domino server monitor creates a set of default system profiles that include all servers, servers in each domain, servers in clusters in each domain, and servers in the Favorites bookmark file. In addition, you can create custom profiles that specify the servers, server tasks, and statistics to monitor. For example, you can create a mail-server profile and select only server tasks and statistics related to mail delivery. You can use the server monitor to perform these tasks: • • • • • • • • • View server monitor statistics by timeline or by state Display past error states only Add or remove a server to monitor Add or remove server tasks or statistics from a selected server or from all servers Create and edit server monitor profiles Move to the Status or Messaging tab to troubleshoot an error report Sort statistics columns that have numerical values Use right mouse functionality to retrieve additional information about a statistic For numerical statistics, display the difference between the current statistic and the statistic generated one hour earlier

Note The Domino server monitor is not available in the Web Administrator.

52-40 Administering the Domino System, Volume 2

Starting the Domino server monitor
The Domino server monitor does not start by default; however, you can change the monitoring defaults in the Administration Preferences so that it does. To start or stop the server monitor manually 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Do one: • To start the server monitor, click the Green arrow. When the server monitor is running, the arrow changes to a Red stop button. • To stop the server monitor, click the Red stop button. To start the server monitor automatically 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Click File - Preferences - Administration Preferences. 3. Click Monitoring. 4. Enable “Automatically monitor servers at startup.” For more information on setting Administration Preferences, see the chapter “Setting Up and Using Domino Administration Tools.”

Monitoring

Viewing the Domino server monitor
The Domino server monitor has two views: By Timeline and By State. The By Timeline view displays historic information about server status. The By State view displays real-time statistics and status of server tasks. By Timeline view Use the By Timeline view to track the status of server tasks. In this view, you can see which tasks are having problems and approximately when the problems occurred. Using the Column scale selector, you can choose a data display time interval of 1 to 60 minutes. As you increase the time interval, you increase the summation of the data. You can change the sort order of both the Server Name and Server Status columns in this view. By State view The By State view displays a detailed status of Domino servers and their associated tasks and statistics. Each server and server task displays a status indicator that identifies its current state. Using the option “Display past states reporting errors exclusively,” you can view only error states. If a statistic is numeric, you can display the difference between the current statistic value and its value from one hour earlier. A differences icon appears in the statistic column and points to the previous value. In this
Monitoring the Domino Server 52-41

view, you can change the sort order of the Server Name and Server Status columns and of any Statistic Value columns that contain numeric values. To view the Domino server monitor 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Choose one view: • By Timeline — Then set the Column scale selector to a value from 1 to 60 minutes. • By State — Then to view past errors only, select the check box “Display past states reporting errors exclusively.” 3. Click Start to start the server monitor. Note If you enable “Automatically monitor servers at startup” in the Administration Preferences, the server monitor starts automatically and monitors the most recently viewed profile.

Setting task status indicators for the Domino server monitor
In the By State view, each task that you monitor has an associated status level. You determine which status levels to monitor, then each task that you monitor displays a current status indicator or task error. For example, you may want to turn off the status indicators for tasks that are not running or those that are running without a problem. You may, however, want to see tasks that are generating failure or fatal errors. The status level indicators display which tasks are generating errors that may need your attention. To enable task status indicators 1. From the Domino Administrator, click Server - Monitoring. 2. Check the box to enable the following task indicators:
Indicator Fatal Failure Warning Not responding Not running Running Meaning The task is running, but fatal errors are being generated. The task is running, but failure errors are being generated. The task is running, but warning errors are being generated. The task is running slowly. The task has not been running since the server monitor started. The task is running without a problem.

52-42 Administering the Domino System, Volume 2

Profiles and the Domino server monitor
To facilitate monitoring servers, tasks, and statistics, the Domino server monitor creates a set of default profiles: • • • • All servers — Includes all servers in all domains you are monitoring, as listed in Administration Preferences Domain name Domain — Includes all servers in the named domain Favorites — Includes all servers in the Favorites bookmark file Clusters — Includes clusters within the domains being monitored

By default, the Domino server monitor contacts servers in the currently displayed profile and any profiles that have been displayed since the monitor started. To customize the profiles that the Domino server monitor uses, you can do any of the following: • • • Modify a default profile Create a new profile Specify the profiles to monitor on startup

Monitoring

Note The Domino server monitor and profiles are not available in the Web Administrator.

Modifying a default profile in the Domino server monitor
You can add tasks or statistics to a default profile. If you add or remove a server from a default profile, Domino prompts you to save the profile with another name. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Select a default profile. 3. From the Monitoring menu, select one of the following: • Monitor New Task • Monitor New Statistic • Remove Task • Remove Statistic 4. Choose one or more tasks or statistics from the task list, and then click OK. Note You do not need to save the profile. The change remains in effect when you end the Domino session

Monitoring the Domino Server 52-43

Creating a custom profile in the Domino server monitor
To create a custom profile, you modify a default profile and then save it with a new name. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Select a system profile to modify. 3. To add or remove tasks or statistics, do the following: a. Select the server whose tasks or statistics you want to modify. b. From the Monitoring menu, select one of the following: • Monitor New Task • Monitor New Statistic • Remove Task • Remove Statistic • Select the task or statistic to add or remove. 4. To add a server, select Monitoring - Monitor New Server, and then select the server from the list. 5. To remove a server, select the server to remove, and then select Monitoring - Remove Server. 6. Choose Monitoring - Save as, and enter a new profile name.

Specifying profiles to use when you start the Domino server monitor
By default, the profile that was being monitored when you stop the server monitor is the profile that will be monitored when you start the server monitor. To override this default behavior, you can specify which profiles to monitor when you start the Domino server monitor. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Select a server profile. 3. From the Monitoring menu, select Profile Properties. 4. Make sure the name of the profile you want to monitor at startup is displayed. 5. Check “Contact servers in this profile at startup.” Tip You can also rename a nonsystem profile in Profile Properties.

Using shortcuts in the Domino server monitor
The Domino server monitor includes shortcuts that provide additional information on the server and server task status without having to move from the Server - Monitoring tab.

52-44 Administering the Domino System, Volume 2

You can perform the following tasks to troubleshoot server performance using the Domino server monitor: • • • Open a different Domino Administrator tab from the Domino server monitor Display the differences in current and previous statistic values View additional information about a server or server task

• Create an event handler for a server that is down Note The Domino server monitor is not available in the Web Administrator. Example using the Domino server monitor Suppose you are monitoring eight servers and are troubleshooting errors. Server Hub-E/East/Acme appears at the top of the server list and displays a failure indicator. In the By State view, you notice that one of the status indicators is reporting a Failure error. You can tell from the column which server task is reporting the error, but you still don’t know what the error is. Hover over a task status indicator or to see a brief explanation of the problem. To take immediate constructive action on the server, you select the server, right click and select Display Status Tab. You are now ready to diagnose and take corrective action from the Server - Status tab. Or perhaps you are monitoring 14 servers, and troubleshooting dead mail statistics (dead.mail). To see which servers have the highest amount of dead mail, sort the statistic column so that the servers with the most dead mail messages appear at the top. To get an idea of when the dead mail really started piling up, locate the cursor in the Dead statistic column and right click. Select Show Statistic’s Difference to see if the error occurred within the last hour. To release the dead mail, right click and select Display Messaging tab to switch to the Messaging - Mail tab. To open a different Domino Administrator tab from the Domino server monitor 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Select a server. 3. From the Monitoring menu, select one: • Display Status Tab — To view the status and access the Server Console to issue commands for the selected server • Display Messaging Tab — To monitor mail tracking for the selected server

Monitoring

Monitoring the Domino Server 52-45

To display differences for statistic values For numerical statistics, you can display the difference between the current statistic value and its value from one hour earlier. A delta icon appears in the statistic column when the earlier, or “differences” value is displayed. If the server monitor has been running less than one hour, it displays the difference between the current statistic value and the oldest value available. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Click in the statistic column to select the statistic. 3. From the Monitoring menu, select “Show Statistic’s Difference.” 4. To remove the difference value and icon, click the statistic column, and chose Monitoring - Show Statistic’s Difference again. To view additional information about a server or task 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Do one: • Server tasks — In either view, locate the cursor in the tasks frame and hover over the error indicator to see what event cause the error. • Servers — In either view, locate the cursor in the server pane and hover over the error indicator to see what event cause the error. To create event handlers and event generators You can generate statistic events and invoke event handlers when a server goes down or comes back up, when a task reports an error, or when a statistic has reported a particular threshold. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Do one: • Locate the cursor in the server pane and right click. • Locate the cursor in the tasks pane and right click. Select “Create event handler” and then select one of the following to create an event handler when a task reports an error. Any Error (Local) Current Error (Local) Current Status (Local) Current Error (On Server) • Locate the cursor in the statistics pane and right click. Select “Create event generator” and then select either local or server to create a new statistics event generator.
52-46 Administering the Domino System, Volume 2

Chapter 53 Using the Domino SNMP Agent
This chapter provides information about the Domino Simple Network Management Protocol (SNMP) Agent and the Domino Management Information Base (MIB), which allow aspects of Domino to be monitored and managed by third-party management stations.

The Domino SNMP Agent
The Domino SNMP Agent enhances the monitoring and control features of Domino by enabling third-party management stations, which use industry standard SNMP, to manage aspects of the Domino server. It consists of: • LNSNMP — An independent application that receives trap notifications from the Event Interceptor and then sends them to the management station using the platform-specific, master SNMP Agent. LNSNMP also handles requests for Domino-related information from the management station by passing the request to the QuerySet Handler and responding back to the management station. LNSNMP includes the: • Recent Trap Table — A dynamic table stored in LNSNMP containing the last ten trap notifications sent from the Event Interceptor. • Trap Generator — Part of the Domino SNMP Agent that receives Domino events from the Event Interceptor and sends them to the management station using the master SNMP Agent. • QuerySet Handler — An add-in task that queries server statistics information and sets the value of configurable Domino-based parameters. The QuerySet Handler returns Domino statistics information to LNSNMP, which then forwards the information to the management station using the platform-specific, master SNMP Agent. Event Interceptor — An add-in task that responds to the SNMP Trap notification for Domino Event Handlers by instructing the Trap Generator to issue a trap.

Monitoring

53-1

The Domino SNMP Agent’s main functions
The agent provides: • • • • • Out-of-band server status through the MIB Control of a Domino server through SNMP Real-time alerts on server status Forwarding of Domino events as SNMP traps Domino statistics through the MIB

The Domino SNMP Agent supports SNMP version 1. Out-of-band server status through the MIB The Domino SNMP Agent constantly monitors the status of the server indirectly through a Domino SNMP Agent server add-in task using IPC to determine whether the server is up or down. The Domino SNMP Agent is not a Lotus Notes API application; all of its status information is gathered out of band. Control of a Domino server through SNMP The following three control functions are available through SNMP: • • • Stop the Domino server Start the Domino server Reboot the operating system Note Rebooting is not supported on the zSeries® (S/390) platform. As a security feature, these functions are not available by default. Each function must be configured on a per-server basis. Real-time alerts on server status The Domino SNMP Agent constantly monitors the status of the server. Changes in status are sent as SNMP traps. Real-time alerts on server status significantly enhance monitoring whether a server is up or down in three ways: • • The information is provided in real-time. The information is available out-of-band. Determining whether the server is up or down does not require the Notes client or Domino server.

53-2 Administering the Domino System, Volume 2

The information is qualitatively better. Instead of two states, up or down, SNMP can determine seven states or events as follows:
Message Status Specific trap Clearing trap number number 11 12

Domino server is up: [server name] Normal (This server has been started by a console command or using SNMP.) Domino server is shut down: Disabled [server name] (This server has been shut down by a console command or using SNMP.) Domino server pulse has failed: [server name] (This server is excessively busy or unresponsive to the SNMP pulse.) Domino server pulse is restored: [server name] (This server is no longer busy and now responding to the SNMP pulse.) System is rebooting (The Domino SNMP Agent is rebooting the entire system.) Warning

12

11

13

14

Monitoring

Normal

14

13

Informational

15

N/A

Domino server is not responding: Critical [server name] (This server may have crashed or hung.) Domino server is now responding: [server name] (This server is now responding again.) Normal

16

17

17

16

Note The above traps are all Generic number 6. The most important additional state is whether the server has been disabled intentionally. This avoids situations such as paging support staff during periods of routine maintenance. The method for determining the server state is a pulse between LNSNMP and its Domino server add-in tasks (first the QuerySet Handler or else the Event Interceptor). Traps 13 and 16 get raised only if LNSNMP first determines that the server is working by communicating with the SNMP add-in tasks. Traps are not raised if the server starts up with a problem. Trap 16 will occur if the trap 13 condition persists (server not responding); in other words, you will see a trap 13 before you see a trap 16.

Using the Domino SNMP Agent 53-3

Forwarding of Domino events as SNMP traps Forwarding of Domino events is similar to real-time alerts. SNMP traps are forwarded in real-time as soon as Domino generates them using the Event server task. Statistics monitors are not strictly real-time because Domino generates them only periodically using the Collector server task. One advantage of the Domino SNMP Agent is that it allows these events to be consolidated across Domino domains. The text message of the Domino event contains several items of information that are labeled as follows: Server — Full name of the originating Domino server. Type — Event Type (see below). Severity — Event Severity (see below). TimeStamp — Time stamp is converted to UNIX Epoch format. Note that this is the server’s time stamp, not the console’s. Text — The Event Message (in the local language of the server). Seq — Assigned by LNSNMP. Note All of these fields come directly from the Domino server except for the Seq field. Type codes are numeric and correspond to the respective Event Types seen in Domino Event Monitors: 0 Unknown 1 Comm 2 Security 3 Mail 4 Replica 5 Resource 6 Misc 7 Server 8 Statistic 9 Update

53-4 Administering the Domino System, Volume 2

Severity codes are numeric and correspond to the respective Event Severities seen in Domino Event Monitors: 0 Unknown 1 Fatal 2 Failure 3 Warning (high) 4 Warning (low) 5 Normal Domino statistics through the MIB Many Domino statistics are available using SNMP. It’s possible to see which MIB objects are derived directly from Domino statistics by examining comments in the Domino MIB that begin with the string “--<<”. SNMP security SNMP version 1 is not a secure protocol. SNMP’s native security uses only community names and IP addresses. All sites should review deployment of the Domino SNMP Agent with their security staff. However, the control functions provided by the Domino SNMP Agent do not present significant security risks (for example, access to the console or databases is not affected).

Monitoring

Domino SNMP Agent architecture
Domino SNMP Agent services are provided by two types of programs: • LNSNMP — The Lotus Notes SNMP agent. As an independent application, LNSNMP is insulated from most Domino server malfunctions and, by itself, adds negligible overhead to the server. Two Domino server add-ins — the QuerySet Handler and the Event Interceptor. The QuerySet Handler and the Event Interceptor depend on the Domino server; if the server fails for any reason, these programs fail as well. The following components comprise the Domino SNMP Agent architecture: • A platform-specific master SNMP Agent — An independent, non-Lotus, agent usually supplied with the operating system platform that provides SNMP services for the machine. This SNMP Agent transports the SNMP traps and Get/Set responses across the network to the management station.
Using the Domino SNMP Agent 53-5

The Domino SNMP Agent consisting of: • LNSNMP — Which receives trap notifications from the Event Interceptor and then forwards them to the management station using the platform-specific SNMP Agent. LNSNMP also handles requests for Domino-related information from the management station by passing the request to the QuerySet Handler and responding back to the management station. • QuerySet Handler — Which queries server statistics information, sets the value of configurable Domino-based parameters, and returns Domino statistics information to LNSNMP, which then forwards the information to the management station using the platform-specific master SNMP Agent. • Event Interceptor — Which responds to the SNMP Trap notification for Domino Event Handlers by instructing LNSNMP to issue a trap.

The Domino MIB — A standard Management Information Base (MIB) file for Lotus Domino servers that can be compiled and used by a network management program such as NetView® or OpenView.

The architecture looks like this:

For additional information, refer to your operating system’s or network management tool’s documentation (such as NetView or OpenView).
53-6 Administering the Domino System, Volume 2

About the Domino MIB
The Domino Management Information Base (MIB) covers only the Domino server and not any other IBM or third-party server add-ins. The branch (object ID) is named:
iso.org.dod.internet.private.enterprises.lotus.notes

and is numbered 1.3.6.1.4.1.334.72. The main branches in numeric order are as follows: • lnInfo — Information about the server provided by the QuerySet server add-in task. This includes values and sub-branches. The main sub-branch is lnStats, which contains the Domino statistics organized into sub-branches that mirror the Domino statistics branches. For example, the Server.* Domino statistics are in the lnServer sub-branch. Comments with these objects, beginning with the string “--<<”, indicate which Domino statistic an object is derived from. lnControl — Values provided by LNSNMP including those monitoring and controlling the server. lnInterceptor — An internal branch relating to the Event Interceptor add-in task. lnUnix — An internal branch that supports for NetView for AIX. lnMPAInfo — A branch with one value provided by LNSNMP that gives the version of the Domino SNMP Agent.

• • • •

Monitoring

Note Some Domino statistics are in floating-point format. SNMP version 1 does not support floating-point numbers, truncating these statistics to integers.

System requirements
The following are system requirements for the Domino SNMP Agent: Windows requirements: • Windows native TCP/IP. • Windows SNMP Agent service.

AIX requirements: • AIX native TCP/IP. • AIX Master SNMP Agent (snmpd).

Using the Domino SNMP Agent 53-7

Linux requirements: • Linux native TCP/IP. • An extensible Master SNMP Agent that supports the SMUX protocol (RFC 1227), such as UCD-SNMP 4.1 or later (4.2.3 or later is strongly recommended), or NET-SNMP 5.0 or later. UCD-SNMP and NET-SNMP are distributed by http://www.net-snmp.org and must be built to include SMUX support by first running their source configure script with “--with-mib-modules=smux” as an argument.

Solaris requirements: • Solaris® native TCP/IP. • An extensible Master SNMP Agent that supports the SMUX protocol (RFC 1227), such as PEER Networks OptiMaster Release 1.8a (included).

zOS (OS/390) requirements: • OS/390® Version 1 Release 3 TCP/IP for OpenEdition MVS Applications or OS/390 Version 2 Release 4 TCP/IP. • The most current PTFs for the zSeries (S/390) platform, which you can access on www.ibm.com.

Configuring the Domino SNMP Agent
To configure the Domino SNMP Agent, you need to perform a procedure specific to each platform and then complete the configuration by performing another procedure that applies to all platforms. Note Before configuring the Domino SNMP Agent on a partitioned server, see the topic Special considerations for partitioned servers. 1. Perform the platform-specific procedure: • Windows • AIX • Linux • Solaris • OS/390 2. Complete the configuration.

53-8 Administering the Domino System, Volume 2

Special considerations for partitioned servers
If you plan to use SNMP on a partitioned server, you should read this section prior to using SNMP with Domino 6. There are several different ways to use the Domino SNMP Agent on a partitioned server. If you want to use the Domino SNMP Agent on only one of your partitions, then configure it on that partition just as you would on any server. Do not configure it on any other partitions. With this option, you will get full functionality and control for one server partition. It is not necessary to configure the LNSNMP.INI as described below. If you want to use the Domino SNMP Agent for out-of-band control on multiple partitions, configure it on each partition. With this option, you can control servers individually and receive SNMP traps for each partition, but you lose the ability to query certain branches of the lnInfo branch of the MIB, including all Domino server statistics. It’s also not possible to use SNMP to start a server that hasn’t otherwise been started since SNMP was itself started. If you don’t need to use SNMP to start partitions, it is not necessary to configure the LNSNMP.INI as described below. If you want to manage multiple partitions and always be able to start their servers using SNMP, then it’s necessary to configure those partitions into LNSNMP.INI as described below. Configuring LNSNMP.INI also causes the virtual rows in the MIB’s lnServerTable to be allocated in the order specified in LNSNMP.INI instead of in the order that the partitions are started. The MIB’s lnServerTable contains a virtual row for each partition, so having prior knowledge about which row will represent a particular partition could simplify certain management functions. The Windows operating system limits all SNMP traps to using one IP address. On UNIX, each partition needs a separate DNS entry in order to distinguish each trap origin. On the client side, while traps from partitions will be received, not all SNMP consoles can associate traps from partitions to map objects. In particular, due to a limitation of WINSNMP, which is used with OpenView Professional Suite, it cannot assign traps to Domino icons. Configuring the LNSNMP.INI file If you need to always be able to start partitions using SNMP, or if you need to know which virtual row in the MIB’s lnServerTable a partition will occupy, then you should perform the following steps. Note By adding a server to LNSNMP.INI you’re implicitly allowing SNMP to start that server if asked to do so. The server may then disallow
Using the Domino SNMP Agent 53-9

Monitoring

further SNMP initiated starts once its own configuration options become known. This situation becomes possible each time the Domino SNMP Agent is started because the Domino SNMP Agent does not retain server configuration information when it is stopped. 1. Create a file called LNSNMP.INI in the appropriate directory depending on platform: • Windows: Windows System directory • AIX, Linux or Solaris: /opt/lotus • zOS (OS/390): /opt/lotus Note These are the recommended directories. However, LNSNMP.INI can be in any path in the PATH environment variable that you like. 2. Edit the file and include one line for each server partition with the following format:
Server=<Data_Directory>;<Server_Name>;<Domino_Partition_ Number>

Data_Directory: The directory that is the server’s Domino data directory for a given partition Server_Name: The name of your Server Domino_Partition_Number: This value is arbitrary because Domino no longer uses numbers to uniquely identify partitions. However, for historical reasons, a value must still be present. For example, if you have a UNIX server with two partitions and data directories of /home/domino/venus and /home/domino/saturn, your LNSNMP.INI file should look like this:
Server=/home/domino/venus;Venus Server;1 Server=/home/domino/saturn;Saturn Server;2

Note The case of the text to the right of the equals sign is significant in UNIX environments. Troubleshooting If LNSNMP does not start properly, then check that the LNSNMP.INI file is correct. LNSNMP will always attempt to reference the LNSNMP.INI file.

53-10 Administering the Domino System, Volume 2

Configuring the Domino SNMP Agent for Windows
Follow the steps below, once per platform, to configure the Domino SNMP Agent for Windows. Note Before using the Domino SNMP Agent, make sure TCP/IP and SNMP are properly installed and configured on the server. Also, make sure that the Domino executable and the Domino data directories are in your search path. Tip If you need to add the Windows SNMP Service to your system, be prepared to reinstall any Windows service packs immediately after adding the Windows SNMP Service. Tip The Windows SNMP Service is configured by double-clicking the Network icon in the Control Panel, then selecting the Services tab, then selecting SNMP Service, and then clicking the Properties button. You will want to configure appropriate trap destinations and community names for your remote management infrastructure. Note The Domino SNMP Agent is configured as a Windows Service and is set up to run automatically. This means that once the Domino SNMP Agent is configured, it is virtually always running, even when Domino is not. If you later upgrade Domino you should stop the LNSNMP and Windows SNMP Services before beginning the upgrade process. 1. Stop the LNSNMP and SNMP services. Enter these commands:
net stop lnsnmp net stop snmp

Monitoring

2. Configure the Lotus Domino SNMP Agent as a service. Enter this command:
lnsnmp -Sc

3. Start the SNMP and LNSNMP services. Enter these commands:
net start snmp net start lnsnmp

You have completed the Windows-specific portion of the Domino SNMP Agent configuration. You should now follow the instructions found in Completing the Configuration of the Domino SNMP Agent. Removing the LNSNMP service If you ever need to undo the configuration of the Lotus Domino SNMP Agent as a service, enter this command:
lnsnmp -Sd

Using the Domino SNMP Agent 53-11

Configuring the Domino SNMP Agent for AIX
Follow the steps below, once per platform, to configure the Domino SNMP Agent for AIX. Note Before using the Domino SNMP Agent, make sure TCP/IP and SNMP are properly installed and configured on the server. Also, make sure that the Domino executable and the Domino data directories are in your search path. Tip The trap destinations and community names for AIX are configured in the /etc/snmpd.conf file. You will want to configure appropriate trap destinations and community names for your remote management infrastructure. Remember to keep the view identifiers unique for each trap destination. Note The Domino SNMP Agent is set up to run automatically. This means that once the Domino SNMP Agent is configured, it is virtually always running, even when Domino is not. If you later upgrade Domino you should stop the LNSNMP process before beginning the upgrade process. Note All the following commands should be executed as the root user. 1. Stop the LNSNMP process. Enter this command:
lnsnmp.sh stop

2. Stop the SNMPD subsystem. Enter this command:
stopsrc -s snmpd

3. Configure SNMPD to accept LNSNMP as an SMUX peer. Add the following line to /etc/snmpd.peers:
"Lotus Notes Agent" 1.3.6.1.4.1.334.72 "NotesPasswd"

4. Configure SNMPD to accept an SMUX association from LNSNMP. Add the following line to /etc/snmpd.conf:
smux 1.3.6.1.4.1.334.72 NotesPasswd

5. Start the SNMPD subsystem. Enter this command:
startsrc -s snmpd

6. Start the LNSNMP process. Enter this command:
lnsnmp.sh start

7. Create a link to the LNSNMP script. Enter this command, changing the Domino executable path if necessary:
ln -f -s /opt/lotus/notes/latest/ibmpow/lnsnmp.sh /etc/lnsnmp.rc

53-12 Administering the Domino System, Volume 2

8. Arrange for LNSNMP to be restarted after a reboot. Add the following line to the end of /etc/rc.tcpip:
/etc/lnsnmp.rc start

You have completed the AIX-specific portion of the Domino SNMP Agent configuration. You should now follow the instructions found in Completing the Configuration of the Domino SNMP Agent.

Configuring the Domino SNMP Agent for Linux
Follow the steps below, once per platform, to configure the Domino SNMP Agent for Linux. Note Before using the Domino SNMP Agent, make sure TCP/IP and SNMP are properly installed and configured on the server. If you are using UCD-SNMP or NET-SNMP its source should have been configured and built with “--with-mib-modules=smux” set. If you are not using UCD-SNMP or NET-SNMP verify your Master SNMP Agent supports the SMUX protocol, per RFC 1227. Also, make sure that the Domino executable and the Domino data directories are in your search path. Tip If you are using UCD-SNMP or NET-SNMP the trap destinations and community names are configured in the /usr/share/snmp/snmpd.conf file. Otherwise, refer to the documentation for the master agent technology you are using. You will want to configure appropriate trap destinations and community names for your remote management infrastructure. Note The Domino SNMP Agent is set up to run automatically. This means that once the Domino SNMP Agent is configured, it is virtually always running, even when Domino is not. If you later upgrade Domino you should stop the LNSNMP process before beginning the upgrade process. Note All the following commands should be executed as the root user. 1. Stop the LNSNMP process. Enter this command:
lnsnmp.sh stop

Monitoring

2. Stop the Master SNMP Agent. If you’re using UCD-SNMP or NET-SNMP enter this command:
/etc/rc.d/init.d/snmpd stop

If you’re not using UCD-SNMP or NET-SNMP refer to your Master SNMP Agent’s documentation.

Using the Domino SNMP Agent 53-13

3. Configure the Master SNMP Agent to accept LNSNMP as an SMUX peer. If you’re using UCD-SNMP or NET-SNMP add the following line to /usr/share/snmp/snmpd.conf:
smuxpeer 1.3.6.1.4.1.334.72 NotesPasswd

If you’re not using UCD-SNMP or NET-SNMP refer to your Master SNMP Agent’s documentation. 4. Start the Master SNMP Agent. If you’re using UCD-SNMP or NET-SNMP enter this command:
/etc/rc.d/init.d/snmpd start

If you’re not using UCD-SNMP or NET-SNMP refer to your Master SNMP Agent’s documentation. 5. Start the LNSNMP process. Enter this command:
lnsnmp.sh start

6. Arrange for LNSNMP to be restarted after a reboot. Enter these commands, changing the Domino executable path and default run levels if necessary:
ln -f -s /opt/lotus/notes/latest/linux/lnsnmp.sh /etc/rc.d/init.d/lnsnmp chkconfig --add lnsnmp chkconfig lnsnmp on

You have completed the Linux-specific portion of the Domino SNMP Agent configuration. You should now follow the instructions found in Completing the Configuration of the Domino SNMP Agent.

Configuring the Domino SNMP Agent for Solaris
Follow the steps below, once per platform, to configure the Domino SNMP Agent for Solaris. Note Before using the Domino SNMP Agent, make sure TCP/IP is properly installed and configured on the server. The steps below will install a suitable Master SNMP Agent, but if you already use a Master SNMP Agent that supports the SMUX protocol, per RFC 1227, you may use that instead. Also, make sure that the Domino executable and the Domino data directories are in your search path. Tip If you will be installing the PEER Master agent, then the trap destinations and community names are configured in the /etc/peer.snmpd.conf file. Otherwise, refer to the documentation for the master agent technology you are using. You will want to configure appropriate trap destinations and community names for your remote management infrastructure.
53-14 Administering the Domino System, Volume 2

Note The Domino SNMP Agent is set up to run automatically. This means that once the Domino SNMP Agent is configured, it is virtually always running, even when Domino is not. If you later upgrade Domino you should stop the LNSNMP process, and the PEER Agent(s) if applicable, before beginning the upgrade process. Note All the following commands should be executed as the root user. 1. Stop the LNSNMP process. Enter this command:
lnsnmp.sh stop

2. Stop the Master SNMP Agent. If you’re using the PEER Agent(s) enter this command:
peerinit.sh stop

If you’re not using the PEER Agent(s) refer to your Master SNMP Agent’s documentation. 3. Install or configure the Master SNMP Agent. If you’re going to be using the PEER Master Agent, it’s already configured for LNSNMP; enter the following commands to install it, changing the Domino executable path if necessary:
ln -f -s /opt/lotus/notes/latest/sunspa/peer.snmpd /etc cp /opt/lotus/notes/latest/sunspa/peer.snmpd.conf /etc

Monitoring

If you’re using another Master SNMP Agent refer to its documentation for how to configure LNSNMP as an SMUX Peer. The three parameters associated with SMUX authentication for LNSNMP are:
Description: Lotus Notes Agent Identity: 1.3.6.1.4.1.334.72 Password: NotesPasswd

4. Start the Master SNMP Agent. If you’re using the PEER Agent(s) enter this command:
peerinit.sh start

If you’re not using the PEER Agent(s) refer to your Master SNMP Agent’s documentation. 5. Start the LNSNMP process. Enter this command:
lnsnmp.sh start

6. Create a link to the LNSNMP script. Enter this command, changing the Domino executable path if necessary:
ln -f -s /opt/lotus/notes/latest/sunspa/lnsnmp.sh /etc/init.d/lnsnmp Using the Domino SNMP Agent 53-15

7. Arrange for LNSNMP to be restarted after a reboot. Enter these commands:
ln -f -s /etc/init.d/lnsnmp /etc/rc2.d/S77lnsnmp ln -f -s /etc/init.d/lnsnmp /etc/rc1.d/K77lnsnmp

8. Create a link to the PEER script, if you’re using the PEER Agent(s). Enter this command, changing the Domino executable path if necessary:
ln -f -s /opt/lotus/notes/latest/sunspa/peerinit.sh /etc/init.d/peerinit

9. Arrange for the PEER Agent(s) to be restarted after a reboot, if you’re using them. Enter these commands:
ln -f -s /etc/init.d/peerinit /etc/rc2.d/S76peer.snmpd ln -f -s /etc/init.d/peerinit /etc/rc1.d/K76peer.snmpd

If you’re not using the PEER Agent(s) refer to your Master SNMP Agent’s documentation. You have completed the Solaris-specific portion of the Domino SNMP Agent configuration. You should now follow the instructions found in Completing the Configuration of the Domino SNMP Agent. Configuring the PEER Encapsulator Agent with other master agents If you installed the PEER Master Agent above, but were using another Master SNMP Agent and need to continue using it, you should read the remainder of this section. Most Network Management Stations (NMS) view managed objects on a host through a single SNMP Agent. The NMS will usually direct its SNMP requests to an agent listening on port 161. Because only a single SNMP Agent can be listening at port 161, this limits the NMS to managing only the variables accessible to the one agent listening at that port. If you install the PEER Master agent, it will listen on port 161, so that all queries directed to that host will go to the PEER Master agent. If you already have non-PEER master agents installed on that host, they too will want to listen on port 161, so you need to reconfigure these non-PEER agents to listen on other ports. Then, configure the PEER Encapsulator agent to emulate an NMS and pass on the appropriate SNMP requests from the PEER Master agent to the encapsulated agents at their respective ports. The PEER Encapsulator agent works by hiding the non-PEER agents, so they are visible to the NMS only through the PEER Master agent. Configure the PEER Encapsulator agent to recognize non-PEER agents, respective sub-trees, SNMP ports, and traps. Then when a non-PEER
53-16 Administering the Domino System, Volume 2

agent sends a trap, the PEER Encapsulator agent listening for the trap forwards it up to the PEER Master agent or discards it, as configured. When the PEER Master agent receives an NMS SNMP request about an encapsulated agent’s managed sub-tree, it passes it on to the Encapsulator agent which, in turn, forwards the request to that encapsulated agent at its listening port. To install the PEER Encapsulator Agent enter these commands:
ln -f -s /opt/lotus/notes/latest/sunspa/peer.encaps /etc cp /opt/lotus/notes/latest/sunspa/peer.encaps.conf /etc

To configure the PEER Encapsulator Agent edit the /etc/peer.encaps.conf file, using the comments as a guide. Refer to your other Master SNMP Agent’s documentation for information about configuring it. To start the PEER Encapsulator Agent enter this command:
peerinit.sh start

Monitoring

This is the same command script used to start the PEER Master Agent and is responsible for both Agents if they’re both installed. Therefore, if you already configured the PEER Master Agent to restart automatically after a reboot, the PEER Encapsulator Agent will also restart automatically.

Configuring the Domino SNMP Agent for zOS (OS/390)
Follow the steps below, once per platform, to configure the Domino SNMP Agent for zOS (OS/390). Note Before using the Domino SNMP Agent, make sure TCP/IP and SNMP are properly installed and configured on the server. Also, make sure that the Domino executable and the Domino data directories are in your search path. Tip Trap destinations are defined in the SNMPTRAP.DEST dataset. You will want to configure appropriate trap destinations and community names for your remote management infrastructure. 1. Start the LNSNMP process. Enter this command:
lnsnmp

Note Automatic start of the Domino SNMP Agent is not supported on zOS (OS/390). You have completed the OS/390-specific portion of the Domino SNMP Agent configuration. You should now follow the instructions found in Completing the Configuration of the Domino SNMP Agent.
Using the Domino SNMP Agent 53-17

Completing the Configuration of the Domino SNMP Agent
Once you’ve performed the platform-specific configuration steps, follow these steps, which apply to all platforms, to complete the configuration of the Domino SNMP Agent. Repeat these steps as necessary for each Domino partition. Starting the Domino server add-in tasks 1. To support SNMP queries, start the QuerySet add-in task. Enter this command on the Domino Server console:
load quryset

2. To support SNMP traps for Domino events, start the Event Interceptor add-in task. Enter this command on the Domino Server console:
load intrcpt

3. To support Domino statistic threshold traps, start the Statistic Collector add-in task. Enter this command on the Domino Server console:
load collect

4. Arrange for the add-in tasks to be restarted automatically when Domino is next restarted. Add quryset and/or intrcpt and collect to the ServerTasks variable in Domino’s NOTES.INI file. Configuring traps for Domino events Once the Domino SNMP Agent is configured, your SNMP management console is able to receive traps for basic SNMP events for that server (for example, server down). Additional configuration is required to receive traps for Domino events. You must create appropriate Event Handlers in the Domino Monitoring Configuration database. The Event Handler’s Notification Method must be set to SNMP Trap, and the Notification Server must be set to an asterisk. For more information about Event Handlers, see the chapter “Monitoring the Domino Server.” Configuring statistic threshold traps You can receive SNMP traps for Domino statistics that exceed a specified value when you have configured appropriate Statistic Event Generators and appropriate Event Handlers in the Domino Monitoring Configuration database. Domino must also be running the Statistic Collector and Event Interceptor add-in tasks. The Notification Method of the Event Handler must be set to SNMP Trap, and the Notification Server must be set to an asterisk. For more information about creating Statistic Event Generators and Event Handlers, see the chapter “Monitoring the Domino Server.”
53-18 Administering the Domino System, Volume 2

Enabling the SNMP Agent to start or stop a Domino server You can start or stop Domino servers from a remote management console using the Domino SNMP Agent. To do so, you must enable the Domino SNMP Agent to start or stop a specific server. By default, the Domino SNMP Agent does not allow the remote server to start or stop. You do not need to modify a server’s Configuration Settings unless you want to enable the Domino SNMP Agent to start or stop that server. Note If the server ID is password protected, then the Domino SNMP Agent cannot be used to remotely restart a Domino server because SNMP cannot pass a password parameter to the server. Note It may not be possible for SNMP to start a server until that server has first identified itself to the Domino SNMP Agent. This situation can be overcome by putting information about the server into the lnsnmp.ini file. For additional information see Special Considerations for a Partitioned Server. The Allow Server Start and Allow Server Stop configuration options can be found in the SNMP tab of a server Configuration Settings document. For more information about server Configuration Settings documents, see the chapter “Setting Up Mail Routing.” Enabling the SNMP Agent to reboot the system You can reboot the system from a remote management console using the Domino SNMP Agent. To do so, you must enable the Domino SNMP Agent to reboot the system. By default, the Domino SNMP Agent does not allow remote system reboot. You do not need to modify a server’s Configuration Settings unless you want to enable the Domino SNMP Agent to reboot the system. Note Rebooting is not supported on the zSeries (S/390) platform. Note In the case of a partitioned server, all running partitions must agree that it’s permissible to reboot the system. If one running partition is configured to not allow a system reboot then the reboot will not be performed. The Allow System Reboot configuration option can be found in the SNMP tab of a server Configuration Settings document. For more information about server Configuration Settings documents, see the chapter “Setting Up Mail Routing.” To initiate a system reboot the remote management console must set the lnRemoteReboot MIB object.

Monitoring

Using the Domino SNMP Agent 53-19

Manually starting and stopping the Domino SNMP Agent
Normally, after you’ve completed the configuration of the Domino SNMP Agent, it starts automatically when you restart the system. If you need to, you can stop the agent, then restart it manually. Windows To stop the Lotus Domino SNMP Agent service, enter this command:
net stop lnsnmp

To start the Lotus Domino SNMP Agent service, enter this command:
net start lnsnmp

AIX To stop the lnsnmp process, enter this command as root:
/etc/lnsnmp.rc stop

To start the lnsnmp process, enter this command as root:
/etc/lnsnmp.rc start

Linux To stop the lnsnmp process, enter this command as root:
/etc/rc.d/init.d/lnsnmp stop

To start the lnsnmp process, enter this command as root:
/etc/rc.d/init.d/lnsnmp start

Solaris To stop the lnsnmp process, enter this command as root:
/etc/init.d/lnsnmp stop

To start the lnsnmp process, enter this command as root:
/etc/init.d/lnsnmp start

To stop the PEER Agent process(es), enter this command as root:
/etc/init.d/peerinit stop

To start the PEER Agent process(es), enter this command as root:
/etc/init.d/peerinit start

53-20 Administering the Domino System, Volume 2

zOS (OS/390) To start the lnsnmp process, type the lnsnmp command from an OpenEdition command line. The command and its parameters are shown below:
lnsnmp [-I ipaddress] [-C community] [-P dpiport]

All parameters are optional. The defaults are as follows: • • • ipaddress: the value returned from GETHOSTBYNAME. community: public dpiport: 161. The value must match the value in the SNMP configuration file (SNMP.PORT).

Using the Domino MIB with your SNMP management station
To access any Domino server’s objects in the Domino MIB, you must load the Domino MIB on your SNMP management station. Refer to your management station documentation for details on adding MIBs. The name of the Domino MIB file is domino.mib. This file can be found in the Domino executable directory of any Domino 6 server. Note Unlike previous releases of the Domino SNMP Agent, the Domino MIB is actually used by the Domino 6 server, specifically the QuerySet add-in task, so a copy of the Domino MIB must remain in the Domino executable directory. If you are running multiple versions of the Domino SNMP Agent in your network, for instance, because of migration, your management stations should use the MIB corresponding to the latest installed version of the Domino SNMP Agent.

Monitoring

Configuring traps for HP OpenView
In order to translate Domino SNMP traps into readable messages in the alarm log of HP OpenView, you must use the Domino SNMP Trap Definition File. To configure the Trap Definition File, follow these steps: 1. Copy the Trap Definition File, DOMINO.TDF, to your management workstation. This file can be found in the Domino executable directory of any Domino 6 server. 2. Choose Monitor - Customize Traps. The Customize Trap Alarms dialog appears.

Using the Domino SNMP Agent 53-21

3. Click Load Traps. The Load Traps Definition File dialog appears. 4. Select the Trap Definition File, domino.tdf, that you copied in step 1. 5. Click OK. The Load Device Traps dialog box appears. 6. Select 1.3.6.1.4.1.334.72 in the Device Class field. 7. Click OK. The Customize Trap Alarms dialog reappears. 8. Click OK.

Configuring traps for Domino events
The default states for Domino event traps can be configured in OpenView for Windows with the DOMINO.TDF file. The entries are: 0=1,FirstEntry,2,LOG,MAP,BELL,NONE,NONE,NONE,X0,$5 1=2,0,0,LOG,MAP,BELL,NONE,NONE,NONE,X1,$5 2=3,1,7,LOG,MAP,NOBELL,NONE,NONE,NONE,X2,$5 3=4,2,8,LOG,MAP,NOBELL,NONE,NONE,NONE,X3,$5 4=5,3,1,LOG,MAP,NOBELL,NONE,NONE,NONE,X4,$5 5=11,4,3,LOG,MAP,NOBELL,NONE,NONE,NONE,X5,$5 The third field after the equals sign controls the OpenView severity (see section “Trap Definition Entry” in the OpenView Programmer’s Guide): 4 - Unknown 11 - Unmanaged 2 - Informational 9 - Disabled 3 - Normal 10 - Marginal 1 - Warning 8 - Minor 7 - Major 0 - Critical You could also customize the BELL | NOBELL option.
53-22 Administering the Domino System, Volume 2

Configuring traps for NetView for AIX
Adding traps If you are using NetView for AIX as your management platform and using the Domino SNMP Agent to forward Domino events, you can make these events more readable by performing the following configuration: 1. Copy the trap configuration script, addtraps.sh, to your management workstation. This file can be found in the Domino executable directory of any Domino 6 server. 2. Stop the NetView demons. Enter this command:
ovstop

3. Start the NetView demon trapd. Enter this command:
ovstart trapd

Having traps running causes traps to be updated as the script runs. See the NetView trapd man pages for more details. 4. As root, run the trap configuration script, addtraps.sh, that you copied in step 1. Enter this command:
sh addtraps.sh

Monitoring

You receive a message for each trap added. 5. Restart NetView. Enter this command:
ovstart

Removing traps To remove these traps, log in as root, and run:
removetrap -n "Notes"

Upon completion, you receive the message “Enterprise has been removed.”

Using the Domino SNMP Agent 53-23

Troubleshooting the Domino SNMP Agent
Check Server Tasks If an Agent function is not working, first check that the QuerySet Handler and Event Interceptor server add-in tasks are running by using the Show Tasks command on the Domino console. You can do this remotely if you are authorized. If neither task is running, then the SNMP Agent will report that the server is down. Check MIB Values using the SNMP Management Station Query the MIB remotely to determine which components are up and running. There are three components in the SNMP architecture for MIB variables: • • • The platform-specific Master SNMP Agent The Domino SNMP Agent The QuerySet Handler

Each can respond to MIB requests. You can test them together or sequentially to determine which pieces are responding. You should use the community name configured into your Master SNMP Agent. Test the: • Base system MIB variable, for example, iso.org.dod.internet.mgmt.mib-2.system.sysDescr (.1.3.6.1.2.1.1.1.0), to determine if the platform’s SNMP Agent is working and to find out which version of the platform-specific Master SNMP Agent is running. If this fails, you can (ICMP) ping the server to determine if TCP/IP is responding. If TCP/IP is running, check the community name used by the server’s Master SNMP Agent. If you cannot verify the community name, try the “public” community name. Refer to your SNMP management software documentation for specific instructions. • MIB variable to determine if the Domino SNMP Agent is working, for example, iso.org.dod.internet.private.enterprises.lotus.notes.mp aInfo.lnMainProxyAgentVersion (.1.3.6.1.4.1.334.72.100.1.0), which indicates the version of the Domino SNMP Agent. QuerySet sends a “heartbeat” to the Domino SNMP Agent every few seconds. If the Domino SNMP Agent is not running, you will receive the following message for each failed heartbeat at the Domino server console:
Lotus Domino SNMP Agent is not available. 53-24 Administering the Domino System, Volume 2

The message stops if you start the agent or tell the QuerySet Handler to quit running. • MIB variable to determine if the QuerySet Handler is working, for example, iso.org.dod.internet.private.enterprises.lotus.notes.lnInfo.lnQSBuild Number (.1.3.6.1.4.1.334.72.1.5.0), which indicates the version of the QuerySet Handler.

If the other variables are successful, but the QuerySet Handler is not responding, verify that the task is running using the Show Tasks command on the Domino console. You can perform this test remotely if you are authorized, or you can open a database, such as the Domino Directory, with the Notes client to verify the server is running. Caution Every 30 seconds, the Domino SNMP Agent tests whether the QuerySet Handler is responding. If this test fails you will receive a Warning trap “Domino Server pulse has failed.” This is usually a temporary problem because the server is overloaded. If the condition lasts 5 cycles, however, you will get a Critical trap “Domino Server is not responding.” This means that the server may have crashed or hung. In either case, while it is occurring you will not be able to query the Domino MIB. When the pulse returns, you will receive a canceling trap message that the server pulse is restored.

Monitoring

Using the Domino SNMP Agent 53-25

Chapter 54 Using IBM Tivoli Analyzer for Lotus Domino
This chapter describes the IBM Tivoli® Analyzer for Lotus Domino and explains how you use it to monitor system health, analyze resource distribution, and balance resources. The IBM Tivoli Analyzer for Lotus Domino includes the Server Health Monitor and Activity Trends.

IBM Tivoli Analyzer for Lotus Domino
The IBM Tivoli Analyzer for Lotus Domino includes two integrated system-management tools: the Server Health Monitor, which offers real-time assessment and recommendations for server performance, and Activity Trends, which provides data collection, data exploration, and resource balancing. Using these tools, you can manage servers and databases, ensure better server performance, and plan for current and future needs. The IBM Tivoli Analyzer for Lotus Domino is a separate product offering from Tivoli Systems. The Server Health Monitor determines server health by calculating health statistics and comparing them against preset thresholds. The Server Health Monitor reports the information, pinpoints problematic server components, and provides short-term and long-term recommendations for restoring server health. Activity Trends collects and stores activity statistics as current observations and historical trends. The activity statistics relate to the server, databases, users, and connections of users to databases. You can explore the collected data to see how database workload is distributed across servers. Using the data, Activity Trends recommends a resource-balancing plan. Then, working with the Domino Change Manager, which is a part of the Domino server, Activity Trends provides a workflow that facilitates implementing the recommended changes.

Monitoring

54-1

Server Health Monitor
In Domino, performing traditional performance troubleshooting involves: • • Using event generators and notifications and Domino server monitoring to perform real-time data-analysis Using information from the server log (LOG.NSF), the Monitoring Results database (STATREP.NSF), and the Administration Requests database (ADMIN4.NSF) to perform historical data-analysis Using Domino Directory documents and NOTES.INI settings to customize the server configuration

The Server Health Monitor extends the usefulness of traditional performance troubleshooting by automatically calculating health statistics, comparing those statistics to predefined thresholds, and reporting on overall server health. If the server health rating is Warning or Critical, a health report, which is stored in the Health Monitoring database (DOMMON.NSF), suggests short-term and long-term recommendations for tuning the server and returning its performance status to Healthy. The Server Health Monitor is incorporated into the Domino server monitor, which is part of the Domino Administration client. All health statistics generated by the Server Health Monitor are local to the Domino Administration client. For each server being monitored, the Server Health Monitor reports a health rating for the server and for all enabled individual server components — namely, CPU, disk, memory, and network utilization; NRPC name lookup; mail delivery latency; and server, HTTP, LDAP, and IMAP response. The health rating of each server and server component is based on a collection of indices. Health ratings, such as healthy, warning, or critical, are assigned, based on these index values. Each index has a calculated value between 0 and 100. These values are based on server health monitoring assessment algorithms and rules. Each index has two related thresholds: a warning threshold and a critical threshold. When the index value is less than both thresholds, the server or server component is rated Healthy. When the index value is greater than the warning threshold, the server or server component is rated Warning. When the index value is higher than the critical threshold, the server performance is judged to be Critical and requires immediate attention.

54-2 Administering the Domino System, Volume 2

The Server Health Monitor includes threshold values for each index on these platforms: AIX, IBM eServer iSeries (OS400), IBM eServer zSeries (Z/OS), Linux/Intel, Solaris/Sparc, Windows NT and Windows 2000. You can modify the thresholds to customize server assessment for each platform. You reduce or increase the thresholds to make the algorithms more or less sensitive. Health Monitoring reports on each server area for which data can be retrieved. If no data is available, nothing is reported for that component. You can customize this behavior by specifying which servers you want to monitor. You can exclude any component from the health report, which is useful for filtering out known situations about which you don’t want to be constantly reminded. If you use the Server Health Monitor, the Current Reports view of the Health Monitoring database (DOMMON.NSF) displays a health rating for each monitored server and server component.

Monitoring

Table of Server Health Monitor statistics
The Server Health Monitor reports a statistic for the overall server and for individual components. Each statistic corresponds to a rating. Occasionally, the Server Health Monitor assigns the rating of Unknown. This happens when the Domino Administration client workstation performs at 100 percent of its CPU capacity for an extended period of time. If this happens you may need to make some adjustments to improve the performance of the Server Health Monitor. Server Health reports are stored in the Health Monitoring database (DOMMON.NSF). For information on how to improve the performance of the Server Health Monitor, see the topic “Improving the performance of the Server Health Monitor,” later in this chapter.

Using IBM Tivoli Analyzer for Lotus Domino 54-3

Overall server health statistics
Statistic 0 = Health.Overall.Value Rating Explanation Never Seen The server has never been seen running during the current server monitor session. Healthy The server is performing within acceptable levels of tolerance. One or more server components are approaching unacceptable levels of poor performance. One or more server components are failing to perform acceptably. One or more server tasks issued a fatal error message. One or more tasks are not responding. The server is not responding.

0 < Health.Overall.Value and Health.Overall.Value < Health.Overall.Threshold.Warning

Health.Overall.Threshold.Warning < = Warning Health.Overall.Value and Health.Overall.Value < Health.Overall.Threshold.Critical Health.Overall.Threshold.Critical <= Health.Overall.Value and Health.Overall.Value <= 97 98 = Health.Overall.Value Critical

Critical

99 = Health.Overall.Value 100 = Health.Overall.Value

Critical Server Down

54-4 Administering the Domino System, Volume 2

Component health statistics
Overall health ratings are based, in part, on component health statistics values.
Statistic 0 = Health.*.Value 0< Health.*.Value and Health.*.Value < Health.*.Threshold.Warning Rating Never Seen Healthy Explanation The component is not being monitored. The component is performing within acceptable levels of tolerance. The component is approaching unacceptable levels of poor performance.

Health.*.Threshold.Warning <= Warning Health.*.Value and Health.*.Value< Health.*.Threshold.Critical Health.*.Threshold.Critical <= Health.*.Value and Health.*.Value <= 97 98 = Health.*.Value Critical

Monitoring

The component is failing to perform acceptably. The task associated with the component issued a fatal error message.

Fatal

99 = Health.*.Value

Not The task associated with the Responding component is not responding.

Table of Server Health Monitor ratings
The Current Reports view of the Health Monitoring database (DOMMON.NSF) displays the assigned rating for each enabled server and server component. When a server rating is Warning or Critical, the Overall Health Report provides recommendations for correcting the problems.

Server ratings
Rating Never Seen Healthy Description The server has never been seen running during the current server monitor session. The server is performing within acceptable tolerances. continued

Using IBM Tivoli Analyzer for Lotus Domino 54-5

Rating Warning Critical

Description One or more server components are approaching unacceptable levels of poor performance. The server is experiencing one or more of these critical problems: • One or more server components are failing to perform acceptably • One or more tasks on the server have issued a fatal error • One or more tasks on the server are not responding

Server Down

The server is not responding; therefore, it isn’t responding to requests for statistics.

Component ratings
Rating Healthy Warning Critical Fatal Description The server component appears to be running correctly. The server component is approaching unacceptable levels of poor performance. The server component is failing to perform acceptably. The task related to this component has issued a fatal error.

Not Responding The task related to this component is not responding.

Server Health Monitor configuration
The Server Health Monitor is part of the IBM Tivoli Analyzer for Lotus Domino. For information on the license required to use the Server Health Monitor, see the topic “Installing the IBM Tivoli Analyzer for Lotus Domino,” later in this chapter. To set up the Server Health Monitor, complete these procedures: 1. Install the IBM Tivoli Analyzer for Lotus Domino. 2. Start the Domino server monitor.

Installing the IBM Tivoli Analyzer for Lotus Domino
To install the IBM Tivoli Analyzer for Lotus Domino: 1. Make sure you have installed the Domino Administrator. 2. Run the install program (SETUP.EXE) from the Tivoli Analyzer directory.
54-6 Administering the Domino System, Volume 2

For more information about installing the Domino Administrator, see the chapter “Setting Up and Managing Notes Users.” The IBM Tivoli Analyzer for Lotus Domino is a separate product offering from Tivoli Systems. To learn more about how this integrated system management tool can help manage your servers and databases, ensure better performance, and help you plan for current and future needs, visit http://www.ibm.com/software/tivoli/r/analyzerfordomino or contact your Tivoli sales representative or Business Partner.

Setting up the Server Health Monitor
To create Server Health Monitor reports and historical charts, you must enable both the Server Health Monitor and statistic reporting. 1. From the Domino Administrator, choose File - Preferences Administration Preferences. 2. Click Monitoring, and then check “Generate server health statistics and reports.” 3. For “Poll servers every n minutes,” enter a value from 1 to 60 minutes. Tip The higher the number of servers to monitor, the larger the polling interval to enter. For timely monitoring, enter a value between 1 and 10. 4. (Optional) To start the server monitor automatically, check “Automatically monitor servers at startup.” 5. Click Statistics, and then check “Generate statistic reports while monitoring or charting statistics.” 6. For “Generate reports every n minutes,” enter a value greater than or equal to the server polling interval specified in Step 3. 7. Wait a few minutes longer than the polling interval, and then open the Health Monitoring Database (DOMMON.NSF) to see the Health report. Before you start the Server Health Monitor The Server Health Monitor does not require any specific Domino server configuration, but you can generate more accurate reports by following these guidelines: • Enable platform statistics on the server. Platform statistics are enabled, by default, in Domino 6. Follow the specific instructions for your platform. You may need to perform additional steps to ensure that platform statistics are working and are fully enabled on your platform.
Using IBM Tivoli Analyzer for Lotus Domino 54-7

Monitoring

• •

Make sure you have at least View-only Administrator rights for every server you want to monitor. Use a TCP server event generator as a self probe to create Quality of Service (QOS) statistics.

For information on setting up platform statistics and using TCP Server Event Generators, see the chapter “Monitoring the Domino Server.”

Starting the Server Health Monitor
To start the Server Health Monitor, you start the Domino server monitor, which automatically monitors the most recently viewed server profile or profiles that you configured to run in the background. The Domino server monitor does not begin on startup by default. To start and stop the Domino server monitor manually 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Click the Green arrow in the upper-right of the task screen. When the server monitor is running, this arrow toggles to a red Stop button. 3. To stop the server monitor, click Stop. To start the Domino server monitor automatically 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Click File - Preferences - Administration Preferences. 3. Click Monitoring. 4. Enable “Automatically monitor servers at startup.” For more information on the Domino server monitor and server profiles, see the chapter, “Monitoring the Domino Server.”

Using the Server Health Monitor
Using the Server Health Monitor, you can perform these tasks to monitor the health of servers and server components: • • • • • • • Specify which server components to monitor Enable statistic alarms Modify threshold values for server components Create health reports Excluding a server from monitoring by the Server Health Monitor Change the purge interval for historical health reports Improve the performance of the Server Health Monitor

54-8 Administering the Domino System, Volume 2

Selecting server components to include in health reports
Each server you monitor has a Health Monitoring Configuration document in the Health Monitoring database (DOMMON.NSF). This document specifies the server components you want to include in health reports. Based on statistics and task information obtained from the server, the Server Health Monitor automatically determines which components to include in health reports. For example, if the HTTP task is not running on a particular server, then the Server Health Monitor automatically excludes the HTTP component from any analysis. Occasionally, you may want to exclude a component manually. For example, if you know that a particular server has a disk I/O bottleneck, exclude the Disk Utilization component so that it doesn’t adversely affect the server’s overall health rating. Server components that are selecting components manually display a pencil icon next to the server name. If there is no pencil icon, the components are being selected automatically. To select server components to include 1. From the Domino Administrator, click the Server - Monitoring tab. 2. From the menu, choose Monitoring - Display Health Reports, and then open the Configuration view. 3. Choose Server Components. 4. Choose the server you want to modify, and click Edit Server Document. 5. Under “How should component indices be enabled?” choose one: • Automatic — to allow the Server Health Monitor to select the components to include in health reports, based on which server tasks are running. • Custom — to manually select the components to include in health reports. Statistics for selected components are included in health reports, whether the server task is running or not. To reset server component select to automatic. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. From the menu, choose Monitoring - Display Health Reports, and then open the Configuration view. 3. Choose Server Components. 4. Choose the server you want to modify, and click Edit Server Document. 5. Click “Restore Automatic Selections” and click OK.
Using IBM Tivoli Analyzer for Lotus Domino 54-9

Monitoring

Setting up statistic alarms for the Server Health Monitor
Just as you create an event generator for a Domino system statistic, you create an event generator for a health statistic. Then when the statistic does not meet the defined threshold, an event is generated. For an event to be created, however, you must enable statistic alarms. Then, the first time a statistic alarm is reported, an event is generated and reported to the Monitoring Results database (STATREP.NSF). In addition to an alarm, you can create an event handler to notify you of the event. Event generators and event handlers are stored in the Monitoring Configuration database (EVENTS4.NSF). For more information on creating event generators and event handlers, see the chapter “Monitoring the Domino Server.” To enable statistic alarms 1. From the Domino Administrator, choose File - Preferences Administration Preferences. 2. Click Statistics, and then check “Check statistic alarms while monitoring or charting statistics.” 3. For “Check alarms every <n> minutes (greater than monitoring poll interval)” enter a value that is greater than the server polling value. The default is 15. Tip If you are not sure what the polling value is, click Monitoring and locate the value for “Poll servers every <n> minutes (1-60 mins).” For more information on setting Administration Preferences for server monitoring, see the chapter “Setting Up and Using Domino Administration Tools.”

Modifying threshold values for the Server Health Monitor
The Index Thresholds view in the Health Monitoring database (DOMMON.NSF) displays the threshold values for each platform. To modify the sensitivity to a particular component, change the threshold value. For example, if you want to run your networks with higher utilization for servers running on a specific platform, increase the threshold for the Network Utilization component for the platform. Keep these considerations in mind if you decide to modify threshold values. First, have a strategy in mind before you change the them. Your strategy should address your system performance needs and reflect your philosophy toward managing servers. Second, if you change threshold values remember that you have done so. Changing any system configuration parameters or adjusting user workload behavior might also have a future impact on these settings. And finally, remember that
54-10 Administering the Domino System, Volume 2

changing threshold values inappropriately may result in health values that do not accurately reflect server capacity and availability. If you get results that seem inaccurate, restore the default threshold values. To modify a threshold value 1. From the Domino Administrator, click the Server - Monitoring tab. 2. From the menu, choose Monitoring - Display Health Reports. 3. Under Configuration, choose Index Thresholds. 4. Choose the operating system whose threshold you want to change, and choose “Edit Threshold Document.” 5. Change the value for the Warning Threshold and/or Critical Threshold. 6. Click OK. If you later decide to restore the default threshold values, perform Steps 1 through 5 above and then click Restore Defaults.

Monitoring

Server Health reports
Based on information gathered by the Domino Server Monitor, the Serve Health Monitor issues Health reports. Health reports are stored in the Health Monitoring database (DOMMON.NSF). There are two views of Health reports, current and historical. Current reports are based on information reported by the Domino server monitor. Historical reports are an accumulation of past reports. Each report includes the following information: • Server Health information — Information about the server, including the version of Domino and operating system. Displays the rating and rating value, and lists the first time this rating appeared. Also shows the last time the server was evaluated. Configuration Issues — Identifies any configuration issues that may be preventing the Server Health Monitor from generating the most accurate diagnoses possible. Failing to correct these configuration issues will result in health reports that are less accurate and less detailed. Details Regarding Rating — This information backs up the recommendations. Information can include details about the server’s configuration or performance. Short Term Recommendations — These are things you can do immediately to improve the server’s performance. Long Term Recommendations — These are suggestions for making lasting improvements that will prevent a poor health rating in the future.
Using IBM Tivoli Analyzer for Lotus Domino 54-11

• •

Displaying Server Health reports
If a server is repeatedly rated Warning or Critical, look at historical health reports to get a better picture of server health. To display a current health report 1. From the Domino Administrator, click the Server - Monitoring tab. 2. From the menu, choose Monitoring - Display Health Reports. 3. Select the view Health Reports - Current Reports. 4. Double-click a server to display the Overall Health Report for that server. To display a historical health reports 1. From the Domino Administrator, click the Server - Monitoring tab. 2. From the menu, choose Monitoring - Display Health Reports. 3. Select the view Health Reports - Historical Reports. 4. Find the target server in the list and expand its report documents.

Changing the purge interval for historical health reports
By default, the historical reports are purged from the Health Monitoring database (DOMMON.NSF) after 7 days. To change this default, edit the NOTES.INI file on the Domino Administration client to include this setting: HEALTH_REPORT_PURGE_AFTER_N_DAYS=n

Improving the performance of the Server Health Monitor
If the Domino Administration client workstation performs at 100 percent CPU utilization for a long period of time, the Server Health Monitor discards server statistic data to keep up with the workload. If statistic data is discarded over an extended period of time, the Server Health Monitor assigns the rating Unknown to every server. When that happens, each health report includes the statement “The Domino Administrator workstation CPU is constantly saturated. Too much server statistic data is being retrieved. This condition causes inaccurate server monitoring reports.”

54-12 Administering the Domino System, Volume 2

To reduce the amount of statistic data: • • Increase the server polling interval in Administration Preferences. Reduce the number of servers being actively monitored during a Domino server monitor session. The servers for each monitoring profile you use are added to the total number of servers being monitored. To clear this list to the servers a specific profile only, stop the Domino server monitor, and then restart it. Dedicate one workstation to the Server Health Monitor

Working with Server Health Monitor statistics
Health statistics are recorded in the Monitoring Results database (STATREP.NSF). Health statistics are local to the Domino Administration client; therefore, they do not reside on the servers being monitored. Just as you use a Domino server statistic, you use a health statistic to monitor the system. You can do any of these: • • • • • Use monitoring profiles to monitor server health View server health Define event generators and event handlers for health statistics (Jump to topics) Excluding a server from monitoring by the Server Health Monitor from being monitored or from generating health reports Create statistics profiles and chart health statistics

Monitoring

Monitoring server health in the Domino server monitor
You monitor server health in the Domino server monitor, using monitoring profiles. You must be actively monitoring each server from which you want to collect health statistics. This means that the Domino server monitor must be running for you to collect Server Health statistics. By default, the Domino server monitor includes a set of default server profiles that are created in the Domino Directory. However, you can create custom profiles that monitor the servers, server tasks and health statistics that you choose. By default, when you start the Domino server monitor, it begins monitoring servers in the last profile that was selected when you shut down the Domino server monitor. The servers in each subsequent profile that you monitor, are added to those servers previously monitored. If you monitor several different profiles in a single session, the number of
Using IBM Tivoli Analyzer for Lotus Domino 54-13

servers monitored may be quite lengthy, which may impact the performance of the Server Health Monitor. To clear the list of servers monitored, stop and then start the Domino server monitor. You can also customize which profiles to monitor upon startup, by specifying profiles you want to monitor in the background, no matter which profile was monitored when you shut down the Domino server monitor. You can perform the following tasks when you work with monitoring profiles: • • • Creating monitoring profiles in the Domino server monitor Modify a system profile Specify monitoring profiles to monitor when you start the Domino server monitor

For more information on creating and modifying server profiles, and specifying which profiles to monitor when you start the Domino server monitor, see the chapter “Monitoring the Domino Server.”

Viewing server health with the Server Health Monitor
After the first polling interval passes, the Server Health Monitor posts a report of server health, which you can view in the Domino server monitor for a quick visual representation of your server’s health. When a server rating is Warning or Critical, or when there is a configuration issue, check the Overall Health Report in the Health Monitoring database (DOMMON.NSF). Each server health report provides short-term and long-term recommendations for restoring the server’s rating to healthy. For example, if the Memory Utilization component receives a Warning rating, the short-term solution may be to check the server for unnecessary processes that have been loaded. The long-term recommendation may be to add memory or to check the server’s page-file allocation. Note A red exclamation mark next to a server indicates a configuration issue. Read the server health report for information on configuration issues. To view server health 1. Make sure you enabled the Server Health Monitor in Administration Preferences, started the Domino Server Monitor, and allowed the monitor to run for a few minutes longer that the specified polling interval. 2. From the Domino Administrator, click the Server - Monitoring tab.
54-14 Administering the Domino System, Volume 2

3. In the Health column (Hea), the Server Health Monitor uses these icons to indicate the server’s overall health: • Green thermometer — the server’s overall health rating is Healthy. All server components are within the appropriate range. • Yellow thermometer — the server’s overall health rating is Warning. One or more server components being monitored are approaching unacceptably poor levels of performance. • Red thermometer — the server’s overall health rating is Critical. One or more server components being monitored are failing to perform within acceptable tolerance levels.

Excluding a server from the Server Health Monitor report documents
The Server Health Monitor creates health reports for each server you are actively monitoring and stores them in the Health Monitoring database (DOMMON.NSF). You can exclude a server from a monitoring profile, so that the server is removed from the current monitoring view in the Domino server monitor. However, the Server Health Monitor continues to include that server in the health reports until you remove the server permanently from DOMMON.NSF. You permanently exclude a server from being included in health reports by removing its current report documents and its configuration server component document. After you exclude a server permanently, the Server Health Monitor no longer generates reports. To exclude a server from a monitoring profile Use this procedure when you do not want to see the continued output of the server health rating for the server, but you want to continue listing the health report for the server in the Health Monitoring database. 1. From the Domino Administrator, click the Server - Monitoring tab. 2. Select the server you want to remove and right-click. From the menu, choose “Remove Server.” 3. Click the Stop button. The next time you press the Start button, the server will no longer be monitored. However, it will continue to be listed in the current health report view. To exclude a server from generating Health Reports Use this procedure when you do not want to monitor the server and do not want to continue receiving health reports on it in the Health Monitoring database.

Monitoring

Using IBM Tivoli Analyzer for Lotus Domino 54-15

1. Perform the steps listed above to exclude temporarily the server from the server monitor view. 2. From the Domino Administrator, click the Files tab. 3. Open the Health Monitoring database (DOMMON.NSF), and open the Configuration - Server Components view. 4. Delete the Health Monitoring Server Configuration document for the server being excluded. 5. Open the Health Reports - Current Reports view and delete the current health report and all the response documents for the server. 6. (Optional) Open the Health Reports - Historical Reports view and delete the historical health reports and the associated response documents for the server.

Charting Server Health Monitor statistics
To chart the performance of Server Health statistics, you must be actively monitoring all servers whose performance you want to chart in the Domino server monitor. In addition, if you want to chart health statistics historically, you must enable the generation of statistic reports while monitoring or charting statistics in the statistic Administration Preferences. For more information on enabling statistic reports, see the topic “Setting up the Server Health Monitor,” earlier in this chapter. You can chart real-time and historical performance of Server Health statistics. Real-time health statistics are gathered by the Statistic Collector server task in the Domino Administrator and are stored in memory, for use when charting real-time statistics. Historical health statistics are created from the historical statistics information stored in the local Monitoring Results database (STATREP.NSF). You can also create statistic profiles to monitor groups of servers and associated statistics routinely. There is a limit of 25 statistics in each statistic profile. You can perform the following tasks when charting server health statistics: • • • Create statistics profiles Modify statistic profiles Display statistic charts

For information on creating statistic profiles and charting statistics, see the chapter “Monitoring the Domino Server.”

54-16 Administering the Domino System, Volume 2

Activity Trends
Domino server resource utilization can be separated into two types, system activity and user activity. System activity, which includes the level of processor, disk, memory, and network consumption that Domino generates to keep the server running, is a fixed amount of activity, as long as systems are healthy and performing smoothly. Domino servers typically use a modest percentage of their resources to run. The remaining server capacity is used to support user activity, which varies with the usefulness of the data on the server. Using Activity Logging servers account for their time precisely, recording user activity by person, database, and access protocol. When summarized and averaged, or trended over time, activity logging of trended statistics provides a way to measure and compare workloads across servers. You can use this information to identify the most active users and databases on each server. Using the Domino Change Manager, you can automate the creation and execution of workload redistribution plans to load a new server, decommission an old one, or balance workloads across unevenly burdened servers Activity Trends is part of the IBM Tivoli Analyzer for Lotus Domino, a separate product offering from Tivoli Systems. The Activity Trends Collector is a Domino server add-in task that records and reports statistics about database activity on a server. Information is stored in the Activity Trends database (ACTIVITY.NSF). The IBM Tivoli Analyzer for Lotus Domino uses the collected data to determine the load on the server. Then, using resource-balancing functionality, the Analyzer applies trends analysis and statistics to intelligent algorithms that can provide computer-aided load balancing on a set of servers or simplify the server decommissioning process. Integrated with the IBM Tivoli Analyzer for Lotus Domino, the Domino Change Manager provides workflow capability that creates resource-balancing plans and implements database moves, using the Tivoli Analyzer tools and analysis. The Domino Change Control database (DOMCHANGE.NSF) and Domino Change Manager are part of the Domino server core functionality. Activity Trends includes: • • Server profile definition — For easy access to a named group of servers. Statistics profile creation — For easy access to a named group of statistics.

Monitoring

Using IBM Tivoli Analyzer for Lotus Domino 54-17

• •

Activity trends charting — You can chart a selected group of statistics for a single server or a group of servers. Resource balancing — Analyzes server resource use and creates recommendations for balancing the servers based on specified resource goals. Activity logging — To collect information that will be used for resource-balancing. Activity Trends — To set up times for data collection and retention. Domino Change Manager — To implement a workflow process in which changes made to the system are controlled and approved.

Activity Trends uses these Domino server features: • • •

Setting up Activity Trends
The basic setup for Activity Trends includes these tasks: 1. Make sure the IBM Tivoli Analyzer for Lotus Domino is installed. 2. For each server for which you want to collect activity logging information and analyze activity trends, enable activity logging and activity trends in the Configuration Settings document. 3. To set up resource balancing, do the following: a. Load the Domino Change Manager administration task on one server in the domain. b. Define a set of server profile options that specify the locations, goals, and behavior of resource balancing.

Enabling activity logging and setting up Activity Trends
You enable activity logging and set up Activity Trends in the Configuration Settings document. First, you enable activity logging to gather data for the selected server tasks. The first time you start Activity Trends, the system must run and collect data for 24 hours before you can work with the data. Then you specify how you to collect the Activity Trends and create the Activity Trends database (ACTIVITY.NSF), which is stored, by default, in the Domino data directory. To enable activity logging and set up Activity Trends 1. From the Domino Administrator, click the Configuration tab, expand the Server section, and click Configurations. 2. Select the server, and click Edit Configuration or Add Configuration.
54-18 Administering the Domino System, Volume 2

3. Click the Activity Logging tab, and check “Activity logging is enabled.” 4. Under Server Activity Logging Configuration, complete these fields:
Field Enabled logging types Action Select the server tasks to use to produce activity logging data. For Activity Trends, enable all tasks except Domino.MAIL. At a minimum, you must enable Domino.Notes.Session and Domino.Notes.Database.

Checkpoint interval Enter the number of minutes to wait between the creation of checkpoint records. The default is 15 minutes. Log Checkpoint at Midnight Check Yes to log ongoing session activity at midnight. This is required for Activity Trends. You must enable this field to enable Activity Logging.

Monitoring

Log Checkpoints for Check Yes and then specify the prime shift interval to log checkpoints for the prime shift. Prime Shift You must enable this field to enable Activity Logging. Prime Shift Interval Specify the start and end time of prime shift. Set the interval on the hour.

5. Click the Activity Trends tab, and complete the following fields on the Basics tab:
Field Enable activity trends collector Action Click yes to run the Activity Trends Collector. Activity Trends Collector uses the raw data from activity logging and prepares it for use with Activity Trends. Enter the name and path of the database where Activity Trends data is stored if you want to change this. The default is ACTIVITY.NSF. Enter a time. The default is 3:23 AM. Schedule the Activity Trends Collector to run after the Catalog task runs. By default, the Catalog task runs at 1 AM.

Activity trends collector database path Time of day to run activity trends collector

Days of the week to Select the days for which you want to collect collect observations observations. The default is Monday through Friday.

Using IBM Tivoli Analyzer for Lotus Domino 54-19

6. Under Activity Trends Data Profile Options, keep the “Use defaults” field enabled. If you choose not to use the defaults, complete these fields.
Field Trends cardinal interval Action Enter the number of recent observations you want to use. The default is 10. When computing trended values, recent observations are weighted the most. For example, if you select Monday through Friday in the “Day of the week to collect observations” field and use the default 10 in the “Trends cardinal interval” field, the trended values will include two weeks of observations (five days each week). Note If you know there has been a recent change in user activity, you may choose not to use trended values.

Observation time Specify the time in seconds for one bucket. The default bucket (seconds) is 300. The observation time controls how many buckets you will have for one 24-hour observation period. Maximum observation list time Trends history interval Specify the maximum length of time data is kept in the Trends database before it is overwritten with new data. The default is 366, the number of days in a leap year. Choose one: • • • • Daily Weekly (default) Monthly Trend Interval

7. Click the Retention tab. Keep the “Use defaults” field enabled. Documents are overwritten after the retention period expires. The defaults are: • Server history — 366 days • Server observations —15 days • Database observations — 10 days • User observations — 10 days • Connection observations — 10 days • Inactive database trends — 10 days • Inactive user trends — 28 days • Inactive connection trends — 28 days • Run log — 20 days
54-20 Administering the Domino System, Volume 2

8. Click the Proxy Data tab, and enter the names of the databases containing activity data to search. 9. Click Save and Close. For detailed information on checkpoint records, see the chapter, “Setting Up Activity Logging.”

Understanding how Activity Trends collects data
Activity Logging collects data from the log file (LOG.NSF) and the Catalog task and stores it in the Activity Trends database (ACTIVITY.NSF). The Activity Trends Collector task processes this data and produces the trended data that is used in charting and resource balancing. The “Trends cardinal interval,” “Observation time bucket,” and “Proxy data” settings affect Activity Trends. Trends Cardinal Interval Trend statistics are based on data gathered during an observation period, which is a 24-hour period from midnight to midnight. Each trend statistic is a weighted running average, which is computed by adding data from a new observation to the existing “trend,” or running average, with an exponential weighting. Consequently, the newest observations are weighted most heavily, and older observations are weighted exponentially less and less in the new computed trend. Keep in mind that increasing the cardinal interval increases the number of recent observations that are heavily weighted, and decreasing the cardinal interval decreases the number. Observation Time Bucket Activity Trends stores data in a “time bucket,” or array, that represents a distribution of activity across one observation period. When you set up Activity Trends, you specify the size of each bucket, by specifying the number of seconds that make up one bucket. The specified number must divide evenly into one hour. For example, the default is 300 seconds, or 5 minutes; therefore, there are 288 5-minute buckets in one observation period. Proxy data By default, the server from which you are running Activity Trends will find the local Activity Trends database (ACTIVITY.NSF). However, you may replicate Activity Trends databases that contain data you want to access. You use proxy data to include the names of other Activity Trends databases that contain trends data from other servers.

Monitoring

Using IBM Tivoli Analyzer for Lotus Domino 54-21

Activity Trends server and statistics profiles
Using profiles simplifies the work of managing groups of servers and groups of statistics. In Activity Trends, you can collect servers into a server profile, and you can specify the statistics to be included in a server profile. In a server profile, you collect servers from the same domain into a named group. Then when you perform resource balancing or use charting to review performance, you have easy access to those servers. After you create a server profile, you can select a statistics profile to view the statistics for the selected server profile. When you perform resource balancing, the server profile can include one or more phantom servers. Phantom servers do not physically exist, but you can use them in “what if” scenarios to evaluate how adding servers might alleviate load problems. Phantom servers are not visible when viewing activity trends, in either the Latest or Historical views, because there is no activity trends data for phantom servers. Activity Trends analysis includes default statistics that differ depending on the view you are in. The Users view, for example, has only one default statistic, while the Server view has two. You can create statistics profiles that contain an unlimited number of Domino system statistics. Then you can use any statistic profile with any server profile. For more information on profiles, see: • • Creating an Activity Trends statistics profile Creating an Activity Trends server profile

Creating an Activity Trends server profile
You can create one or more Activity Trends server profiles. To create a server profile 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and do one: • Select a view in the Latest folder or Historical folder • Select Resource Balancing 2. In the “Server profiles” area, click the green plus sign. 3. In the Add Server dialog box, select the domain to use. 4. Under Server, do one or both of these: • Click Existing Server, and select from the list of available servers. • Click Phantom (Resource Balancing only), and enter a name for the phantom server.
54-22 Administering the Domino System, Volume 2

5. Click Add to add each server, and then click Done when you have completed your selections. This group is only temporary. To save this server profile, proceed to the next step. 6. Click the document icon and choose “Save As.” 7. In the “Save Server Profile” dialog box, enter a group name and click OK. To create an additional server profile Use this procedure to clear the current server profile and create a new one. 1. In the “Server profile” area, click the document icon, and choose New. 2. Click the green plus sign, and complete Steps 4 through 7 in the above procedure.

Modifying an Activity Trends server profile

Monitoring

You can add or delete servers to an existing server profile. In Resource Balancing, you can also add phantom servers. A phantom server does not physically exist, but is factored in to the resource-balancing plan to evaluate how adding servers might alleviate current load problems. To add a server to a profile 1. From the Domino Administrator, click the Server - Performance tab, and expand the Activity Trends section. 2. Select an Activity Trends view. 3. Under “Saved server group configurations,” choose a server profile. 4. Click the green plus sign to display the “Add Server” dialog box. 5. Under Server, do one or both of these: • Click Existing Server, and then select from the list of available servers. • Click Phantom (Resource Balancing view only), and then enter a name for the phantom server. 6. Click Add to add each server, and then click Done when you complete the selections. This group is only temporary. To save this server profile, proceed to the next step. 7. Click the document icon, and do one: • Click Save As, and enter a new profile name. • Click Save to update the existing profile.

Using IBM Tivoli Analyzer for Lotus Domino 54-23

To delete a server from a profile 1. From the Domino Administrator, click the Server - Performance tab, and expand the Activity Trends section. 2. Select an Activity Trends view. 3. Under “Server profiles,” choose a profile. 4. Select the name of one or more servers to delete. 5. Click the red minus sign.

Deleting an Activity Trends server profile
You can delete a server profile that was previously saved. 1. From the Domino Administrator, click the Server - Performance tab, and expand the Activity Trends section. 2. Select an Activity Trends view. 3. Select a server profile from the list. 4. Click the document icon, and choose Delete.

Creating an Activity Trends statistics profile
To create a statistics profile 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and select a view in the Latest folder or Historical folder. 2. In the “Statistics profiles” area, click the green plus sign. 3. In the Add Activity Statistic dialog box, expand the statistic categories. The list of activity statistics varies depending on the view. 4. Choose one or more statistics to add, and click OK. Tip To select more than one statistic, locate your cursor in the column to the left of the list and click next to each statistic you want to add. Drag the mouse to select large group of statistics. 5. Click the document icon, and choose “Save As.” 6. In the Save Statistics Profile dialog box, enter a name for the group. To create another statistics profile 1. In the “Statistics Profiles” area, click the document icon, and choose New. 2. Click the green plus sign, then complete Steps 4 through 6 in the above procedure.

54-24 Administering the Domino System, Volume 2

Modifying an Activity Trends statistics profile
You can add or delete statistics from a saved statistics profile. To add a statistic to a saved profile 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and select a view in either the Latest folder or Historical folder. 2. Under “Statistics profiles,” choose a group. 3. Click the green plus sign to display the “Add Activity Statistic” dialog box. 4. For each statistic you want to add, select the statistic, and click OK. When you finish adding statistics, click Done. Tip To select more than one statistic, position the cursor in the column to the left of the list and click next to each statistic to add, or drag the mouse to select a large group of statistics. 5. Click the document icon, and do one: • Click Save As, and enter a new profile name. • Click Save to update the existing profile. To delete a statistic from a saved profile 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and select a view in the Latest folder or Historical folder. 2. Under “Statistics profiles,” choose a profile. 3. Select the statistic you want to remove, and click the red minus sign. 4. Click the document icon, and do one: • Click Save As, and enter a new profile name. • Click Save to update the existing profile.

Monitoring

Viewing Activity Trends charts
You can view the latest available data and historical data charts of Activity Trends statistics. You can also set display options that customize the appearance of the charts. You can select servers and statistics to view, or you can select predefined server and statistic profiles. You can also “drill down” for more information on any user or database statistic in the Latest Folder view. For example, to see which databases a user is accessing, select a user from the Latest Folder - User view and double-click the user’s name; the Connection view displays a chart of that user’s database use.

Using IBM Tivoli Analyzer for Lotus Domino 54-25

For information about setting charting display options, see the topic “Setting charting options for resource balancing” later in this chapter. To view Activity Trends charts 1. From the Domino Administrator, click the Server - Performance tab. 2. Select the Activity Trends view. 3. Select one of these views: • Latest folder - Server — To view the set of data available for selected statistics on each selected server. • Latest folder - Database — To view the databases on each selected server. • Latest folder - User — To view the users statistics for all databases on the selected servers. • Latest folder - Connection — To view information for a selected statistic from either the User or Database charts. • Historical folder — Weekly • Historical folder — Daily

Resource balancing in Activity Trends
Using resource balancing, you can balance selected resources, such as database transaction load and disk space, among a selected group of servers. You decide which databases are available to be relocated as part of the resource balancing. All system databases are automatically “pinned” and cannot be moved. You can pin other databases to prevent them from being moved. In addition to balancing the resources of existing servers, you can create phantom servers to use for future planning. Each phantom server represents a new server that can be loaded with databases. Then you can evaluate the effect of adding a new server before you incur the expense of additional hardware.

Server roles
The role you assign to a server affects the resource-balancing results. • • Source Only — These servers cannot have any databases moved to them. Destination Only — These servers cannot have any databases removed from them. A phantom server is a Destination Only server and cannot be changed. Any — These servers can have databases moved to or from them.

54-26 Administering the Domino System, Volume 2

Setting up resource balancing in Activity Trends
Within an Activity Trends server profile, you define criteria that determines which databases and servers to evaluate and how to balance resources. 1. Specify locations of the databases and servers to search for activity data. 2. (Optional) Set display options for Activity Trends charts. 3. Set the primary and secondary goals for analyzing the database activity that you want to balance. 4. Specify which databases can move during resource balancing. 5. Specify the location of the Change Manager database and set resource-balancing behavior.

Specifying database and server locations for resource balancing

Monitoring

Use the Server Profile Options dialog box to specify which databases and servers will be searched for activity data, and whether to use cached data. Because Activity Trends data changes only on a daily basis, caching data is highly recommended to increase system performance by avoiding a read across a potentially slow network. The first time a server’s data is read, the data is cached and remains available. For example, if you read and then delete a server’s activity data and later add the same server, the in-memory data is used. You can open the Server Profile Options dialog box from the Activity Trends menu or by clicking the Server Profile Options button:

To specify locations 1. From the Domino Administrator, click the Server - Performance tab. 2. Select the Activity Trends - Resource Balancing view. 3. Choose Resource Balancing - Options to open the Server Profile Options dialog box. 4. Click General. 5. Under Activity Data Search Order, choose one or both: • Search Local Activity Databases — To search the Activity databases (ACTIVITY.NSF) on each server on which Activity Trends is enabled.

Using IBM Tivoli Analyzer for Lotus Domino 54-27

• Search Activity Data Proxy Servers — To use servers that contain activity data copied or replicated from another server. Enter the name of the servers that have the proxy data. Activity Trends Collector proxy data options are configured in the Configuration Settings document in the Domino Directory. 6. Under Activity Trends Data Cache for the field “Enable caching of activity data,” do one: • Check Yes (default) — To cache Activity Trends data. When data is cached, if the data for a server has already been retrieved (even though the server may not appear in any of the server lists), the cached data is used. • Uncheck Yes — To gather Activity Trends data every time a new server is added. Data from servers that are removed is discarded immediately, and new data is retrieved. 7. For the field “Cache expiration time out,” enter the number of minutes that data remains cached after the server’s data is first retrieved. The default is 360 minutes. 8. Choose one of the following to set location defaults. These defaults apply only to items on the current tab. • Use Defaults — To revert to previously stored custom defaults. • Save as Defaults — To save a custom set of defaults and override the system defaults. • Reset Defaults — To revert to the system defaults.

Setting charting options for resource balancing
You can set options for how Activity Trends charts display on the Domino Administrator Server - Performance tab. For all Activity Trends views, you can specify font appearance and show database names instead of file names. You can specify additional charting options that apply individually to the Latest folder, Historical folder, and the Resource Balancing views. You can open the Server Profile Options dialog box from the Activity Trends or Resource Balancing menus, or by clicking the Server Profile Options button:

54-28 Administering the Domino System, Volume 2

To set chart options 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and click Resource Balancing. 2. Choose Resource Balancing - Options to open the Server Profile Options dialog box. 3. Click Charting. 4. Under Font Preferences, select the way that type will appear on all charts in all Activity Trends views. The defaults are:
Chart Element Chart Heading Font Chart Axis Label Font Font Size Appearance Bold Plain Plain Default Sans Serif 12 Default Sans Serif 8 8

ChartLegend Font (when visible) Default Sans serif

5. Under Resource Balancing Display Options, check Yes to enable these options for Resource Balancing view. The default is unchecked.

Monitoring

• Show actual values on Y-axis when displaying non-normalized data • Show chart using 3D effect 6. Under Latest Activity Display Options, do the following to set the appearance of for the Activity Trends - Latest folder views: a. For the field “Maximum X-axis items that can be displayed” enter the number of items that can be shown in the horizontal position on the chart. The default is 1000. b. Check Yes to enable these display options. The default is unchecked: Show database titles on X-axis Show actual values on Y-axis when displaying single data type (such as bytes, transactions, milliseconds) Show chart using 3D effect 7. Under Historical Activity Display Options, check Yes to enable these options for the Activity Trends - Historical folder views. The default is unchecked. • Show actual values on Y-axis • Show chart using 3D effect 8. Choose one of the following to set Charting defaults: • Use Defaults — To revert to previously saved custom defaults. • Save as Defaults — To save a custom set of defaults and override the system defaults. • Reset Defaults — To revert to the system defaults.
Using IBM Tivoli Analyzer for Lotus Domino 54-29

Primary and secondary goals for resource balancing
To balance resources, first determine your primary and secondary goals, and specify how much weight to give each of these goals. The default goals are Notes Transactions and Disk Space, which are the defaults for Primary and Secondary goals respectively. Because transactions factors in almost all user and server activity, and disk space is typically a constrained resource, these are a good measurement on which to balance. The second factor in resource balancing is tolerance. When you specify tolerance, you indicate the level of accuracy you want for the resource. A low value typically generates more moves (it is less tolerant when the values are lower), but produces a better distribution of the resources that are closer to the targeted accuracy. A higher tolerance value creates fewer moves, but does not distribute the activity as evenly. You set tolerance values for both the Primary and Secondary Goals, however the primary tolerance is much more important than the secondary tolerance in determining the number of moves. Finally, you specify whether to use trended data or data collected from one observation period. You also choose when to gather the data. For more information about trended data see the topic “Understanding how Activity Trends collects data,” earlier in this chapter. The resulting resource chart may show heavy activity on some servers and light activity on others. You can choose to balance the activity across the servers so that no single server shows a high incidence of activity. You can balance resources based on a primary and a secondary goal. Unless you have specific requirements in mind, the recommended primary and secondary goals are Notes Transactions and Disk Space, respectively. Because the primary goal is given more weight than the secondary goal, set the resolution of the most troublesome resource area as the primary goal. For example, if you suspect that some servers have available disk space, while others have almost none, choose the statistic Disk Space as the primary goal.
Statistic Name AvgSpaceUsed DiskSpace FullTextIndexSize Description Percentage of the disk space actually in use, as recorded by the database activity data. The number of bytes of disk space occupied by the database, as recorded by the database activity data. Size of the full-text index for this database. continued

54-30 Administering the Domino System, Volume 2

Statistic Name

Description

HTTP BytesFromServer The number of bytes sent from the database, as recorded by the user session data. HTTP BytesToServer HTTP RequestMsecs HTTP Requests The number of bytes sent to the database, as recorded by the user session data. Request time, in milliseconds. The number of HTTP requests.

Notes BytesFromServer The number of bytes sent from the server, as recorded by the user session data. Notes BytesToServer Notes Connects Notes DocumentsRead Notes DocumentsWritten Notes Transactions Replica BytesRead Replica BytesWritten Users The number of bytes sent to the server, as recorded by the user session data. The number of database connections, as recorded by the user session data. The database read count, as recorded by the database activity data.

Monitoring

The database write count, as recorded by the database activity data. The number of transactions, as recorded by the user session data. The number of bytes read, as recorded by the Replicator task. The number of bytes written, as recorded by the Replicator task. The count of unique users, as recorded by the user session data.

Setting primary and secondary resource-balancing goals
To balance resources, you establish two goals based on two selected statistics. Each goal is based on a statistic that is associated with the activity you want to balance. You can open the Server Profile Options dialog box from the Resource Balancing menu, or by clicking the Server Profile Options button:

1. From the Domino Administrator, click the Server - Performance tab. 2. Select the Activity Trends - Resource Balancing view. 3. Choose Resource Balancing - Options to open the Server Profile Options dialog box.
Using IBM Tivoli Analyzer for Lotus Domino 54-31

4. Expand the Balancing section, and then click Goals. 5. Complete these fields to specify the primary goal:
Field Statistic Name Tolerance Analyze Action Select a statistic from the list. The default is Notes Transactions. Enter a percentage. The default is 10%. Choose one: • Trended Data (default) — To analyze the resource balance based on trended data. • Last Observation Data — To analyze the resource balance based on the data that was gathered during the most recent observation time. Over period Choose one: • Complete Day (24 hours) — To analyze data gathered during a 24-hour period. • Prime Shift Only (default) — To analyze data gathered during the prime shift hours. Note The prime shift hours are defined on the Activity Logging tab of the Configuration Settings document.

For more information on defining prime shift hours, see the topic “Setting up Activity Trends” earlier in this chapter. 6. Click Secondary Goal, and repeat Step 5 to specify the values for the secondary goal. Goals that were selected as Primary goals will not appear in the list of available statistics for secondary goals. 7. (Optional for secondary goal only) Enable “Other options” if any tolerance value is acceptable as a solution for resource balancing. 8. Choose one of the following to set defaults for goals. You can set these defaults on either the Primary or Secondary Goal tab. • Use Defaults — To revert to previously saved custom defaults. • Save as Defaults — To save a custom set of defaults and override the system defaults. • Reset Defaults — To revert to the system defaults.

Specifying which databases can move during resource balancing
To specify which databases can move during resource balancing, you create a master pin list. Because system databases, such as the Domino Directory, are never moved, do not include them in the pin list.

54-32 Administering the Domino System, Volume 2

You pin databases in one of two ways. You can list databases you do not want to move, or you can list only the databases that you do want to move. After you define a pin list, you can save it as a pin list profile. Tip You can also pin individual databases from the Available Databases list in the Server - Performance tab, in the Resource Balancing view of the Domino Administrator. By default, all databases are associated with all servers. The server name can be specified as part of the entry. Use a colon to specify the server part. For example, Acme/East:mail/*.nsf applies to all mail/*.nsf databases on the server Acme. When you select servers to balance resources, you should be aware that Activity Trends does not recognize that servers are in a cluster. If you include servers from different clusters or some servers that are in a cluster and some servers that are not in a cluster, Activity Trends may suggest moving a database out of a cluster in order to balance the resources. To prevent this, you can create a separate server profile for each cluster and one for nonclustered servers, or you can pin databases that you want to exclude from resource balancing. You can open the Server Profile Options dialog box from the Resource Balancing menu, or by clicking the Server Profile Options button:

Monitoring

To create a master pin list 1. From the Domino Administrator, click the Server - Performance tab. 2. Select the Activity Trends - Resource Balancing view. 3. Choose Resource Balancing - Options to open the Server Profile Options dialog box. 4. Expand the Balancing section, and then click Pin List. 5. Click the Database Pin List tab. 6. Under Pin Method, choose one: • Pin listed databases — To pin the listed databases so that they will not be moved. • Pin all but listed — To make the listed databases available to be moved, and pin all other databases. 7. Under “Database List,” add or delete databases. To add a database, enter the name directly on the list.

Using IBM Tivoli Analyzer for Lotus Domino 54-33

8. Next to the list of database names, do one: • Choose Reset to return the list to its original set of databases. • Choose Save as, and enter a name to save a new pin list. 9. Choose one: • Use Defaults — To revert to previously saved custom defaults. • Save as Defaults — To save a custom set of defaults and override the system defaults. • Reset Defaults — To revert to the system defaults. To edit or delete a saved pin list profile 1. Under “Saved Pin List Profiles,” select a profile. 2. Do one: • Edit the list of databases, and then click Save. • Click Delete.

Understanding resource-balancing behavior
When you set the resource-balancing behavior, you balance the amount of moves made during resource balancing with the amount of accuracy achieved. Accuracy is how successfully the moves were made, based on the number of moves allowed. The higher the accuracy, the more evenly resources are balanced. You also specify the location of the Domino Change Control database (DOMCHANGE.NSF). By default, Activity Trends automatically selects a server. However, you must specify the Domino Change manager server in the Configuration Settings document. Use the default unless you want to use a local replica or are working remotely and want to use a server that has a replica of the Domino Change Control database. Resource balancing distributes database activity across three bins: • • Light — The top bin when graphed, has the lightest amount of activity. Medium — The middle bin when graphed, has a medium amount of activity. This percentage is calculated based on the percentage in the other two bins. Heavy — The bottom bin when graphed, has the heaviest amount of activity.

54-34 Administering the Domino System, Volume 2

Resource balancing attempts to balance the bins among the servers as well as the total for the servers. This is important because heavily utilized databases (databases with a high number of transactions) also have the greatest variance. That is, their usage is more likely to vary from the mean more frequently. This means that when there is a spike in activity, the spike will be a big spike, and the dip will be a big dip. Dividing the databases into bins separates the few databases that account for a large amount of activity, from the large amount of databases that account for little activity. For example, out of 100 databases on a server, 10 databases may account for 30% of activity, while 65 databases account for another 30%. The remaining 40% of activity is accounted for by the medium usage 250 databases. Balancing according to the bins, ensures that the spread of heavily used and lightly used databases are evenly distributed across the servers. This results in more predictable usage patterns, increased availability, and more efficient use of resources. Deciding the exact percentages for each of the bins depends on how your organization uses their databases and the type of server being balanced (mail server versus application server). For mail servers in most organizations you may want to increase the size of the light bin and decrease the size of your heavy bin, while for application servers the mix may be different. For more information about charting bin activity and how the values are calculated, see the topic “Understanding current and projected profile charts,” later in this chapter. You also specify how Activity Trends analyzes the server resource capacities. By default, server capacities are determined relative to other servers in the list. For example a server that has a capacity of x1 transactions has half the transactional capability (CPU) of a server at x2. You could, however balance resources based on actual values (such as the number of transactions per day, or the total amount of disk space available). Using the example above, you would specify the servers as having a capacity of 10,000 and 20,000 transactions. However, if you choose to balance resources based on actual values, you have to know that the servers involved can actually handle the capacities specified. Another way in which you indicate server resource capabilities, is to specify how the server volume is determined. You can either use server volume and file system information when resource balancing, or ignore volume information and treat all space as flat. The default is to use the volume information, which uses the different physical volumes and their sizes that comprise the space available to Domino, rather than just the total amount of space on the server. Volume balancing is recommended.
Using IBM Tivoli Analyzer for Lotus Domino 54-35

Monitoring

This may produce plans in which a database moves to a different server and has a different destination path because of space requirements on a particular volume on the destination server.

Customizing resource-balancing behavior
Customizing resource-balancing behavior is an advanced feature. Therefore, unless you know how changes will affect the outcome of resource balancing, use the default settings To customize resource-balancing behavior 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and click Resource Balancing. 2. Choose Resource Balancing - Options to open the Server Profile Options dialog box. 3. Expand the Balancing section, and then click Advanced. 4. Under Resource Balancing Behavior, choose one: • Minimize Moves — To minimize the number of moves made, even though the balance may not be as accurate when completed. • Balance Moves and Accuracy — To allow more moves, in an effort to reach a higher level of accuracy. • Maximize Accuracy — To allow as many moves as it takes to get the most accurate resource balance. 5. Under “When submitting a resource balancing plan” choose one of these: • Automatically Select Server — to automatically locate the server in the domain that has the Domino Change Control database (DOMCHANGE.NSF). This is the default. • Use Local Database Replica — and then enter the path to use a replica of the Domino Change Control database (DOMCHANGE.NSF) located on the local drive. • Use Remote Server — and then enter the name of the server that has the Domino Change Control database (DOMCHANGE.NSF). 6. Under Bin Sizes, choose the percentage for each bin: • Light Bin — Default is 30% • Middle Bin — Default is 40% • Heavy Bin — Default is 30%

54-36 Administering the Domino System, Volume 2

7. For the field “Enter server resource capacities as relative values when editing server properties,” do one: • Check Yes (default) to specify server resource capabilities relative to other servers in the list. • Uncheck Yes to specify actual values, such as the number of transactions per day or the total amount of available disk space. 8. For the field “Use server volume and file system information when resource balancing,” do one: • Check Yes (default) to use the volume information, such as physical volumes and their sizes that comprise the space available to Domino. • Uncheck Yes to ignore volume information and use the total amount of space on the server, treating all space as flat. 9. For the field “Warning when data is older than n days,” enter the number of days before a warning is generated. The default is 7 days. Then if you create a resource-balancing plan and the data is older than 7 days, you receive a warning that the resulting plan will be based on old data. 10. Choose one of the following options to set Resource Balancing behavior defaults: • Use Defaults — To revert to previously saved custom defaults. • Save as Defaults — To save a custom set of defaults and override the system defaults. • Reset Defaults — To revert to the system defaults.

Monitoring

Analyzing resource-balancing distributions
Use any of these procedures to analyze the current and proposed distribution of user activity on specified databases. The statistics and charts displayed during this process reflect the choices you made in the Server Profile Options dialog boxes. 1. Create a proposal for a new, balanced distribution. 2. Compare the current and projected distribution of databases on servers. 3. Review the distribution of user activity represented in the light, medium, and heavy bins. Review the effect of changes on other resource statistics in these charts as well. The accuracy is only a guide as to how well it achieved the balance within the tolerance specified. Sometimes the required accuracy may not be achieved for
Using IBM Tivoli Analyzer for Lotus Domino 54-37

a particular server. There are many reasons why this could happen. Sometimes, there is no solution within the parameters specified and resources are balanced as well as they can be. 4. Review the server capacity and accuracy information before and after proposed targets. 5. Change the mix of servers and server properties and run the analysis again, if necessary. 6. Submit a plan to the Domino Change Manager to implement the new balance of resources.

Creating a proposal for balanced resources
Based on the selections made in the Server Profile Options dialog box, you can balance resources for a server profile that you created. During the resource-balancing process, it may take several attempts before databases are distributed in a way that you find acceptable. You may need to change source server or database selections. You can make these adjustments during this process to help make the analysis process run smoothly. • • • • Pin and unpin databases Change server properties or add a phantom server Filter out servers and their databases that you do not want displayed on the Available Databases tab Change the layout of the Activity Trends view on the Server Performance tab of the Domino Administrator

To create a proposal 1. From the Domino Administrator, click the Server - Performance tab. 2. Under Activity Trends, click Resource Balancing. 3. Choose a server profile. 4. Click the “Available Databases” tab to display the list of databases that can be moved. 5. (Optional) To change the databases that are available for moving, select a database and click Pin or Unpin. 6. Make sure that each server in the top frame has an arrow next to its name. If there is a red (x) instead of an arrow, the server is not reporting its trended data. You must remove the server or make it a phantom server; otherwise, the Analyze button will be disabled and you will not be able to create a proposal. 7. Check the server properties to make sure that the capacity of each server is weighted correctly.
54-38 Administering the Domino System, Volume 2

For information on editing server properties, see the topic “Editing server properties for resource balancing” later in this chapter. 8. Click Analyze. 9. When the analysis is complete, view the Recommended Plan and Project Profile.

Comparing current and projected resource balances
After creating a proposal for balanced resources, compare the proposal against the current resource profile by reviewing the information on the Resource Balancing tabs. The Available Databases and Current Profile tabs display information about the current state of the servers. You can also look at the information in the upper frame, which shows you the current and projected activity, and the targeted and achieved accuracy. The Recommended Plan and Projected Profile tabs, which are populated after you analyze current resources, display the distribution of resources after the plan is completed. The Resource Balancing view is on the Server - Performance tab of the Domino Administrator. The four tabs provide the following information about the servers for which you want to balance resources: • • • • Available Databases — Lists the databases that are not pinned in the Master Pin List and are, therefore, available to be moved Recommended Plan — Shows the new source and proposed destination for the databases Current Profile — Shows how the servers are currently balanced Projected Profile — Shows how the servers will be balanced after the plan is carried out

Monitoring

Evaluate the changes that are proposed during resource balancing. If you are not satisfied with the proposed changes, change the mix of servers or databases or adjust the specified tolerance level in the Server Profile Options dialog box. If you are happy with the proposal, then you are ready to submit the plan to the Domino Change Manager.

Evaluating server activity for resource balancing
To balance resources, evaluate the database activity for each server on which you want to balance resources. Then compare that activity to redistributed database activity that would result from balancing resources. The Resource Balancing view on the Server - Performance tab of the Domino Administrator provides this information in a number of ways. First, the status of selected servers or of servers in a selected server profile displays. A red X next to the server indicates that the server is not available for resource balancing, possibly because the server is down.
Using IBM Tivoli Analyzer for Lotus Domino 54-39

Hover over the red X with your mouse to see the status of the server, including the error message. The Edit Server Properties dialog box also shows associated error messages in the Status field. For each goal specified in the Server Profile Options dialog box, Activity Trends displays the following information that you use to evaluate whether a server is a candidate for resource balancing: • • Current — The current value of the metric as recorded. Capacity — The resource capacities of each server. Resources are balanced using either capacity or target values. By default, the capacity is the value used in determining the targets during resource balancing. You set this value by editing server properties. Target — The target value that you want to meet during resource balancing. This value is based on the statistics specified as primary and secondary goals. For example, if Notes Transactions is a goal, the value is the number of transactions. So, if a server has a target of 2000 transactions, the resource-balancing solution attempts to provide this server with 2000 transactions. Projected — The calculated final value of the server’s resource, if the generated solution (plan) were to be applied. Accuracy — A percentage from 0 to 100 that represents how successfully the moves were made, based on the behavior criteria you specified. A low percentage is bad and a high percentage is good. Servers whose values are within the tolerance for the goal (set in server profile options) display in blue. Values that did not achieve the tolerance specified for the Goal display in red. This is not necessarily bad, sometimes it means you need to use other servers or that there is no good solution for this resource problem. In a good balance, there should be almost no red values for the primary goal, and perhaps a few ones for the secondary.

• •

If you do not like the distribution of activity or servers based on this evaluation, you can edit the server properties to change the server role. Likewise, you can alter some of the options selected in the Server Profile Options dialog box. If you have not set server profile options, you can edit the server properties to change some of the option defaults, and then analyze again using the new server values. For more information on editing server properties, see the topic “Editing server properties for resource balancing” later in this chapter.

54-40 Administering the Domino System, Volume 2

Understanding current and projected profile charts
To determine the proposed resource distribution, view the charts of trended statistics created by Activity Trends. The Resource Balancing view on the Server - Performance tab of the Domino Administrator displays database activity for each server. The chart on the Current Profile tab represents the current server load. The chart on the Projected Profile tab shows how the servers will be rebalanced if the proposed plan is implemented. The charts use light, medium, and heavy bins to show the distribution of user activity. Each bin represents a group of databases and their metric values. These bins reflect the “bin sizes” values specified in the Server Profile Options dialog box. View the distribution of activity before it is balanced (Current Profile), and then view it again to determine if your goals have been met. Resources that are not well balanced show a disproportionate amount of activity in the heavy bin. After resource balancing has been applied, the recommended distribution in bins should be relatively even across the servers, if your goals were achieved. The higher the accuracy of resource balancing, the more evenly activity is distributed. Example The following chart shows database transactions on each server. The overall height of the bar represents the sum (total) of the database transactions. The three bins represent the light, medium, and heavy modal distribution of the database metric — in this case, transaction. In this example, heavy is the first 30% of databases; middle is the next 40%; and light is the top 30%, all adding up to 100%.
100 90
Light activity

Monitoring

80 70 60 50 40 30 20 10 0
Heavy activity Medium activity

Using IBM Tivoli Analyzer for Lotus Domino 54-41

• • •

Light — The light bin is the top bin when graphed, using the lightest color of blue. This indicates the bin with the lightest amount of activity. Medium — The medium bin is the middle bin when graphed, using a medium blue. This indicates the bin with a medium amount of activity. Heavy — The heavy bin is the bottom bin when graphed, using the darkest color of blue. This indicates the bin with the heaviest amount of activity.

How bin values are calculated To understand how bin values are calculated, assume there are 20 databases, each with a varying number of transactions. Five is the lowest number of transactions on any database, and 420 is the highest number of transactions on the most active database. The total transactions per database is represented as follows: 5,5,10,10,15,25,25,50,75,100,120,125,140,150,250,300,310,350,400,420 = 2885 transactions When you group these transactions based on the bin sizes designated in the Server Profile Options (30% light, 40% medium, and 30% heavy), the transactions are distributed as follows: Light = 5,5,10,10,15,25,50,75,100,120,125,140,150 (14 databases account for 855 transactions; 865 is the target) Middle = 250,300,310 (3 databases account for 860 transactions; 1154 is the target) Heavy = 350,400,420 (3 databases account for 1170 transactions; 866 is the target).
1 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0
Sales1
Server: Sales1/Acme Stat: Notes Transactions Units: transactions Total: 2885 [DBs: 20] Light: 855 [DBs: 14] Medium: 860 [DBs: 3] Heavy: 1170 [DBs: 3]

54-42 Administering the Domino System, Volume 2

When you view these charts, you see that 29% of the chart is light blue; 30% is medium blue; and 40% is dark blue. Hovering over the bar on the chart, the pop-up shows that most transactions on the server occur on relatively few (three) databases. In this case, 15% of the databases account for about 40% of the transactions. If the bars for the other servers on which you are balancing resources have different proportions for light, medium and high bins, then resource balancing would better spread the load across the system and probably result in better server performance.

Using resource balancing in Activity Trends to decommission a server
Decommissioning a server is a special case of workload balancing in which everything outside the default pin list is moved from the server. The databases that remain, which may still account for significant activity, are either system databases or databases that are typically installed on every server, such as templates or help files. In most cases the latter group will be the same on every server, with the possible exception of unread marks. Use these guidelines to decommission a server: 1. Edit the server properties and do the following: • Set the server as “source only” to prevent Activity Trends from moving any databases to it. • Set the server capacity to 0% for the unit you are using as the primary balancing goal. 2. Use the default pin list so that Activity Trends relocates all databases other than the system databases and the databases installed on every server. You can also use an empty pin list since system databases are always pinned.

Monitoring

Editing server properties for resource balancing
You can balance resources based on capacity or on a specified target. For example, if you have a new server, you can redistribute server activity to accommodate the increased resource capacity. However, if you need to increase the number of transactions per server, you balance resources by redistributing activity based on achieving a new target value. In addition, you can assign a weight to each server’s capacity. For example, assume you have one server with 1.5GB of RAM and a 60GB hard drive and have a second server with 3GB of RAM and a 120GB hard drive. You can enter the capacity of the first server as 1 and the second server as 2, giving it twice the weight.
Using IBM Tivoli Analyzer for Lotus Domino 54-43

If you set a capacity (or target) of zero for source-only or any-role servers, resource balancing tries to move all unpinned databases on the server. This is useful when decommissioning servers and moving their contents to new servers. If a server’s data cannot be obtained, you can treat the server as a phantom server and then change it back to a real server when data becomes available. After changing it back, press F9 to refresh and read the data from the server. To edit server properties 1. From the Domino Administrator, click the Server - Performance tab and open the Resource Balancing view. 2. Under Server profiles do one: • Select a profile • Select All Servers 3. In the Servers section, double-click the server whose properties you want to edit. In the Edit Server Properties dialog box, the server name and domain name appear by default. Complete the following fields:
Field Type Action Choose one: • Real — To identify a server that physically exists in the domain. • Phantom — To identify a server that does not physically exist but is factored in to the resource-balancing analysis. Note The option to toggle between a real server and a phantom server is available only for real servers whose data cannot be obtained. Role Choose one: • Any — Databases can be moved to or from the server. • Source Only — This server will not have any databases moved to it. • Destination Only — This server will not have any databases moved from it. Note Phantom servers are always Destination Only. Goals Select either the primary or secondary goal from the list. These are the goals set in the Server Profile Options dialog box. For more information about goals, see the topic “Primary and secondary goals for resource balancing.” continued

54-44 Administering the Domino System, Volume 2

Field

Action

Capacity Select this option to balance resources for the selected goal, based on server capacity. Enter the number of resource units. The default is 1. Target Select this option to balance resources based on achieving a target goal. Enter a target value for the goal you selected.

Filtering servers used during resource balancing
You can change the displayed list of available databases by setting filters that hide databases from display without affecting the master pin list or affecting how a plan is generated. Using these options provides you with the information you want quickly and easily. For example, using “hide databases appearing in plan” shows only the databases that will remain and filters out all databases that will move. The “hide system databases” and “hide master pin databases” options show all of the databases on the servers, even though you don’t want to move them. This option is useful when you need to see the complete picture of databases on a server and is useful especially when decommissioning a server. To filter servers 1. From the Domino Administrator, click the Server - Performance tab and open the Resource Balancing view. 2. Click the Filter button on the Available Databases tab. 3. In the Servers field choose one: • All Servers • Selected Servers 4. Check or uncheck one or more: • Hide System Databases (default is checked) • Hide Master Pin Databases (default is checked) • Hide Databases appearing in Plan (default is unchecked)

Monitoring

Pinning additional databases during resource balancing
When you set the Server Profile Options, you create a pin list of databases that cannot be moved during resource balancing. However, as part of the resource-balancing process, you can pin or unpin databases. For example, you may want to evaluate the effect of pinning an additional database, or you may want to unpin a database to see if resources balance with fewer moves. Pinning or unpinning databases as you balance resources does not change the saved pin list. You cannot unpin a system database or a
Using IBM Tivoli Analyzer for Lotus Domino 54-45

database that is pinned by the master pin list. However, the status of each database is saved with the server profile information for the selected server profile. To pin or unpin databases as you balance resources 1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends section, and choose Resource Balancing. 2. Click the Available Databases tab. 3. Do one of the following: • Select the databases that cannot be moved, and then click Pin. • Select one or more databases that are currently pinned, and then click Unpin. 4. Click the Analyze button to see the effect of the new pinning information.

Displaying additional statistics during resource balancing
You can change the statistic that displays on the current or projected profile chart so that you can view the balance of other types of database activity. By default, when you balance resources, the primary goal is the statistic that displays. 1. From the Domino Administrator, click the Server - Performance tab and open the Resource Balancing view. 2. Click the Filter button on the Available Databases tab. 3. Select the statistic you want to display. 4. Under Options, select one or more of the following. The defaults vary depending on the statistic. • Use Trended values — to use trended statistics, instead of current statistics. • Use Prime Shift values — to use statistics collected during the prime shift hours. Prime shift hours are specified in the Configuration Settings document when you set up Activity Trends. • Size in proportion to capacity — to base statistics on server capacity. Server capacity is specified in the server properties. For more information on setting prime shift hours and editing server properties, see the topics “Enabling activity logging and setting up Activity Trends” and “Editing server properties for resource balancing,” earlier in this chapter.

54-46 Administering the Domino System, Volume 2

Changing the layout of the Activity Trends view
You can change the layout of the charts in the Activity Trends or Resource Balancing view. For example, you can maximize the sections you are working on to reduce the amount of scrolling. You can change the layout of the chart display using the Resource Balancing or Activity Trends menus, or the layout button:

1. From the Domino Administrator, click Server - Performance. 2. From the Resource Balancing menu, select layout, and then choose one: • Maximize • Maximum Width • Maximum Height • Restore

Monitoring

Submitting a resource-balancing plan to the Domino Change Manager
When you decide to implement resource balancing, you submit a plan to the Domino Change Manager. To submit a resource-balancing plan 1. From the Domino Administrator, click the Server - Performance tab. 2. Select the Resource Balancing view, and then select the Recommended Plan tab. 3. Click Submit to submit the current data to the Domino Change Manager. 4. Enter a plan name and a description of the plan. 5. The field “Submit to” displays the option selected in the Advanced section of the Server Profile Options. Click the button at the right of this field to open the Server Profile Options dialog box and change this selection.

Using IBM Tivoli Analyzer for Lotus Domino 54-47

Domino Change Manager
To implement a resource-balancing plan, you use the Domino Change Manager task, which you load on only one server, usually the Administration server, in a domain. The Domino Change Manager uses the Domino Change Control database (DOMCHANGE.NSF) to manage and implement a plan. After you submit a plan, you track the status of the plan in the Domino Change Control database (DOMCHANGE.NSF). To access the Domino Change Manager from the Domino Administrator, choose Server Analysis, then expand the Domino Change Control view and choose “Plans - by Status.”

The Domino Change Manager and the Administration Process
The Domino Change Manager uses the Administration Process to move databases from one server to another. Data is collected and stored in the Activity Trends database (ACTIVITY.NSF). When you use resource balancing to create a plan for redistributing the database load, it first initiates a database move command. Then it generates the “Maintain Trends Database Record” request during the standard execution of the database move. The “Maintain Trends Database Record” request is posted in the Administration Requests database (ADMIN4.NSF) after the database is created on the destination server. During the execution of the “Maintain Trends Database Record” request, the administration requests that typically require your approval are automatically approved because the plan has been approved. You do not have to manually approve requests in the Administration Requests database (ADMIN4.NSF). For more information on the Maintain Trends Database Records Administration Process request, see the appendix “Administration Process Requests.”

Setting up Domino Change Manager
To set up the Domino Change Manager, you load the Change Manager task. Then, the first time you run the task, it creates the Domino Change Control database (DOMCHANGE.NSF). Load this task on only one server in the domain — usually the Administration server. To set up and run the Change Manager task 1. Open the NOTES.INI file for the server on which the Change Manager will run.

54-48 Administering the Domino System, Volume 2

2. Add the following to the ServerTasks setting:
runjava ChangeMan

3. Save and close the NOTES.INI file. 4. At the console, enter this case-sensitive command exactly as shown:
load runjava ChangeMan

Tip To display full help text for this task, append -? or -help to the command.

Specifying maximum concurrent tasks for Domino Change Manager
There are three thread pools that control the number of concurrent tasks that the Domino Change Manager can carry out. The combination of the number of concurrent plans and demands creates a pool from which all the demands of all the plans are run. How the size of these thread pools affects performance depends on the size of the server. If necessary, you can limit the amount of CPU used by the Domino Change Manager. On very powerful machines, however, you may want to increase these numbers considerably. You typically want to increase the number of concurrent demands to change the total number of demands (across all executing plans) that can run simultaneously. This is the key variable that will affect performance. As a general guideline: • Increase the number of concurrent messages when you have many people drafting, preparing, and submitting many plans. If you have only a few plans, this is not necessary. Increase the number of concurrent plans when you want many plans to execute at the same time.

Monitoring

You set these options in the Configuration Settings document for the domain. This Configuration Settings document applies the settings as the default settings for all servers and uses the * [All Servers] as the group or server name. To specify the maximum concurrent tasks 1. From the Domino Administrator, click the Configuration tab, expand the Server section, and click Configurations. 2. Select the * [All Servers] Configuration Settings document, and click Add Configuration or Edit Configuration.

Using IBM Tivoli Analyzer for Lotus Domino 54-49

3. Click the Change Control tab, and complete these fields:
Field Domain Change Server Database file name Action Choose the server that stores the Domino Change Control database (DOMCHANGE.NSF). Enter the name of the Domino Change Manager. The default name is DOMCHANGE.NSF in server/data directory. If the database is not in the default directory, enter a full path name. Enter the maximum number of messages that can be executed at the same time. The default is 5. The recommended number is between 1 and 10. Enter the maximum number of plans that can be executed at the same time. The default is 5. The recommended number is between 1 and 10. Enter the maximum number of demands (for example, database moves) that can be simultaneously processed. The default is 40. This number should be equal to or larger than the “Max. concurrent plans” number.

Max. concurrent messages Max. concurrent plans Max. concurrent demands

4. Click Save & Close.

Using the Tell ChangeMan command at the Domino console
You can use the Tell ChangeMan command at the console to control the Domino Change Manager. The following options are available. The command Tell ChangeMan is not case sensitive.
Option quit stop exit help ? restart start plug-in stop plug-in Action Stops the Change Manager and all plug-ins. Stops the Change Manager and all plug-ins. Same as Quit. Stops the Change Manager and all plug-ins. Same as Quit. Refers you to documentation. Refers you to documentation. Same as Help. Stops and then restarts the Change Manager and all plug-in subsystems. Starts the plug-in. Currently, Control, Monitor, and RoboAdmin are the defined plug-ins. Stops the plug-in. Currently, Control, Monitor, and RoboAdmin are the defined plug-ins. Note Alternatively, you can also use the forms plug-in stop, plug-in quit and plug-in kill. continued

54-50 Administering the Domino System, Volume 2

Option restart plug-in

Action Stops and then starts the plug-in. Currently, Control, Monitor, and RoboAdmin are the defined plug-ins. Note Alternatively, you can also use the form plug-in restart.

plug-in command Attempts to issue the command to the named plug-in, if it exists and is running. reset Resets the internal lookup caches.

For more information on using Domino server commands, see the appendix “Server Commands.”

ACLs for the Domino Change Control database
There are four ACL roles created specifically for those who are working with the resource-balancing plan. However, users or groups can also have standard Domino ACL roles, such as Author or Reader. The roles specific to resource balancing are: Change Admin, System Admin, Plan Creator, and Plan Reader. Change Admin A Change Administrator has the authority to change the settings in any plan or plan element, such as a constraint or variable. In addition, a Change Administrator can alter and add some elements used to create a plan. Specifically, a Change Administrator can edit, create, and delete constraints and constraint sets, approval profiles, keywords, and resources. A Change Administrator must commit a plan to be executed. All plans (including move requests created in the Administration Process database) execute with the authority of the Change Administrator who committed the plan. For that reason, the Change Administrator must also have Create Replica access on each destination server. A Change Administrator automatically has the Plan Reader role. System Admin The System Admin role is distinct from the Change Admin role, which does not automatically include the role of System Admin. Each of these roles is independent but not mutually exclusive in terms of the access that the role grants. As with a Change Administrator, a System Administrator can edit, create, and delete keywords, resources, interfaces, functions, domain configurations, and plug-Ins. Because users with the System Admin role can make powerful and potentially catastrophic changes, assign the role only to users or groups of users who have an in-depth understanding the Domino Change Manager. In addition, all control
Using IBM Tivoli Analyzer for Lotus Domino 54-51

Monitoring

documents (Interface and Function Definitions, Domain Configurations and Plug-ins) must be signed by either the Change Manager server or a user who has the System Admin role. When the database is first created, all control documents are signed by the server. This is to ensure the security of the Change Manager system and the Domino Server. Plan Creator This role designates users and groups of users who can create plans. Plan Reader This role allows users and groups of users to read all plans. By default a Change Administrator can read all plans and does not explicitly need this role. Authors and Requesters of plans do not need this role to read their own plans.

Default ACL settings for the Domino Change Control database
When the Change Control database (DOMCHANGE.NSF) is created, these default access levels and roles are assigned.
Name Full Access Administrator Administrator (Listed in the Server document of the current server.) Default LocalDomainServers OtherDomainServers Anonymous Access level Role Manager Change Admin System Admin Plan Creator No roles Plan Reader No roles No roles

No access Manager No access No access

Recommended ACL settings Assign the roles of Change Administrator and System Administrator only to administrators who require them. Administrators who have these roles have the ability to alter the basic system documents of a plan. The recommended access level is Editor for most Change Administrators and System Administrators. However, you can assign the Author access level, but add restrictions on editing existing system documents such as Interface or Function definitions. The System Admin role should be especially restricted. Assign the Plan Creator role only to those people or groups in an organization that can create plans. Plan Creators only create plans, they cannot commit them.

54-52 Administering the Domino System, Volume 2

Assign the Plan Reader role to people and groups that will be allowed to read plans only. This role assumes that the people and groups reading the plans are not Authors or Requesters. Make sure that the Change Administrators and servers in the LocalDomainServers group have Create Replica access rights.

Setting ACLs for mail database moves during resource balancing
To move databases within the domain, both the LocalDomainServers group and the Change Administrator who committed the plan must have Create Replica and Create Database rights. 1. From the Domino Administrator, click the Configuration tab, and open the Server view. 2. Open the Server document for the mail server. 3. Select the Security tab. 4. Under server access, add LocalDomainServers and any users with the Change Admin role to these fields: • Create databases & templates • Create new replicas 5. Save and close the document. Note When load balancing, you don’t have to approve the deletion of the mail database on the source server. This is handled by the Domino Change Manager.

Monitoring

Resource-balancing plans
The purpose of a resource-balancing plan is to move databases according to the set of criteria defined in the Server Profile Options. The plan is based on the analysis and proposal created during data exploration in Activity Trends. When a plan is first submitted to the Domino Change Manager, the plan has draft status. By default, the person who submits the plan to the Domino Change Manager is the author and has the Plan Creator role. After the plan is submitted, it follows a prescribed course of submissions and approvals until the final plan is activated and then completed. The flowchart below shows the progression of a resource balancing plan from its original draft state through its completed, archived state.

Using IBM Tivoli Analyzer for Lotus Domino 54-53

Promoting a plan from one state to another, such as from drafted to prepared, can be made from within the plan document or from the Change Control database (DOMCHANGE.NSF).
Draft
Prepare

Legend
Author or Administrator activated Approver activated System activated Administrator or System activated

Submitted
Redraft

Prepared
Redraft Commit Reject Redraft

Committed

Rejected

Approve

Cancelled

Cancel

Approved
Activate Retry Fail

Activated
Hold Release

Failed

Complete

On Hold
Archive

Completed
Archive Archive

Archived (Pseudo-state)

The workflow for processing a plan submitted by Resource Balancing follows these steps: 1. The author fully defines a plan by editing the draft plan. 2. The author or a Change Administrator “prepares” the plan, thereby changing the plan’s status to “prepared.” The prepared state signals that the author is satisfied with the details of the plan and wants to have it executed. 3. A Change Administrator reviews the details of the plan and makes any necessary changes, which are typically limited to adding or removing approvers. At this time a Change Administrator can cancel the plan or commit the plan to execution, subject to approval by various groups and roles. 4. A committed plan is either approved or rejected by approvers. Approval must be unanimous for a plan to be approved. If one of the approvers is a group, only one member must approve the plan. If one approver rejects a plan, it passes into the rejected state. If no approvers are assigned, the plan automatically passes to the approved state.
54-54 Administering the Domino System, Volume 2

5. At any stage, a plan can be canceled. An author can cancel a plan prior to its prepared state. A Change Administrator can cancel a plan any time prior to completion. Canceled and rejected plans can be redrafted. Plans can be changed only in the draft state. If change to a plan is required, cancel or reject it, and then redraft the plan. A redrafted plan begins again in draft status. 6. After a plan is approved (and is within the plan’s optional start and end times for activation), it is moved to activated status. While the plan is in the activated state, a Change Administrator can put any part of the plan on hold. 7. The activated plan runs to completion unless an error causes the plan to fail. If the plan fails, the Change Administrator can change the environment or the plan, and then retry it.

Database move sequences
Database move sequences are generated by Activity Trends Resource Balancing in the Domino Administrator. To move large groups of databases that include more than 25 moves, it groups them into sets of 25 moves or more, called demand sets. A demand set can involve any grouping of commands to be executed. In the Domino Change Manager, these demand sets are titled “database move sequences.” Each database move sequence has a maximum of 25 moves. The contents of each move sequence is generated automatically. You can see these database move sets when you submit a resource-balancing plan to the Domino Change Manager. You can restructure the contents by cutting and pasting the demands from one demand set into another or by creating additional demand sets and new demands. (To cut and paste, select a demand and use the Edit menu.) The Domino Administrator creates as many of these demand sets as needed to accomplish a move. For example, the Acme Move Plan includes 55 database moves, so the Domino Change Manager creates three database move sequences — two that include 25 moves, and one that includes 5 moves. You can determine whether the database moves and database move sequences are executed sequentially or concurrently or any combination of the two. By default, all are moved concurrently. Using the Acme Move Plan example, the Domino Change Manager attempts to perform all three database move sequences at the same time. Within each database move sequence, the Domino Change Manager attempts to move all databases at the same time.

Monitoring

Using IBM Tivoli Analyzer for Lotus Domino 54-55

What happens if a move fails A database move can fail for a number of reasons. For example, a database move fails if a server is down, if the destination server does not have create replica rights, or if the source database has been manually moved or deleted. How the Domino Change Manager handles the failure depends on how the moves are executed: • Concurrently — If any demand fails, the plan continues with other demands. When all demands are in a state of completion or failure, the plan reports a failure to the Domino Change Control database (DOMCHANGE.NSF). You can then retry the move, and the plan will attempt to complete only the demands that failed during the previous attempt. Sequentially — If any demand fails, the plan stops.

Choosing how database moves are executed
You can specify whether database moves are sequential or concurrent. 1. From the Domino Administrator, click the Server - Analysis tab. 2. Open the Domino Change Control view, and then select the Plan - By Status. 3. Select one and then click Edit: • A plan • A database move sequence 4. Under Execution Options, for the field Execution Method choose one: • Sequential • Concurrent 5. Click OK to save and close the document.

Viewing database moves
Anyone with access to the Domino Change Control database (DOMCHANGE.NSF) can view database moves. Approvers can view database moves in the plan document when they are notified to approve the plan. To view database moves in the Domino Change Control database 1. From the Domino Administrator, click the Server Status tab. view. 2. Open the Domino Change Control - Plans view, and then choose one of the following views: • By Status — if you know the status of the plan you want to view • By Author — if you don’t know the status of the plan but you know who the author is
54-56 Administering the Domino System, Volume 2

3. Find the target plan and expand the plan to view the database move sequences. 4. Expand any of the database move sequences and view the individual moves. To view database moves in the resource-balancing plan 1. From the e-mail notification, click the link to the plan. 2. In the plan document, select the Demand Details tab.

Preparing a plan document for resource balancing
After you submit a plan, the plan document is a draft document that may require additional input before it is ready to be submitted to the Change Administrator. In the plan document, you specify how the moves are carried out, when the plan is submitted to the Administration Process, and when you want the Administration Process to execute the plan. When the Domino Change Manager moves databases, it creates groups of database move sequences, called demand sets. You can choose whether to move the demand sets one at a time or all at the same time. Each plan can have an associated approval profile that lists the names of persons or groups who must approve the plan document. If there is no approval profile, you can list the names of approvers in the plan document. If you assign a group as an approver, any one of the group members can approve the plan. For more information on creating an approval profile, see the topic “Creating a resource balancing plan approval profile” later in this chapter. For more information about demand sets, see the topic “Understanding demand set moves” later in this chapter. The Resource Balancing plan document is a dynamic document that provides the current status of the plan and keeps a history of plan modifications, including the author and date of each modification. Whether you make any changes to the plan document, it must be moved to its next state, which is the prepared state. In its draft state the plan can be edited by its author. To prepare a plan document 1. From the Domino Administrator, click the Server - Analysis tab. 2. Open the Domino Change Control view, and then select the Plans by Status view. 3. Select the draft plan to move to the prepared state and then click Edit.

Monitoring

Using IBM Tivoli Analyzer for Lotus Domino 54-57

4. In the Basics section, complete these fields:
Field Name Categories Description Action Enter a unique name for the plan. (Optional) Select a category or enter a new category name. (Optional) Enter a description of the plan.

5. Under Execution options, choose one: • Sequential — To execute each demand set (database move sequence) one at a time. • Concurrent — To move all demand sets at the same time. 6. In the field Activate Plan, do one: • Choose “Only between specified start and stop periods” and specify a time during which the request can be sent to the Administration Process. • Choose “Anytime after specified start” and specify a time after which the request can be sent to the Administration Process. • Choose“ Anytime before specified end” and specify a time by which the request must be sent to the Administration Process. • Choose “At any time (after approval)” to submit the request to the Administration Process any time after the plan is approved. 7. Under Requesters and Authors, the plan automatically displays the name of the person who submitted the plan. However, you can edit either field if, for example, you submitted the plan for someone else but you do not want to remain as the requester or the only author. 8. Click the Approval tab, and complete one or both of these fields:
Field Approval profile Action Do one: • Click “Choose Profile” and select the approval profile from the list. • Click “Clear Profile” to remove the assigned profile. Require approval from Enter the names of users or groups to add to the approval list.

9. Click the Notifications tab. This tab lists, by role, those who will be notified at each stage of the plan. Add or remove the selection of any role as needed. Check Others, and then select from the list to add users to the notification list.

54-58 Administering the Domino System, Volume 2

10. (Optional) Click the Variables tab. The default variable is Execution time, and the value is unspecified. To specify an execution time at which the Administration Process executes the plan, you must edit the variable. For information on editing variables see the topic “Editing and creating resource balancing plan variables” later in this chapter. 11. Click the Constraints tab to view and edit the constraints that will apply to the moves executed by this plan. By default, no constraints are assigned automatically. • Referenced constraints — Lists the constraints that apply to this plan. Click Edit to add or remove one of the constraints. • Ad-hoc constraints — Click New to create a new constraint. For information on creating constraints see the topic “Creating constraints in the Domino Change Manager” later in this chapter. 12. When you finish changing the draft plan, click Apply.

Monitoring

13. Click Change Control to promote this plan from draft state to prepared state, and then click OK.

Creating an approval profile for resource balancing
You use an Approval Profile document to create a set of approvers. Then you can assign the approval profile to one or more resource-balancing plans. You can include users and groups as members of an approval profile. However, if you list a group as a profile member, only one group member must approve the plan. For example, if you move a database that is used by the marketing group, you may want one user, but not all, to approve the plan. If you want all members of a group to approve a plan, enter each user’s name in the approval profile. Changes to the Approval Profile document are tracked for you and listed in the Creation and Modifications section. To create an approval profile 1. Make sure that you have the Change Admin role in the ACL of the Domino Change Control database. 2. From the Domino Administrator, click the Server - Analysis tab. 3. Open the Domino Change Control view, and then select the Setup Approval Profiles. 4. Click Create - Approval Profile.

Using IBM Tivoli Analyzer for Lotus Domino 54-59

5. On the Basics tab, complete these fields:
Field Name (unique) Description Category Members Action Enter a unique name for the profile. (Optional) Enter a description. (Optional) Select a category or enter a new category name. Select the names of users or groups to include in this approval profile.

6. Click the Administration tab, and complete these fields:
Field Owner Administrators Action By default, the owner is the person who creates this document. Enter the names of users who can edit this document. • No (default) — To allow a Change Administrator to delete the plan. • Yes — To prevent anyone except a Change Administrator from deleting the plan. Prevent design refresh Choose one: • No — To allow the upgrade of all template documents during a version upgrade. • Yes (default) — To prevent edited template documents from being overwritten during a version upgrade. This will not affect any documents that the user creates — it will only affect documents that match those from the template’s copy.

Prevent deletion Choose one:

7. Click OK.

Viewing the status of resource-balancing plans
You can view the status of resource-balancing plans in the Domino Change Control database (DOMCHANGE.NSF). 1. From the Domino Administrator, click the Server - Status tab and open the Plans view. 2. Choose one of the following views: • Awaiting Approval — To view plans that have been drafted and submitted, but have not been approved by all approvers.

54-60 Administering the Domino System, Volume 2

• Awaiting Commitment — To view plans that have been fully approved, but have not yet been committed for completion. • Active Plans — To view plans that have been fully committed and are being carried out by Change Manager. • By Status — to view all plans grouped by status.

Setting up plan documents for resource balancing
When you create a resource-balancing plan document, you access directly or edit information in other documents in the Domino Change Control database (DOMCHANGE.NSF). These documents support the plan and play a critical role in providing structure to the plan. You use the following resource balancing plan documents to provide the following information: • • • Constraints — Specify when moves can be made. Variables — Assign a common name that has a referenced value. Notification messages — Create custom notification messages that are sent whenever the plan status changes.

Monitoring

Working with Domino Change Manager constraints
When you create a plan, you can add constraints to specify when the moves will be made to affected databases. By default, no constraints are added to a plan automatically. When you edit the plan, you can assign one or more constraints or constraint sets. You can add a constraint to plans or to database move sequences in a plan. The Domino Change Control database (DOMCHANGE.NSF) includes predefined constraints and constraint sets. The default constraints are: • • • • • • • During standard change windows Is after hours Not during change freeze period Not on workdays Major change Minor change Trivial change

The default constraints sets are:

Using IBM Tivoli Analyzer for Lotus Domino 54-61

To view constraint definitions You can view a definition of each constraint and constraint sets. 1. Make sure that you have the Change Admin role so that you can edit, create, and delete constraints. 2. From the Domino Administrator, click the Server - Analysis tab. 3. Click Domino Change Control, and then select the Setup Constraints view.

Creating constraints in the Domino Change Manager
Use constraints to specify time limitations for database moves. 1. You must have the Change Admin role to create a new constraint. 2. From the Domino Administrator, click the Server - Analysis tab. 3. Click Domino Change Control, and then select the Setup Constraints view. 4. Click Create - Constraint. 5. On the Basics tab, complete these fields:
Field Name Unique name Description Action Enter a name. This name appears in the Setup view. Enter a unique name. This is the name of the document you are defining. Enter a description of the constraint.

6. Under Behavior, click Choose Function, and then select a function. 7. Click the Variables tab, and then click Edit to add a variable to this constraint. 8. Click OK to save and close the document. Note To edit a constraint, select a constraint and edit the fields listed in Steps 5 through 7. When you edit a constraint, you can also edit the arguments for assigned variables.

Creating constraint sets in the Domino Change Manager
You use constraints to specify time limitations for database moves. 1. You must have the Change Admin role to create a new constraint. 2. From the Domino Administrator, click the Server - Analysis tab. 3. Click Domino Change Control, and then select the Setup Constraints view. 4. Click Create - Constraint Set.
54-62 Administering the Domino System, Volume 2

5. On the Basics tab, complete these fields:
Field Name Unique name Description Action Enter a name. This name appears in the Setup view. Enter a unique name. This is the name of the document you are defining. Enter a description of the constraint.

6. Click the Constraints tab, and then click Edit. 7. Select the constraints you want to include in this constraint set. 8. Click OK to save and close the document.

Working with plan variables
A variable is a convenient way to specify context for the execution of the demand sets and their demands. Values for variables that are defined within parent objects (such as plans and demand sets) can be used by lower-level objects, such as demands and constraints. For example, you can define a plan variable called ExecutionTime. Then you can specify the value (in time) that you want a plan to be executed. You define a variable at a higher level (usually within a plan) and then reference it within a demand. When the value of a variable changes, all demands and plans that reference that variable automatically use the new value. If you have the Change Administrator role, you can add, delete, or modify local variables that are referenced by function arguments and other variables.

Monitoring

Editing and creating plan variables
The one default variable for the Domino Change Control database is called Execution Time. This variable determines when the Administration Process executes the plan. To edit a variable 1. You must have the role Change Admin role. 2. From the Domino Administrator, click the Server - Analysis tab. 3. Open the Domino Change Control view, and then select the Plans by Status view. 4. Open a plan in edit mode, and then select Variables tab. 5. Click Edit. 6. In the Edit Variables dialog box, select a variable from the list, and then click edit.
Using IBM Tivoli Analyzer for Lotus Domino 54-63

7. Select a Type: • Text • Number • Time • Boolean 8. For the field Special, do one: • Choose Simple value, and then enter a Text value. • Choose Formula, and then click Keywords and Variables and copy a text formula. • Chose Unspecified to leave the value undefined. To create a new variable 1. Perform Steps 1 through 5 in the procedure above. 2. In the Edit Variables dialog box, click New 3. In the Name field, enter a name for the variable. 4. Complete the Type and Special fields.

Creating plan notification messages
Resource documents define the standard messages that are sent during the various phases of plan execution. The plan Resources are referenced by the Interface message definitions. They correspond to each step of the workflow, such as Approve, Prepare, or Commit. You can edit the text of any of the plan messages to customize them. To edit a resource document 1. Make sure that you have the Change Admin role. 2. From the Domino Administrator, click the Server - Analysis tab. 3. Click Domino Change Control, and then select the Setup - Resources view. 4. Select the Standard Plan Message resource, and then click Edit. 5. Under Content body, make changes to the message text. 6. Click OK to save and close the document.

54-64 Administering the Domino System, Volume 2

Chapter 55 Transaction Logging and Recovery
This chapter explains how to set up and use database transaction logging and how to take advantage of fault-recovery strategies.

Transaction logging
Domino supports transaction logging for servers that run Domino 5 and later, and for databases that are in a Domino 5 or later on-disk structure. Transaction logging captures all the changes made to a database and writes them to a transaction log. The logged transactions are then written to disk in a batch, either when resources are available or when scheduled. A transaction is a related series of changes made to a database on a server. For example, opening a new document, adding text, and saving the document is one transaction. In this case, the transaction consists of three separate implicit API calls: NotesOpen, NoteUpdate, and NoteClose. A transaction log is a record of changes made to Notes databases. The transaction log consists of log extents and the log control file (NLOGCTRL.LFH). A log extent is one of the log files into which the transaction logs are written. It has the form Sxxxxxxx.TXN, where x character represents a seven-digit number that is unique to that server. Domino fills each extent sequentially before writing data to a new one. The records are secured using a proprietary byte-stream format. Each server has only one transaction log that captures all the changes to databases that are enabled for transaction logging. Use transaction logging to: • Schedule regular backups. Backups based on transaction logs are faster and easier than full database backups that do not use transaction logging. Recover from a media failure. If you have a media failure, you can restore the most recent full backup from tape, then use the transaction logs to add the data that was not written to disk.

Monitoring

55-1

Recover from a system crash. When the server restarts, it runs through the end of the transaction logs and recovers any writes that were not made to disk at the time of the crash. Logged databases do not require a consistency check. Log the database views. You can avoid most view rebuilds.

To use all the features of transaction logging for backups and backup recovery, you need a third-party backup utility that uses the backup and recovery methods of the Domino C API Toolkit (Release 5 or later). For example, in the case of a media recovery, a database backup is taken with the third-party utility, while logging keeps track of updates to the database. When the database is then lost, the backup is brought up to current state by going through the transaction log and applying any updates which have happened to that databases since the database backup was taken. Note that restart recovery does not require a third-party utility. In this case, logging goes on while updates are happening. When the server crashes then restarts, any updates which would have otherwise been lost are written to the database. This significantly reduces lost data and database corruption because of server crashes, and reduces overall restart time since the consistency check of databases is not required.

Understanding the database instance ID (DBIID)
When you enable transaction logging, Domino assigns a unique database instance ID (DBIID) to each Domino database. When Domino records a transaction in the log, it includes this DBIID. During recovery, Domino uses the DBIID to match transactions to databases. Some database maintenance activities, such as using the Compact command with options, cause Domino to reconstruct the database in such a way that old transaction log records are no longer valid. When this happens, a new DBIID is assigned to the database. From that point on, all new transactions recorded in the log for that database use the new DBIID. After a database is assigned a new DBIID, take a new full backup of the database. The new full backup captures the database in its current state with the new DBIID. Then, if you have to restore the database, Domino needs only the new transactions that contain the new DBIID. Domino assigns a new DBIID when: • • • • You enable transaction logging for the first time. You run the Compact task with an option — for example, the option to reduce file size. You run the Fixup task on corrupted databases. You move a Domino database to a logged server.

55-2 Administering the Domino System, Volume 2

How transaction logging works
Following is a general example of transaction logging from both the administrator’s and the employees’ points of view. The administrator enables transaction logging for all the databases on the servers. The administrator chooses the Archived logging style so that there is plenty of room for the transaction logs; uses a separate, mirrored device for safe and speedy storage of the transaction logs; and installs a backup utility to recover from media failures and any resulting corrupted databases. The administrator backs up the transaction logs daily. This procedure doesn’t take long because the administrator is backing up only the changes, rather than doing a full backup of all the databases on the server. When the server crashes, it’s down, but not for long. As the administrator restarts the server, it replays all the changes from the transaction logs to the databases. The server is soon back in business.

Monitoring

A few days later, there’s a media failure. The administrator restores the corrupted databases from the most recent weekly backup and replays the changes. The employees who use the databases do not notice any difference in how they do their work. They might notice, however, that servers are up and running more often and that there is less down time.

How changes are made to the database
Transaction logging posts all the database transactions to the log file, without waiting for the transaction to commit to disk. After being posted to the log file, the change is considered successful. The physical write process can wait until the server is less busy or occur at periodic intervals. The changes are written to disk in a batch. What happens between the time when the transaction is posted to the log file and when the database is updated on the disk? Databases are cached in memory while they are open. The writes to the database happen to the in-memory copy of the database. They are then immediately sent to the transaction logs. Later, the memory-cached version of the database is posted to disk, updating the databases. Since the transaction log is sequential, there is no seek time, and only enough information is written to the logs to redo (or undo if necessary) the operation. In many cases, this is less information than the database write to disk. If the database is not yet completely written to disk and you open it, you are opening the memory-cached version. If the server crashes before the version on disk has been updated with the changes, restarting the server applies the logs to the database during restart.
Transaction Logging and Recovery 55-3

Planning for transaction logging
Transaction logging captures all the changes that are made to databases and writes them to a transaction log. The logged transactions are written to disk in a batch when resources are available or at specified intervals. Use this checklist for your transaction logging planning. • Allocate space for the log files. Use a dedicated, mirrored device, such as RAID level 1 with a dedicated controller for optimal performance and data integrity. Plan a backup strategy. Plan to archive the transaction logs daily using incremental backups. Schedule weekly full database backups. You will then be prepared if you have a media failure. Decide which servers and databases will use transaction logging. Transaction logging is available for servers running Domino 5 and later. Consider enabling transaction logging for all databases on the server. Select a Domino-compatible backup utility. The utility must be able to use the backup and recovery methods of the Domino C API Toolkit (Release 5 or later). Choose the logging style that fits your needs. Logging styles include archived, circular, and linear. Set up a Domino server for transaction logging.

• •

Comparing transaction logging styles
There are three logging styles to choose from — circular, linear, and archived. The logging style you choose is also dependent on your disk size and backup strategy. With circular logging, Domino reuses a fixed amount of disk space (up to 4GB) for transaction logs. After the disk space is used up, Domino starts overwriting old transactions, starting with the oldest. When the space fills up, perform a backup on the databases. You may need to do daily backups to capture database changes before they are overwritten, depending on the server activity level. Use circular logging if the size of the log needed between full database backup intervals is less than 4GB. Linear logging is like circular logging, except it allows more than 4GB. Use linear logging if the size of the log needed between full database backup intervals is greater than 4GB, and you are not using archive media.

55-4 Administering the Domino System, Volume 2

Archived logging creates log files as needed. It simplifies backup and restoration, and provides online and partial backups. The log files are not overwritten until you archive them. With archived logging, you must have a backup utility to back up the filled log extents so that they are ready if needed. If you do not have a backup utility, the server continues to create log extents, fills up the disk space, and then panics.

Setting up a Domino server for transaction logging
You can enable and set up transaction logging on any server. 1. Make sure that all the databases you want to log are in the Domino data directory, either at the root, or in a subdirectory. 2. From the Domino Administrator, click the Configuration tab, expand the Server section, and click “All Server Documents.” 3. Select the Server Document for the Domino server you want to edit and then click Edit Server. 4. Click the Transactional Logging tab, complete these fields, and then save the document:
Field Transactional Logging* Action Choose one: • Enabled — To start transaction logging • Disabled (default) — To not use transaction logging Enter the path name location of the transaction log. For best results, use a separate mirrored device, such as a RAID (Redundant Array of Independent Disks) level 0 or 1 device with a dedicated controller. This provides better performance and data integrity than using the default path (\LOGDIR) in the Domino data directory. Note If the device is used solely for storing the transaction log, set the “Use all available space on log device” field to Yes. Use all available space on log device For circular and linear logging only. Choose one: • Yes — To use all available space on the device for the transaction log. Choose Yes if you use a separate device dedicated to storing the log. • No — To use the default or specified value in the “Maximum log space” field. continued

Monitoring

Log path*

Transaction Logging and Recovery 55-5

Field

Action

Maximum log space For circular and linear logging only. The maximum size, in MB, for the transaction log. Default is 192MB. Maximum is 4096MB (4GB). Allocate a separate disk with at least 1024MB (1GB) of disk space for the transaction log. Domino formats at least 3 and up to 64 log files, depending on the maximum log space you allocate. Automatic fixup of corrupt databases Choose one: • Enabled (default) — To run the Fixup task automatically if a database is corrupted and Domino cannot use the transaction log to recover it. Domino assigns a new DBIID and notifies the administrator that a new database backup is required. • Disabled — To not run the Fixup task automatically. Domino notifies the administrator to run the Fixup task with the -J parameter on corrupted logged databases. Runtime/Restart performance This field controls how often Domino records a recovery checkpoint in the transaction log. This affects server performance as databases may be flushed from the cache to disk. To record a recovery checkpoint, Domino evaluates each active logged database to determine how many transactions would be necessary to recover each database after a system failure. When Domino completes this evaluation, it: • Creates a recovery checkpoint record in the transaction log that lists each open database and the starting point transaction needed for recovery • Forces database changes to be saved to disk if they have not been saved already Choose one: • Standard (default and recommended) — To record checkpoints regularly. • Favor runtime — To record fewer checkpoints. This option requires fewer system resources and improves server run-time performance but causes more of the log to be applied during restart. • Favor restart recovery time — To record more checkpoints. This option improves restart recovery time because fewer transactions are required for recovery. continued

55-6 Administering the Domino System, Volume 2

Field Logging style**

Action Choose one: • Circular (default) — To re-use the log files and overwrite old transactions. • Archived (recommended) — To re-use the log files after they are archived. A log file can be reused when it is inactive, which means that it does not contain any transactions necessary for a restart recovery. Use a third-party backup utility to copy and archive the existing log. When Domino using the existing file again to Start, Domino increments the log file name. If all the log files become inactive and are not archived, Domino creates additional log files. • Linear — To re-use the log files and overwrite old transactions for log size greater than 4GB.

* If you change this field, you must restart the server so that the change takes effect. ** If you change this field, Domino assigns a new DBIID to each database. You must restart the server and perform another full backup.

Monitoring

Changing transaction logging settings
You can change the transaction logging settings. 1. Perform a full backup of all databases. 2. Open the Domino Administrator, click the Configuration tab, and open the Server document. 3. Click Edit Server. 4. Click the Transactional Logging tab and change the fields you want, taking into consideration the issues in the following table: For more information on the fields, see the topic “Setting up a Domino server for transaction logging” earlier in this chapter.
Field Transactional Logging Issue Consider carefully before you disable transaction logging. If you do not use transaction logging, you should back up your databases daily. You will also need Fixup to recover from media failure. When you restart the server, Domino runs restart recovery a final time to ensure that all databases are consistent. Then it disables transaction logging. continued Transaction Logging and Recovery 55-7

Field Log path

Issue If you edit the log path, save this document, then you must stop the server and use the operating system to move the existing log files to the new path. If you change only this field, you do not need to restart the server. As Domino logs the transactions, the changes take effect. If you change the logging style, you must perform a full backup of all databases because Domino assigns new DBIIDs to all the databases.

Use all available space on log device Logging style

5. Click Save & Close. 6. Restart the server so that the settings take effect.

Disabling transaction logging for a specific database
After you set up transaction logging on a server, Domino logs all databases on that server. You can disable transaction logging of specific databases, but this practice is not recommended because if unlogged databases are corrupted during a system or media failure, you must run the Fixup task to recover the database.

To disable transaction logging for a specific database
1. Do one of the following to choose “Disable transaction logging”: • If you are creating a new database, use the Advanced Database Options dialog box. • If you are working in an existing database, use the Advanced tab of the Database Properties box. • In the Domino Administrator, select a database on the Files tab, choose Tools - Database - Advanced Properties. 2. Be sure that all users have closed the database. 3. Use the Dbcache command with the flush parameter to close the database in the database cache. 4. Open the database.

To reenable transaction logging for a specific database
Follow the steps above, but de-select “Disable transaction logging.”

55-8 Administering the Domino System, Volume 2

View logging
View logging provides a way to maintain consistent views in failure conditions and allows media recovery to update those views. View logging is transaction logging support for Notes views and folders. All updates to Notes views or folders are recorded in the transaction log for recovery purposes. To enable view logging, you use Domino Designer. In Designer, open a view or folder, select the Advanced tab, and check “Logging - Include updates in transaction log.” Note If you enable view logging in a template, all databases created from that template and all databases whose designs are replaced from that template have those views logged.

Using transaction logging for recovery Monitoring
Transaction logging is an integral part of recovering from system and media failures. Using transaction logging provides insurance against system failure, but creating regular backups is essential so that you can recover data after a failure.

System failure recovery
A system failure causes the server to stop and requires you to restart the server. During restart, Domino automatically performs database recovery. The system uses the transaction logs to apply full transactions and undo partial transactions that were not written to disk for databases that were open during the system failure. Domino runs the Fixup task for: • • • Databases in formats that are earlier than Domino 5 Databases that are in Domino 5 format but have transaction logging disabled Corrupted databases, if you choose Yes for “Auto fixup of corrupt databases” in the Server document.

When you restart a server after a system failure, Domino automatically restores the affected databases.

Transaction Logging and Recovery 55-9

Media failure recovery
A media failure causes databases to be damaged or lost. To recover, you use the third-party backup utility to restore database backups and transactions from the transaction log files. The backup utility you choose must use the backup and recovery methods of the Domino C API Toolkit (Release 5 or later). For information on recovering after a media failure, see the documentation included with your backup utility.

Fault recovery
You can set up fault recovery to automatically handle server crashes. When the server crashes, it shuts itself down and then restarts automatically, without any administrator intervention. A fatal error such as an operating system exception or an internal panic terminates each Domino process and releases all associated resources. The startup script detects the situation and restarts the server. If you are using multiple server partitions and a failure occurs in a single partition, only that partition is terminated and restarted. Domino records crash information in the data directory. When the server restarts, Domino checks to see if it is restarting after a crash. If it is, an e-mail is sent automatically to the person or group in the “Mail Crash Notification to” field. The e-mail contains the time of the crash, the server name, and, if available, the FAULT_RECOVERY.ATT file, which includes additional failure information from an optional cleanup script, will be attached. The fault-recovery system is initialized before the Domino Directory can be read. During this initialization, fault-recovery settings are read from the NOTES.INI file, and then later read from the Domino Directory and saved back to the NOTES.INI file. Any changes to the Domino Directory or the NOTES.INI file become effective when the Domino server is restarted. To disable the reading of the Domino Directory, and subsequent update to the NOTES.INI file, use the NOTES.INI setting FaultRecoveryFromIni=1.

Operating systems and fault recovery
Because fault recovery runs after an exception has occurred, it cannot rely on Domino’s internal facilities. Instead, fault recovery makes heavy use of operating system features. UNIX systems primarily use message queues. Therefore, it is important to configure the operating system so that sufficient message queue
55-10 Administering the Domino System, Volume 2

resources are available. If you are using multiple Domino server partitions, each partition requires a complete set of resources. Consult your operating system documentation for additional details on configuring message queue parameters. Windows NT and Windows 2000 systems do not require any system resource changes.

Specifying a cleanup script for fault recovery
You can create an optional script that runs before any other cleanup takes place. Use the file FAULT_RECOVERY.ATT to collect the information from the script. 1. From the Domino Administrator, click the Configuration tab, and expand the Server section. 2. Open the Server document, click Edit document, and click the Basics tab. 3. Complete these fields:
Field Cleanup Script Name Action Enter the entire script name, including any extensions. Note Directory separators (slashes) in the file name portion are converted for the operating system, but slashes in optional arguments are not converted. Enter the number of seconds for the cleanup script to run. Default is 300 seconds (5 minutes). Maximum is 1800 seconds.

Monitoring

Cleanup Script Maximum Execution Time

Maximum Crash Enter the number of restarts allowed during a specified Limits time limit — for example, 3 crashes within 5 minutes. If the number of crashes exceeds the time limit, the server exits without restarting. Mail Crash Notification to Enter a user or group name. When the server restarts, Domino checks if it is restarting after a crash and sends e-mail to the person or group.

Enabling fault recovery
1. From the Domino Administrator, click the Configuration tab, and expand the Server section. 2. Open the Server document, click Edit document, and click the Basics tab. 3. Check “Fault Recovery Enabled.”

Transaction Logging and Recovery 55-11

Chapter 56 Using Log Files
This chapter describes how to use the Domino server log (LOG.NSF) and the Domino Web server log (DOMLOG.NSF) to collect information about the Domino system.

The Domino server log (LOG.NSF)
Every Domino server has a log file (LOG.NSF) that reports all server activity and provides detailed information about databases and users on the server. The log file is created automatically when you start a server for the first time. You can do the following: • • • • Control the size of the log file Record additional information in the log file View the log file Search the log file

Monitoring

Controlling the size of the log file (LOG.NSF)
By default, the log file (LOG.NSF) records information about the Domino system. Because the log file can become quite large, it is important to manage its size. You can control the size of the log file automatically, using NOTES.INI settings, user preferences, and other settings. For example, the Log setting in the NOTES.INI file determines how long documents are maintained before being deleted from the log file. By default, documents are deleted after 7 days. If you are troubleshooting a system problem, you may want to record additional information in the log file. The log file becomes large quickly when you set a higher logging level for purposes of analyzing a system problem. For example, if you are troubleshooting a mail routing problem, you can set the logging level to verbose. When you do, the log file will contain a large amount of information regarding that activity. If you set a high logging level during troubleshooting, remember to reset the logging level after you solve the problem.

56-1

For more information on NOTES.INI settings, see the appendix “NOTES.INI File.” For more information on setting additional logging levels, see the topic “Recording additional information in the log file,” later in this chapter.

NOTES.INI settings for log files
The following table contains the NOTES.INI settings that determine what is reported in the log file and set size limitations. For more information on these settings, see the appendix “NOTES.INI File.”
Setting Log Log_AgentManager Description Specifies the contents of the log file and controls other logging actions. Specifies whether or not the start of agent execution is recorded in the log file and shown on the server console. Enforces logging of server console command output, which can otherwise be prevented if the command is prefixed with an exclamation point (!). Logs information about the Directory Catalog task to the Miscellaneous Events view of the log file (LOG.NSF). Specifies the level of logging of replication events performed by the current server. Specifies whether individual sessions are recorded in the log file and displayed on the console. Specifies whether the current status of server tasks is recorded in the log file and displayed on the console. Specifies the level of detail of Indexer events displayed at the server console and in the log file. Specifies whether messages generated when views are rebuilt are recorded in the log file.

Log_Console

Log_DirCat

Log_Replication Log_Sessions Log_Tasks

Log_Update Log_View_Events

Mail_Log_To_MiscEvents Determines whether all mail event messages are displayed in the Miscellaneous Events view of the log file.

56-2 Administering the Domino System, Volume 2

Recording additional information in the log file
In addition to controlling the size of the log file using NOTES.INI settings, you can use the following settings, fields, and commands to specify additional information and establish logging levels for the log file.
To record information about Mail routing Setting, field, or command “Logging level” field on the Router/SMTP Advanced - Controls tab of the Configuration Settings document. File - Preferences - User Preferences - Ports COMx - Trace File - Tools - Preferences - Notes Preferences Ports - COMx - Trace - Options Set a com port option in the Port Setup dialog box.

Modem I/O Modem script I/0 Traced network connections Web Navigator Web server

Monitoring

The “Retriever log level” field on the Server Tasks - Web Retriever tab of the Server document. Additional information regarding the Web server is logged in the Domino Web server log (DOMLOG.NSF).

For more information on the Domino Web server log, see the topic “Viewing the Domino Web server log (DOMLOG.NSF)” later in this chapter.

Viewing the log file (LOG.NSF)
You can also use the Web Administrator to open the log (LOG.NSF). 1. From the Domino Administrator, click the Server - Analysis tab. 2. Select the server that stores the log file you want to view. 3. Click Notes Log. 4. Click the desired view. 5. Open the desired document. Tip You can also view the search results from the Server - Analysis tab using the tool Analyze - View Log Document. This tool gives you more details about the messages in the current log document and allows you to sort the messages in several different ways. Doing this makes it easier find the information you are looking for and to see patterns of server activity.

Using Log Files 56-3

Views in the log file (LOG.NSF)
View Contains information about Size and activity of all databases on the server Percentage of each database’s disk space that is in use Total disk space of each database Weekly usage of the database Populated by the nightly Statistics Log task Sessions (including K transferred) Documents read and written Replications Sorted by database Populated by the nightly Statistics Log task Database - Sizes • • • • • Database Usage • • • • •

Mail Routing Events Miscellaneous Events

• Mail routing details not available in the Miscellaneous Events view • • • • • • • • • • • Events that do not appear in other views Modem I/O messages Script I/O messages Server task messages Sorted by date Object store file name Mail database file name Mail database title Number of documents referenced in the object store Total size of the documents in the object store Details on the shared mail object store usage on your server

Object Store Usage

Passthru Connections Phone Calls By Date Phone Calls By User Replication Events

• Starting and Ending times, destination, and protocol for each passthru connection • Information about calls made and received by a server, sorted by date or by user

• All replication sessions between servers, sorted by server • Information includes the name of the initiating server, time and duration of replication, port used, and the number of documents added, deleted, or modified • Uncategorized billing information provided in the Usage by Date and Usage by User views, sorted by user and including totals for each column and session continued

Sample Billing

56-4 Administering the Domino System, Volume 2

View Usage by Date Usage by User

Contains information about • Sessions this server had with users or other servers, sorted by date or by user • Information includes: sessions opened; session duration; databases opened; database-access duration; number of transactions (workstation-to-server database requests); and network usage (K transferred) • Transactions for operations, such as opening a document, updating a document, reading a section of a view, and going to a specific section of a view • Includes totals by date, by user/server, and for all usage

Search Results

• Results of log analysis • Information includes starting time and name of server

Searching the log file (LOG.NSF)
The log file (LOG.NSF) contains a wealth of information for the Domino Administrator. However, if you are troubleshooting a problem, searching through all of the information can be time consuming. Using the Log Analysis tool, you can search the log file for specific events, event severities, or for specific words, and you can specify the dates you want to search. For example, if you are troubleshooting a mail routing problem, you can search for routing events with an event severity of warning or failure, that occurred during the time you were experiencing difficulties. Some advanced queries can be made on Domino 6 servers only, and then only if the Event task is running on them. When you perform a log analysis, the search results display automatically and are also saved in the Search Results view of the log file (LOG.NSF). They include the following types of information: • • • • • Status of the event, displayed as an icon Type of event Severity of the event Time the event occurred A description of the event

Monitoring

To search the log file 1. From the Domino Administrator, click the Server - Analysis tab. 2. Click Analyze, and then click Log. 3. In the Log Analysis dialog box, create a search query by specifying the search criteria.
Using Log Files 56-5

Note You can select more than one when specifying search criteria. For example, you can select more than one event type, then you must select one of these options: • The results must match one of the criteria — select this option if the results must match the selected criteria, such as event type, or event severity. • The results can match one of the criteria — select this option if results that do not match the selected criteria can be included in the log search as well.
Search criteria Date Complete the following Start and End Date — Select the dates you want to search. Start and End Time — Select the times you want to search. Select one: • Use above time range in any time zone — Use this setting when you do not need to vary the search start and end parameters. • Convert time range to server’s time zone — Use this setting if you are searching the log file for a server in a different time zone. • Any time — Use this setting if you do not want to limit the log search by date or time. Event Type Select the type of event for which you want to search. Event Severity Select the type of severity for which you want to search. Add-in Name Select the add-in name for which you want to search. Add Add-in Name — Enter the name of an add-in task if you do not find it on the list. Error Code Event Text Click in the column to the left of a message to select the error message for which you want to search. Do any of the following to refine your text. • Look for — Choose one of these: any of the words all the words exact phrase • Enter — Enter the words or phrases for which you want to search. • Must Contain the Words — Enter the words that the log search must contain to be successful. • Must Not Contain the Words — Enter the words or phrases that would make a search result invalid. continued 56-6 Administering the Domino System, Volume 2

Search criteria Queries

Complete the following Select Existing Query — Choose any predefined query. Save query on exit — Select this option if you want to save your query criteria. Save Query As — Enter a name for your query. Query Formula — Displays the new or selected query for your verification.

4. When you click OK, the Log Analysis Results are displayed and a copy of the results is stored in the Search Results view of the log file. Tip Search strings can be any length containing any type of character and the search is not case sensitive. To view a search result 1. Open the log file (LOG.NSF). 2. Select the Search Results view. 3. Results are listed by starting time and server name. Select the results you want to view. 4. Use File - Open or double-click to open the search results document. Tip You can also view the search results from the Server - Analysis tab using the tool Analyze - View Search Results, which gives you additional sorting abilities when viewing the results. Analyzing Domino 6 log files using a Domino 5 server If you have a mixed environment in which you are using a Domino 6 Administration client and a server that is Domino 5 or earlier, the log analysis is based on the Domino 5 Log Analysis functionality, and the results are saved in the Results database (RESULTS.NSF). The Results database is based on the LOGA4.NTF template. It shows the date and time of events, their source (event or console message), and the text of messages. The view doesn’t display times for server console messages. If you are using a Lotus Domino Administrator 6 client to analyze a Domino 6 server log file, you can still create a Results database and save the results to this database. To do so, open the document from the Search Results view in LOG.NSF, then use the File - Save As menu to save it to the desired location. For more information about the Results database, see the Domino 5 documentation.

Monitoring

Using Log Files 56-7

Logging Domino Web server requests
You can log Domino Web server requests to a database or to text files. • • Text files — Text files are smaller and can be used with third-party analysis tools. Domino Web Server Log (DOMLOG.NSF) — Logging to a database allows you to create views and view data in different ways. However, the size of the database can become large so that maintenance becomes an issue.

Note You can log to both text files and a database. These options are not mutually exclusive.

The Domino Web server log (DOMLOG.NSF)
You can log your server activity and Web server requests to the Domino Web server log (DOMLOG.NSF) database. This option may be preferable if you want to create views and view data in different ways. Logging to a database is somewhat slower than logging to text files, especially at very busy sites, and the size of the database can become large so that maintenance becomes an issue. However, if you use the Domino Web server log, you can treat this information as you would other Notes databases, and you can use built-in features to analyze the results. The Domino Web server log (DOMLOG.NSF) logs all Domino Web server activity and tracks this information about each HTTP request: • • • • • • • Date and time the request was made User’s IP address (or the DNS address if DNS lookup is enabled in the Server document) User’s name (if the user supplied a name and password to access the server) Status code the server returns to the browser to indicate its success or failure in generating the request Length of the information, in bytes, sent from the server to the browser Type of data accessed by the user — for example, text/html or image/gif HTTP request sent to the server from the browser

56-8 Administering the Domino System, Volume 2

• • • • • • •

Type of browser used to access the server Internal and Common Gateway Interface (CGI) program errors URL the user visited to gain access to a page on this site Server’s IP address or DNS name Amount of time, in milliseconds, to process the request Cookies sent from the browser Translated URL (the full path of the actual server resource, if available)

Setting up the Domino Web server log (DOMLOG.NSF)
To set up the Domino Web server log, you must enable logging (by default, logging is disabled). You can restrict the information logged to the Domino Web server log to analyze log file results. Some information may increase the size of the log file without providing meaningful information — requests for graphics or icons, for example, so you may want to exclude that type of information from the log. Domino creates the Web server log database when the HTTP task starts after you enable logging to DOMLOG.NSF. To enable logging to the Domino Web server log 1. From the Domino Administrator, click the Configuration tab. 2. Open the Server document for the Web server. 3. Click the Internet Protocols - HTTP tab. 4. Under “Enable Logging To,” choose Enabled in the DOMLOG.NSF field. 5. (Optional) Under “Exclude From Logging,” complete these fields to exclude certain types of information from the log file:
Field URLs Methods MIME types User agents Enter URL paths to exclude — for example, *.gif or /anydir/* HTTP methods — for example POST or DELETE MIME types to exclude — for example, image (for all images) or image/gif (for .gif images) Strings that are part of user agent (browser) strings to exclude requests from a particular user agent. • To exclude Microsoft Internet Explorer, enter MSIE* • To exclude Netscape: For version 4.7, enter Mozilla/4.7 For version 4.6, enter Mozilla/4.6 continued Using Log Files 56-9

Monitoring

Field Return codes Hosts and domains

Enter HTTP response status codes to exclude — for example, 300 or 400 Browser client DNS names or IP addresses to exclude — for example, 130.333.* or *.edu Note To enter DNS names in this field, you must first enable the DNS Lookup setting in the HTTP Server section of the Server document. Otherwise, you can enter only IP addresses in this field. Enabling this setting will impact performance.

6. Save the document and then restart the HTTP task so that the changes take effect.

Viewing the Domino Web server log (DOMLOG.NSF)
1. From the Domino Administrator, click the Files tab. 2. Open the Domino Web server database (DOMLOG.NSF). 3. Click Requests to display request documents, and then click a request document to display its content.

Domino Web server logging to text files
When setting up Domino Web server logging to text files, you must determine the Access file format. The content of the Access log varies depending on which log file format you choose: • • Extended Common Common

The most commonly used Access log format is Extended Common, which logs all Web server information into a single text file. Optionally, you can choose Common for the Access log file format; however, the Common format is an older log file format and is available primarily for legacy information. If you choose the Common format for your Access file, it contains a subset of the server request information, with the requesting agent and referer information stored in separate Agent and Referer log files. It is difficult to match the entries in these different log files because a referer is not always sent with every request, so the number of referer entries may not match the number of requests.

56-10 Administering the Domino System, Volume 2

When you log to a text file, the following information is recorded:
Text file Access Records Depending on the file format you choose, the Access log file records the following Web server request information in the order shown: Common 1. Client DNS name or IP address if DNS name is not available 2. Host header from request, or server IP address if Host header is not available 3. Remote user if available 4. Request time stamp 5. Http request line 6. Http response status code Extended Common 1. Client DNS name or IP address if DNS name is not available 2. Host header from request, or server IP address if Host header is not available 3. Remote user if available 4. Request time stamp 5. Http request line 6. Http response status code 7. Request content length if available, otherwise shows “-” 8. Referring URL if available, otherwise shows “-” 9. User agent if available, otherwise shows “-” 10. Amount of time, in milliseconds, to process the request 11. Value of the cookie header 12. Translated URL, (the full path of the actual server resource, if available) Agent Referer User agent if available, otherwise shows “-” URL the user visited to gain access to a page on this site

Monitoring

Using Log Files 56-11

CGI Error file
Standard errors (stderr) from CGI programs are captured in the CGI Error file, regardless of which text file format you set up.

Setting up Domino Web server logging to text files
To set up logging the Domino Web server to text files, you must enable logging (by default, logging is disabled). By default, Domino stores log files in the data directory. While the Web server is running, it creates new log files depending on the log file duration settings. If the Web server is not running, it creates log files as needed when the Web server is started. Some information may increase the size of the log file without providing meaningful information — requests for graphics or icons, for example, so you may want to exclude that type of information from the log. To enable logging to text files 1. From the Domino Administrator, click the Configuration tab. 2. Open the Server document for the Web server. 3. Click the Internet Protocols - HTTP tab. 4. Under “Enable Logging To,” choose Enabled the Log Files field. 5. Under “Log File Settings,” complete these fields:
Field Access log format Enter Choose one: • Common — To log information in three separate log files • Extended Common — To log information in one file Note Although you have the option of logging to three separate files, most third-party log-analysis tools require a single text file. Time format Choose one to record the time of requests: • LocalTime (default) — To use the time zone currently set on the server • GMT— To use Greenwich Mean Time continued

56-12 Administering the Domino System, Volume 2

Field

Enter

Log file duration Choose one to determine how often a new log file is created: Note The prefixes used in the file names are chosen in the Log File Names section of the Server document. • Daily (default) — To create a new log file each day, starting at midnight. Daily log files use the file naming convention:
file name prefixDDMMYYYY.log

Example: The access log file for May 29, 2001 is access-log29051998.log • Weekly — To create a new log file each week, starting on Sunday at midnight. Weekly log files use the file naming convention:
file name prefix__WWYYYY.log

Example: The access log for the week of May 24, 2001 is access-log__212001.log. • Monthly — To create a new log file each month, starting at midnight on the first day of the month. Monthly log files use the file naming convention:
file name prefix—MMYYYY.log

Monitoring

Example: The access log file for May 2001 is access-log—052001.log. • Never — To create log files of unlimited duration. The file naming convention is:
file name prefix.log

Example: The CGI error log file is cgi-error-log.log. Maximum log entry length The maximum length allowed for an individual entry in the access log file. If the entry exceeds this length it is not written to the file. The default is 10 kilobytes.

Maximum size of The maximum size allowed for the access log file. If this access log limit is reached no more entries are written to the file. A value of zero (the default) indicates that the size is unlimited.

6. Under “Log File Names,” complete these fields:
Field Enter Directory for log The directory to store the log files; if this field is blank, files Domino stores the log files in the data directory Access log The prefix to use when creating the Access log file. The default is access. Do not enter a file extension. continued

Using Log Files 56-13

Field Agent log

Enter The prefix to use when creating the Agent log file. The default is agent. Note If you chose the Extended Common format, you will not have an agent log; this information will be included in the access log.

Referer log

The prefix to use when creating the Referer log file. The default is referer. Note If you chose the Extended Common format, you will not have a referer log; this information will be included in the access log. The prefix to use for the CGI error log. The default is cgi-error. Note The cgi-error log is created only if the CGI script logs information to stderr. The format of cgi-error log information is CGI script dependent. The Access log format does not affect the cgi-error log in any way.

CGI error log

7. (Optional) Under “Exclude From Logging,” complete these fields to exclude certain types of information from the log file:
Field URLs Methods MIME types User agents Action Enter URL paths to exclude — for example, *.gif or /anydir/* Enter HTTP methods — for example, POST or DELETE Enter MIME types to exclude — for example, image (for all images) or image/gif (for .gif images) Enter strings that are part of user agent (browser) strings to exclude requests from a particular user agent. • To exclude Microsoft Internet Explorer, enter MSIE* • To exclude Netscape: For version 4.7, enter Mozilla/4.7 For version 4.6, enter Mozilla/4.6 Return codes Hosts and domains Enter HTTP response status codes to exclude — for example, 300 or 400 Enter browser client DNS names or IP addresses to exclude — for example, 130.333.* or *.edu Note To enter DNS names, you must first enable the DNS Lookup setting in the HTTP Server section of the Server document. Otherwise, you can enter only IP addresses. Enabling this setting impacts performance.

8. Save the document.

56-14 Administering the Domino System, Volume 2

Chapter 57 Setting Up Activity Logging
This chapter describes how to set up and use the Lotus Domino 6 activity logging feature.

Activity logging
You use activity logging to collect information about the activity in your enterprise. You can use this information to charge users for the amount they use your system, monitor usage, conduct resource planning, and determine if clustering would improve the efficiency of your system. Domino writes the activity logging information in the Domino log file (LOG.NSF). To create activity logging reports, you write a Notes API program to access the information in the log file. You can also view the activity logging information by using Activity Analysis. In a hosted environment, enable activity logging on all of your ASP servers, that is, the servers used to house and maintain your hosted organizations.

Monitoring

The information in the log file
Domino logs activity in the log file (LOG.NSF). The information is not visible in the log file, but you can access the information in the file by writing an API program. For information about writing an API program to access this information, see the Lotus C API Toolkit for Notes/Domino 6. The toolkit is available for download at http://www.lotus.com/ldd. Note Activity logging records in the log file are hidden. The records you can see in the log file do not contain as much detail as activity logging records and are not updated as often as activity logging records. You can view activity logging information by running Activity Analysis.

57-1

You use the Domino Administrator to specify which types of activity to log. This table describes the types of activity you can log.
Activity type What this logs Agent HTTP IMAP LDAP When a Domino server runs scheduled agents, as well as the running time of the agents Web server requests Activity generated during an IMAP session Activity generated by all LDAP activity. Each type of LDAP activity generates a separate record. The types of LDAP activity include abandon, add, bind, compare, delete, extended, modify, modify distinguished name, search, and unbind. Activity generated by mail and mail-related messages being routed to and from the server. The messages can come from a Domino server or an SMTP server. When Notes clients and Domino servers open, use, and close Notes databases and the duration of use. When users or servers connect through a Domino passthru connection, as well as the activity that is generated through that connection When Notes clients and Domino servers acting as clients start and end sessions with a Domino server Activity generated during a POP3 session Activity generated by replication with another server or with a client Activity generated during an SMTP session

Mail

Notes Database Notes Passthru Notes Session POP3 Replica SMTP

Activity logging records
The records in the log file keep track of all activity generated. Domino creates different types of records for each type of activity. For some types of activity, Domino creates multiple records during a session; for other types of activity, Domino creates a single record. Checkpoint records For types of activity that could require long sessions to complete, Domino generates an Open or Authorization record when a session begins. This record indicates that a session is open and shows the time at which the session began. During the session, Domino generates Checkpoint records, which log all activity that has occurred so far during the session. Checkpoint records ensure that activity is logged even if a server stops functioning before a session ends. When a session ends, Domino generates a Close record, which consolidates all the activity for the entire session.
57-2 Administering the Domino System, Volume 2

Domino creates Checkpoint records for the following types of activity: IMAP, Notes session, Notes database, Notes passthru, POP3, and SMTP. The Checkpoint records are cumulative; each one contains all of the activity that was logged to that point during the open session. By default, Domino creates a Checkpoint record the first time there is activity after a 15 minute waiting period, and every 15 minutes when there is activity thereafter. This waiting period is called the checkpoint interval. Domino generates a Checkpoint record the first time activity occurs after the checkpoint interval has completed. For example, if several transactions occur during the first 10 minutes of the checkpoint interval but no more activity occurs until minute 21, Domino generates the Checkpoint record in minute 21. For each type of activity for which there is an open session, Domino creates only one Checkpoint record per period, no matter how much activity occurs. To change the duration of the checkpoint interval, you can change the “Checkpoint interval” setting on the Activity Logging tab of the Configuration Settings document. To determine how long to make the checkpoint interval, consider three factors: the need to record information, the need to preserve storage space, and the need for quick performance. The longer you make the checkpoint interval, the more activity data that could be lost if the server crashes before Domino writes the Checkpoint records. The shorter you make the checkpoint interval, the more Checkpoint records that could be created, requiring more storage space. In addition, if you set a short checkpoint interval, system performance could be affected if there is a lot of activity. Note For types of activity that generate multiple activity logging records, the record type is indicated in the EventType field in the record.

Monitoring

Agent activity logging
Agent activity logging generates a record for each Domino server-based agent that runs successfully. The record shows the name of the agent, the name of the database that contains the agent, the amount of time it took to run the agent, and the name of the person who last saved the agent. The record does not show the types of activities the agent performed. Domino does not generate activity logging records for agents that run on a Web server, for agents that you run manually from a client, or for agents that are scheduled to run locally on a client. For information about restricting who can run agents on a server, see the chapter “Controlling Access to Domino Servers.”

Setting Up Activity Logging 57-3

HTTP activity logging
HTTP activity logging tracks requests from browsers to access Domino Web servers. Domino generates an HTTP activity logging record each time a browser sends an HTTP request to a Domino Web server. For example, if a user opens a Web page that includes information from three separate files, Domino generates three separate activity logging records. HTTP activity logging records include such information as the name of the Web server, the name of the user accessing the Web server, the HTTP request, the URL the user clicked, the number of bytes returned as a result of the request, the amount of time it took to process the request, the HTTP status code returned as a result of the request, and the time at which the request occurred. In addition, if you have set URL translation rules in the Server Configuration document, the HTTP activity logging record shows the results of the translations.

IMAP activity logging
IMAP activity logging tracks IMAP session activity, such as the user name, the server name, the IP address of the client, the number of bytes the client sent to and read from the server, and the duration of the session. There are three types of activity logging records for IMAP sessions: • Authorization records, which log when an authenticated IMAP session begins. Authorization is logged after any of the following occur: a successful Login command; a successful Auth command; a successful Greeting command, if the client is preauthorized. Checkpoint records, which log activity that occurs when an IMAP session has been open for a specified length of time Close records, which consolidate IMAP information into a single record when an IMAP session ends

• •

LDAP activity logging
LDAP activity logging tracks information about every LDAP request. Because each type of LDAP request has a different structure, Domino generates a different activity logging record for each type.

57-4 Administering the Domino System, Volume 2

This table shows the types of LDAP requests and some of the information that Domino logs for each type of request. Domino does not generate Checkpoint records for LDAP requests.
Request type Information logged Abandon Organization name, user name, server name, client IP address, the message ID of the command to abandon, the LDAP result code, and any error messages returned to the client Organization name, user name, server name, client IP address, the distinguished name of the object to be added, the attributes that are added and their new values, the names of the directories to which the entry was added, the number of entries added, the number of bytes sent to the server, the LDAP result code, and any error messages returned to the client Organization name, user name, server name, client IP address, LDAP version, the name the client is using to bind, the authentication method, the LDAP result code, and any error messages returned to the client

Add

Bind

Monitoring

Compare

Organization name, user name, server name, client IP address, the distinguished name of the object that was compared, the attribute and value portions of the attribute value assertion, names of the directories searched, the number of bytes sent to the server in the query, the LDAP result code, and any error messages returned to the client Organization name, user name, server name, client IP address, the distinguished name of the object that was deleted, names of directories from which the object was deleted, the number of entries deleted, the number of bytes sent to the server, the LDAP result code, and any error messages returned to the client Organization name, user name, server name, client IP address, the name of the extended command, the LDAP result code, and any error messages returned to the client Organization name, user name, server name, client IP address, the distinguished name of the entry to be modified, the operations to be performed on the entry (add, delete, replace), the attributes that are modified and their new values, the names of the directories in which the entry was modified, the number of entries modified, the number of bytes sent to the server, the LDAP result code, and any error messages returned to the client

Delete

Extended

Modify

ModifyDN Organization name, user name, server name, client IP address, the directory entry that is modified, the new Relative Distinguished Name (RDN), whether the old RDN was deleted, the new parent entry, the names of the directories in which the entry was modified, the number of entries modified, the number of bytes sent to the server, the LDAP result code, and any error messages returned to the client continued Setting Up Activity Logging 57-5

Request type Information logged Search Organization name, user name, server name, client IP address, the base object, the scope of the search, deref aliases, the maximum number of entries the client requests, the time limit a client requests for a session, the types of information to include in a record (field names only or field names and values), filters, the attributes that you want displayed for each entry, the amount of time the search took, the names of the directories searched, the number of entries and the number of bytes sent to the client, the LDAP result code, and any error messages returned to the client Organization name, user name, server name, client IP address, the LDAP result code, and any error messages returned to the client

Unbind

You can customize the LDAP service configuration to limit the amount of data collected in the Values fields in Add and Modify records.

Mail activity logging
Mail activity logging tracks mail that is sent from and received by a server. Activity logging records for mail include such information as the name of the server that created the record, the originator and recipients of the message, the message ID, the preceding and next hops on the delivery route, and the size of the message. There are five types of activity logging records for mail activity:
Type of record Description Deposit Mail is deposited into MAIL.BOX on a server. This mail can come from a Domino server or a Domino SMTP server. The receiving server logs this activity as a Deposit. The sending server logs this activity as a Transfer. Mail is delivered from MAIL.BOX to a user. The router could not deliver a message. Mail is transferred from one server to another on the way to its final destination. The sending server logs this as a Transfer. The receiving server logs this as a Deposit. The router cannot transfer a message to another server. This is logged on the sending server.

Delivery Delivery failure Transfer

Transfer failure

For each mail message, at least two types of records are logged — a Deposit record and at least one of the other types of records, depending on the disposition of the attempted delivery.

57-6 Administering the Domino System, Volume 2

Domino logs updates to messages in MAIL.BOX as new deposits. For example, if you change the address on a message in MAIL.BOX so that it routes correctly, that message is logged as a new deposit. If a message is split because the recipient list is too large, a separate record is generated for each copy of the message. Each of these records contains the same MessageID and Originator.

Notes session activity logging
Notes session activity logging tracks network traffic that occurs during a server session with a Notes client or with another Domino server acting as a client. Session records include such information as the name and network address of the session user, the number of documents read and written, the number of bytes read and written, the total number of transactions executed during the session, and the duration of the session. Servers, users, and API programs can all generate session activity. There are three types of activity logging records for session activity: • • • Open records, which log when a session begins Checkpoint records, which log activity that occurs when a session has been open for a specified length of time Close records, which consolidate all session information into a single record when a session ends

Monitoring

This table contains a few examples of the types of activities that generate each type of session record.
Type of record Type of activity Open • Opening a database or any action that opens a database, such as checking database properties • Starting replication • Having a remote server open another server’s MAIL.BOX Checkpoint • • • • • • • • • • • Reading documents Editing documents Saving and updating documents Viewing or changing an ACL Rebuilding a database view Performing any other activity while a session is open Closing a database Ending replication Logging off, either manually or automatically Exiting Notes Having a remote server close MAIL.BOX Setting Up Activity Logging 57-7

Close

Notes database activity logging
Notes database activity logging tracks Notes database activity that occurs during a server session. Database records include such information as the name of the database, the name and address of the database user, the number of documents read and written, the number of bytes read and written, the total number of transactions executed in the database, and the length of time the database was open. Servers, users, and API programs can all generate database activity. There are five types of activity logging records for database activity: • • • • • Open records, which log when a database opens Checkpoint records, which log activity that occurs when a database has been open for a specified length of time Close records, which consolidate all log information for a database session into a single record when a database closes CloseEnd records, which consolidate database information at the end of a Notes session (when the client logs off of the server) MailDeposit records, which log when a mail message that does not contain an attachment is deposited into MAIL.BOX. (Mail messages that contain attachments generate Open records, Close records, and possibly Checkpoint records.)

This table contains a few examples of the types of activities that generate each type of database record.
Type of record Type of activity Open • Opening a database or any action that opens a database, such as checking database properties • Starting replication, including opening a database to determine if replication is needed (even if no replication is needed)* • Having a remote server open another server’s MAIL.BOX Checkpoint • • • • Editing documents Saving and updating documents Viewing or changing an ACL Performing any other database activity while a database is open continued

57-8 Administering the Domino System, Volume 2

Type of record Type of activity Close • Closing a database • Ending replication • Logging off, either manually or automatically (one record for each open database) • Exiting Notes (one record for each open database) • Having a remote server close MAIL.BOX CloseEnd Closing a database at the end of a session Closing databases that the server opened for replication Logging off of Notes Exiting Notes Depositing a mail message that does not contain an attachment into MAIL.BOX

MailDeposit

* When Domino closes databases after determining that replication is not necessary, it generates a Close record that contains 0 (zero) in the Duration field.

Monitoring

CloseEnd records log the total activity in a database during a Notes session. Each time a user opens and closes a database during a session, Domino creates separate database Open and Close records. When the user closes the Notes session, Domino generates a CloseEnd record for each database that was open during the session. The CloseEnd record consolidates the total activity in the database during the entire Notes session. Therefore, if you open and close a database several times during a Notes session, Domino generates multiple Open and Close records for that database, but only one CloseEnd record.

Notes passthru activity logging
Notes passthru activity logging tracks activity that is generated by a client or a server through a passthru connection. This includes such information as the number of bytes sent and received, the number of documents read and written, the number of transactions executed, and the duration of the passthru session. There are three types of activity logging records for passthru connections: • • • Open records, which log when a passthru connection begins Checkpoint records, which log activity that occurs when a passthru session has been open for a specified length of time Close records, which consolidate information into a single record when a passthru session ends, such as when a client logs off or disconnects from the passthru server
Setting Up Activity Logging 57-9

POP3 activity logging
POP3 activity logging tracks such POP3 information as the name of the user, the IP address of the client, the number of bytes the client sends to and reads from the server, the number of messages sent to the client, the number of messages deleted from the client, and the duration of the session. There are three types of activity logging records for POP3 activity: • • • Authorization records, which log when a user is authenticated and a session begins Checkpoint records, which log activity that occurs when a POP3 session has been open for a specified length of time Close records, which consolidate POP3 information into a single record when a POP3 session ends

If a session ends before authentication is complete, Domino generates only a Close record. The user name in this record is “Anonymous.”

Replication activity logging
When you use activity logging for replication, Domino generates one activity logging record for each database replication request that a server initiates. Only the initiating server generates activity logging records. Activity logging records for replication include such information as the names of the source and destination servers, the replicaID of the database that was replicated, and the number of bytes replicated in each direction. There are no Checkpoint records for replication activity logging. When a client initiates replication with a server, Domino logs the activity as session activity, not as replication activity. In addition, using the Cluster Replicator does not generate activity logging records for replication.

SMTP activity logging
SMTP activity logging tracks SMTP session activity, such as the IP address of the connected client, the number of messages the client sends to the server, the number of bytes the client sends to and receives from the server, the number of recipients to whom messages are sent, and the duration of the session. There are three types of activity logging records for SMTP sessions: • • • Open records, which log when an SMTP session begins Checkpoint records, which log activity that occurs when an SMTP session has been open for a specified length of time Close records, which consolidate SMTP information into a single record when an SMTP session ends

57-10 Administering the Domino System, Volume 2

Example of creating activity logging records
This example shows the activity logging records that Domino generates when a user sends mail to another user whose mail database is on a different mail server. In this example, the message goes directly to the recipient’s mail server without making any intermediate hops. Domino generates some of these records, such as Notes session Checkpoint records and Notes database Checkpoint records, only if the activity occurs after the checkpoint interval has elapsed during the session.
Activity Records generated Server that generates records Sending server Sending server

1. User opens mail database 2. User creates a mail message 3. User sends message to MAIL.BOX

Notes Session Open Notes Database Open The following are possible: Notes Session Checkpoint Notes Database Checkpoint Mail Deposit plus the following: If the message contains an attachment: Notes Database Open Notes Database Close If the message does not contain an attachment: Notes Database MailDeposit The following are possible: Notes Session Checkpoint Notes Database Checkpoint Mail Transfer

Monitoring

Sending server

4. User saves message

Sending server

5. The Router picks up the message from MAIL.BOX 6. The Router deposits the message in the destination server’s MAIL.BOX

Sending server

Mail Deposit plus the following: If the message contains an attachment: Notes Database Open Notes Database Close If the message does not contain an attachment: Notes Database MailDeposit

Receiving server

continued

Setting Up Activity Logging 57-11

Activity

Records generated

Server that generates records Receiving server Receiving server

7. The Router delivers the message to the user’s mail database 8. User opens mail database and reads message

Mail Delivery

Notes Database Open

Configuring activity logging
You configure activity logging by editing the Configurations Settings document. 1. From the Domino Administrator, click the Configuration tab. 2. In the Task pane, expand Server and click Configurations. 3. In the Results pane, select the Configuration Settings document you want, and click Edit Configuration. 4. On the Configuration Settings document, click the Activity Logging tab. 5. Select “Activity logging is enabled.” 6. In the “Enabled logging types” field, select the types of activity you want to log. 7. (Optional) To increase or decrease the frequency of creating Checkpoint records, change the checkpoint interval. 8. (Optional) To automatically create Notes session and Notes database Checkpoint records every day at midnight, select Log checkpoint at midnight. 9. (Optional) To automatically create Notes session and Notes database Checkpoint records every day at the beginning and end of a specific time period, select “Log checkpoints for prime shift” and then specify the times for the Prime shift interval. 10. Click Save & Close. 11. (Optional) If you are logging activity for LDAP Add and Modify operations and want to change the amount of information logged in the Attributes field from the default of 4096 bytes, follow the steps in the topic “Limiting the amount of attribute information logged for LDAP Add and LDAP Modify activity.”

57-12 Administering the Domino System, Volume 2

Limiting the amount of attribute information logged for LDAP Add and LDAP Modify activity
Since it is possible for LDAP Add and LDAP Modify operations to add or modify many attribute values, by default activity logging stops logging attribute information in a record when the amount logged reaches 4096 bytes in that record. To specify a different amount of attribute information to log: 1. From the Domino Administrator, open the server that runs the LDAP service or a server in the same domain as the server that runs the LDAP service. 2. Click the Configuration tab. 3. In the Task pane, expand Directory; then expand LDAP; and then select Settings. 4. Do one of the following: • If you see the message “Unable to locate a Server Configuration document for this domain. Would you like to create one now?” click Yes, and then click the LDAP tab on the document that is created. • If you do not see this message, click “Edit LDAP Settings.” 5. In the field “Activity Logging truncation size,” type a value (in bytes). 6. Click Save & Close.

Monitoring

Viewing activity logging data
You can view the activity logging information by running Activity Analysis, which copies the information you specify to the Log Analysis database (LOG4A.NSF or whatever name you specify). Domino creates the Log Analysis database on your local computer. The Log Analysis database includes views for the following activity information:
View Agent All HTTP IMAP Description For agent activity, shows the user, date, database, agent name, and run time Shows the activity type and timestamp of all activity logging records For HTTP activity, shows the target server, user name, date, HTTP request, time of the request, and the length of the content For IMAP activity, shows the organization name, server name, user name, timestamp, bytes sent and received, and the duration continued Setting Up Activity Logging 57-13

View LDAP Add

Description For LDAP Add activity, shows the organization name, user name, timestamp, name of the added object (entry), number of bytes received, and any error messages For all LDAP activity, shows the organization name, type of activity, user name, and the timestamp

LDAP All

LDAP Delete For LDAP Delete activity, shows the organization name, user name, timestamp, name of the deleted object (entry), number of entries deleted, and any error messages LDAP Modify LDAP ModifyDN For LDAP Modify activity, shows the organization name, user name, timestamp, name of the modified object (entry), number of bytes received, and any error messages For LDAP ModifyDN activity, shows the organization name, user name, timestamp, name of the modified object (entry), the new RDN, the new superior, and any error messages

LDAP Search For LDAP Search activity, shows the organization name, user name, timestamp, base object, filter, bytes sent, and the search time Mail Deposited For mail deposited into MAIL.BOX, shows the server name, who the message was from and to, when the message was deposited, the message ID, and the action taken upon the message (depositing the mail into MAIL.BOX) For messages processed in MAIL.BOX, such as mail transferred to other servers and mail delivered to users, shows the server name, who the message was from and to, when the message was deposited, the message ID, and the action taken upon the message For Notes database activity, shows the organization name, server name, user name, database name, timestamp, number of bytes sent and received, number of documents read and written, and the total number of transactions For Notes passthru activity, shows the date, duration of the connection, and the number of bytes sent and received by the client and by the target server

Mail Processed

Notes Database

Notes Passthru

Notes Session For Notes session activity, shows the organization name, server name, user name, timestamp, number of bytes sent and received, number of documents read and written, and the total number of transactions continued

57-14 Administering the Domino System, Volume 2

View POP3

Description For POP3 activity, shows the organization name, server name, user name, timestamp, number of messages retrieved by and deleted from the client, number of bytes the client sent to the server and received from the server, and the duration of the session For replication activity, shows the date, source server and database name, destination server and path, and the number of bytes transferred For SMTP activity, shows the organization name, server name, IP address of the connected client, timestamp, number of messages the client sent, number of recipients to whom the messages were sent, number of bytes the client sent to and received from the server, and the duration of the session

Replica

SMTP Session

Note In addition to containing the results of running activity analysis, the Log Analysis database may contain the results of running log analysis, especially if you run log analysis using a version of Domino earlier than Lotus Domino 6.

Monitoring

Running activity analysis
1. In the Domino Administrator, make the server on which you want to run activity analysis current. 2. Click the Server - Analysis tab. 3. In the Tools pane, expand Analyze; and then click Activity. 4. Do one of the following to select the types of activity you want to log: • To log all the types of activity, skip this step. By default, all activity types are selected. • To deselect a type of activity to log, click the activity type in the “Selected types of activity” pane, and then click Remove. To deselect all the types of activity, click Remove All. • To select a type of activity to log, click the activity type in the “Select server activity types to search for” pane; and then click Add. To add all the types of activity, click Add All. 5. Choose the starting and ending dates and times of the activity you want to view. 6. (Optional) To write the analysis results to a database other than the Log Analysis database, click Results Database and specify a different database. Then click OK.

Setting Up Activity Logging 57-15

7. Select “Append to this database” to append the results of the analysis to previous results in the database, or select “Overwrite this database” to create a new database that contains only the results of the current analysis. 8. Click OK to run the analysis and to open the Log Analysis database.

Viewing the data in the Log Analysis database
1. If the Log Analysis database is not already open, do the following: • On your local computer, choose File - Database - Open. • Select the Log Analysis database, and then click Open. (By default, the database title is “Log Analysis” and the file name is LOGA4.NSF.) 2. In the Task pane, expand Server Activity; and then click the view for the type of activity you want to view. 3. (Optional) In the Results pane, double-click the record you want to view.

57-16 Administering the Domino System, Volume 2

Chapter 58 Maintaining Databases
This chapter describes how to maintain databases after you deploy them.

Database maintenance
To keep a specific database in good working order, perform these tasks regularly.
Task Monitor replication, if a database replicates Frequency Daily

Monitoring

Check for and consolidate replication or Daily, for large active databases; save conflicts weekly for other databases Monitor database activity Monitor database size Weekly Weekly

For information on monitoring database replication and database activity, see topics in this chapter. For information on monitoring database size, see the chapter “Improving Database Performance.” In addition, if you’re a server administrator, perform the following tasks regularly to maintain all databases on a server.
Task Run the Updall task to update all views and full-text indexes Frequency Daily. Occurs by default daily at 2 AM.

Run the Designer task to keep databases Daily. Occurs by default daily at 1 that inherit design from master templates AM. in sync with the master templates Run the Compact task Weekly or monthly with the -B argument and in conjunction with a certified backup utility. Occasionally

Monitor the database cache

For information on running the Updall and Designer tasks, see the topic “Synchronizing databases with master templates, ” later in this chapter. For information on running the Compact task and monitoring the database cache, see the chapter “Improving Database Performance.”
58-1

The Files tab in the Domino Administrator
The Files tab in the Domino Administrator provides an easy way for you to manage files in the Domino data folder. From the Files tab, you can: • • • View file information Manage databases — for example, compact databases and manage ACLs Manage folders and links

• Display disk space information To customize the Files tab, you can: • • • Choose the types of files you see Choose the folder contents you see Customize the column display

To display the Files tab
1. From the Domino Administrator, select a server in the Server pane on the left. To expand the pane, click the Servers icon. 2. Click the Files tab.

To open a specific database or template
Select the database or template in the files pane of the Files tab, and then double-click.

Choosing the types of files you see in the Files tab
Do the following to choose the types of files you see in the Files tab: 1. From the Domino Administrator, click the Files tab. 2. In the “Show me” box, select one of the following options to control the type of files that the files pane displays: • Databases only — Displays databases but not templates • Templates only — Displays templates and databases that act as templates • Mail Boxes only— Displays only MAIL.BOX databases for administrators to quickly open when monitoring mail • All database types — Displays all databases and templates • All files — Displays all types of files • Database links only — Displays only database links

58-2 Administering the Domino System, Volume 2

3. To choose a combination of files to display, in the box, select Custom, select one or more of these options, and then click OK: • Databases • Templates — Displays all templates except advanced templates • Advanced templates — Displays advanced templates • Database Links • Mail boxes • ID files • Modem files Alternately, you can specify one or more custom file extensions to display files with those extensions, for example, TXT or BMP.

Choosing the folder contents you see in the Files tab
To choose the contents of folders that you see in the Files tab, do the following:

Monitoring

1. From the Domino Administrator, click the Files tab. 2. Use the left pane in the Files tab to select a folder. By default, you see only files in the selected folder. To see all the files in the Domino data folder, click the files icon. The Files tab can display files only in the data folder and in any folders within the data folder.

Customizing the columns in the Files tab
The files pane of the Files tab in the Domino Administrator displays the following information about databases in the order specified, by default: • • • • • • • • • • • • Title File name Physical Path File Format Size Max Size Quota Warning Created Last Fixup Is Logged Template

Maintaining Databases 58-3

To add and remove columns 1. From the Domino Administrator, choose Files - Preferences Administration Preferences. 2. Click the Files icon. 3. To add a column, select the column in the Available Columns box and then click the right arrow to include the column in the Use These Columns box. All available columns are displayed by default. 4. To remove a column, select the column in the Use These Columns box, and then click the left arrow to remove the column. 5. Click OK. To change the order of columns 1. From the Domino Administrator, choose Files - Preferences Administration Preferences. 2. Select the Files icon. 3. Select the column in the Use These Columns box and do the following: • To move the column one place to the right, click the up arrow below the box. • To move the column one place to the left, click the down arrow below the box. 4. Click OK.

Managing databases with the Files tab
Use the Files tab to manage databases from the Domino Administrator. 1. From the Domino Administrator, click the Files tab. 2. Select one or more databases in the files pane. 3. In the tools pane on the right, select Database and then select a tool described in the following table. Or drag selected database(s) to the tool.
Database tool Manage ACL Create Replica Compact Full-text index Description Manages access control lists Creates replicas of databases using the Administration Process server task Compacts databases Manages full-text indexes

Multi-Database Index Enables and disables multi-database indexing for databases Advanced Properties Set advanced database properties continued 58-4 Administering the Domino System, Volume 2

Database tool Quotas Move Sign Replication Fixup Cluster Analyze Find Note Create Db Event Generator Manage Views

Description Set quotas to limit the size of databases Moves databases using the Administration Process server task Signs databases with signatures that can be used for workstation data security Enables and disables replication of databases Fixes corrupted databases Manages databases in a cluster Runs a database analysis Finds a document based on Note ID or UNID and displays its properties to aid in troubleshooting Monitors a database based on various criteria Frees space used by view indexes

Monitoring

Managing folders and links with the Files tab
Use the Folder tool in the Files tab to manage folders, and folder and database links from the Domino Administrator. 1. From the Domino Administrator, click the Files tab. 2. Select a folder location in the left pane. 3. In the Tools pane on the right, select Folder and choose one of the following options: • New • New Link • Update Link • Delete For more information, see the chapter “Organizing Databases on a Server.”

Displaying disk space information with the Files tab
Use the Disk Space tool in the Files tab of the Domino Administrator to display the disk size and free disk space on a selected server. 1. From the Domino Administrator, select the server for which you want to display disk space. 2. Click the Files tab. 3. In the Tools pane on the right, select Disk Space.
Maintaining Databases 58-5

Monitoring replication of a database
If there are replicas of a database, you can use any of these methods to monitor replication daily.
Method Replication history Description Records each successful replication session for a database. Useful for determining at a glance if a replication is occurring. Shows details about replication events between servers. Useful for determining the cause of replication failure and for verifying that the expected number of replication updates occurred. Notifies you when replication of a database hasn’t occurred within a specified time period. A server administrator creates replication monitors as a part of configuring the Event Monitor task. Lets you collect replication history, replication events from the log file, and other information specific to a database into a results database that you can analyze.

Replication Events view of the log file (LOG.NSF) Replication monitor

Database Analysis tool

In addition to ensuring that a database is replicating, you should routinely check for and consolidate replication and save conflicts. For more information on the Database Analysis tool, see the topic “Database analysis,” later in this chapter.

The database replication history
A database’s replication history is stored in the Basics tab of the Database Properties box. The first time one server replica successfully replicates with a replica on another server, Domino creates an entry in the replication history. The entry contains the name of the other server, as well as the date and time of the replication. Separate entries are created when a replica sends information and when a replica receives it. On each subsequent replication with a specific server, Domino updates the entry in the history to reflect the most recent replication time. Domino uses the replication history to determine which documents to scan for changes during the next replication. For example, if a database successfully replicated with the HR-E/East/Acme server 24 hours ago, Domino replicates only those documents that were added, modified, or deleted in the replica on HR-E/East/Acme within the last 24 hours. Before replication starts between two databases, Domino checks the replication history of both databases to make sure that they agree. If they don’t, Domino scans each document created or modified since the date
58-6 Administering the Domino System, Volume 2

specified in the “Only replicate incoming documents saved or modified after” setting on the Other panel of the Replication Settings dialog box. If a database doesn’t replicate successfully, Domino doesn’t update the replication history. Clearing the replication history If you have Manager access to a database, you can clear the database replication history if you think the database doesn’t contain all the documents it should or if the database replication history is not synchronized with that of other replicas. Clear the replication history only as a last resort to solve replication problems. If you clear the history, during the next replication, Domino scans each document created or modified since the data specified in the “Only replicate incoming documents saved or modified after” setting on the Other panel of the Replication Settings dialog box. Scanning all these documents can be time-consuming, especially over dial-up connections. If you clear the “Only replicate incoming documents saved or modified after” setting, Domino scans all documents in the database. Within a server cluster, the Cluster Replicator stores replication history information in memory and updates the replication history about once an hour. For information on viewing cluster replication data, see the book Administering Domino Clusters. For more information on the “Only replicate incoming documents saved or modified after” setting, see the chapter “Creating Replicas and Scheduling Replication.”

Monitoring

Displaying and clearing the replication history
To display a replication history 1. Make sure you have Reader access or higher in the database ACL. 2. Open the database. 3. Choose File - Replication - History. 4. Do one of the following: • Select Date to view the information by date. • Select Server name to view the information by server. 5. Click Done when you finish reviewing the history. Tip If the replication history dialog box truncates an entry, click Zoom to display the complete entry. To copy the entire replication history to the Clipboard, click Copy.

Maintaining Databases 58-7

To clear a replication history 1. Make sure you have Manager access in the database ACL. 2. Open the database. 3. Choose File - Replication - History. 4. Do one of the following: • To clear one entry, select it, click Zoom, click Remove, then click Yes. • To clear the entire replication history, click Clear, then click Yes. 5. Click Done.

Viewing replication events in the log file
The Replication Log entries in the Replication Events view of the log file (LOG.NSF) display detailed information about the replication of specific databases. For each database that has replicated on a specified server, a Replication Log shows the access the server has to the database; the number of documents added, deleted, and modified; the size of the data exchanged; and the name of the replica that this database replicated with. The Events section of a Replication Log shows any problems that occurred when a specific database replicated. For example, the Events section shows if replication is disabled or if the database ACL is preventing replication. 1. From the Domino Administrator, select the server that stores the log file you want to view. 2. Click the Server - Analysis tab. 3. Select Notes Log - Replication Events. 4. Open a recent Replication Log.

Replication or save conflicts
Multiple users can simultaneously edit the same document in one copy of a database or edit the same document in different replicas between replication sessions. When these conditions occur, Domino stores the results of one editing session in a main document and stores the results of additional editing sessions as response documents. These response documents have the title “Replication or Save Conflict.” Domino uses the $Revisions field, which tracks the date and time of each document editing session, to determine which document becomes the main document and which documents become responses.

58-8 Administering the Domino System, Volume 2

Replication conflicts
A replication conflict occurs when two or more users edit the same document and save the changes in different replicas between replications. These rules determine how Domino saves the edit sessions: • The document edited and saved the most times becomes the main document; other documents become Replication or Save Conflict documents. If all of the documents are edited and saved the same number of times, the document saved most recently becomes the main document, and the others become Replication or Save Conflict documents If a document is edited in one replica but it is deleted in another replica, the deletion takes precedence, unless the edited document is edited more than once or the editing occurs after the deletion.

Save conflicts
A save conflict occurs when two or more users open and edit the same document at the same time on the same server, even if they’re editing different fields. When this situation occurs, the first document saved becomes the main document. Before the second document is saved, a dialog box indicates that the user is about to save a conflict document and if the user saves the document, it becomes a Replication or Save Conflict document. Note ACL and design changes never result in replication or save conflicts; the most recent change always prevails.

Monitoring

Preventing replication or save conflicts
The following techniques reduce or eliminate replication or save conflicts. The first four are techniques that a database designer uses: • Select the Form property “Merge replication conflicts” to automatically merge conflicts into one document if no fields conflict. This applies to replication conflicts only and not to save conflicts. Specify a Form property for versioning so that edited documents automatically become new documents. Lock documents in a database. Use LotusScript to write a custom conflict handler. For information on designing forms and using LotusScript, see the books Application Development with Domino Designer and Domino Designer Programming Guide, Volumes 2A and 2B: LotusScript/COM/OLE Classes.
Maintaining Databases 58-9

• • •

The last three are techniques that a system administrator or database manager can use: • • • Assign users Author access or lower in the database ACL to prevent users from editing other users’ documents. Keep the number of replicas to a minimum. If the database property “Limit entries in $Revisions fields” is set to a value greater than 0, increase the limit by specifying a greater value than the existing one or specify -1 to remove the limit.

For more information on the database property “Limit entries in $Revisions fields,” see the chapter “Improving Database Performance.”

Consolidating replication or save conflicts
Regularly look for and consolidate replication or save conflicts. To consolidate a conflict, merge information into one document and remove the other document. Conflicts are easiest to consolidate immediately after they occur, since the conflict document is still closely synchronized with the information in the main document. It’s important to consolidate replication or save conflicts quickly, so users access the correct information. Tip To locate replication or save conflicts, create a view that displays only conflict documents. Then, to see a conflict document in context with its main document, select the Replication or Save Conflict document in the view that displays conflicts, hold down the CTRL key, and switch to the view that shows the main document. To consolidate replication or save conflicts, you can save the main document or save the Replication or Save Conflict document

To save the main document
1. Copy any information you want to save from the Replication or Save Conflict document into the main document. 2. Delete the conflict document.

To save the Replication or Save Conflict document
1. Do one of the following: • Copy any information you want to save from the main document into the Replication or Save Conflict document. • If you do not need to save any information from the main document, perform a minor edit in the replication or save conflict document — for example, delete a space.

58-10 Administering the Domino System, Volume 2

2. Save the conflict document. The conflict document becomes a main document. 3. Delete the original main document.

Monitoring database activity
Monitor database activity regularly. If database activity is high and users report performance problems, do any of the following: • • • • • Set database properties that improve performance. Create a replica of the database on another server, if possible, one within a server cluster. Move the database to a more powerful server. Move the database to a disk that is less heavily used, or if it’s a large database, to its own disk.

Monitoring

Track database activity with activity logging.

If a database or view is inactive, consider deleting the database or view to free disk space on the server.

How the Statlog task generates activity statistics
The Statlog task on a server runs by default once a day at 5 AM, at which time it reports database activity for databases on the server in Database Activity Log entries in the Database - Usage and Database - Sizes views of the log file (LOG.NSF) and to the User Activity dialog box of individual databases. This table compares the information generated in each location.
Information provided Database Activity Log entry User Activity dialog box Yes

Shows total number of times user and servers Yes accessed, read, and wrote to a database in past 24 hours, past week, past month, and since the creation of the database* Shows inactive views (indicated by the size 0) Yes Shows names of users and servers who read and No wrote documents, sorted by date* * Includes activity for anonymous and authenticated Internet clients.

No Yes

Maintaining Databases 58-11

Tip In addition to viewing activity statistics reported by Statlog, you can evaluate database activity by creating a view that sorts documents by date. You can also create File Monitor documents as part of Event Monitor configuration. File Monitors report user activity for specific databases. For information on creating views, see the book Application Development with Domino Designer. For information on monitoring database activity within a server cluster, see the book Administering Domino Clusters. Statlog always reports activity information to the log file, but to save disk space, you can prevent it from automatically reporting to User Activity dialog boxes. Note The Statlog task also reports database size statistics in the Database - Sizes view of the log file.

Viewing database activity statistics generated by the Statlog task
Instead of opening the log file or viewing the User Activity dialog box directly as described below, you can use the Database Analysis tool to see activity statistics. For information on monitoring database activity using the Database Analysis tool, see the topic “Database analysis,” later in this chapter. In the log file (LOG.NSF) 1. From the Domino Administrator, select the server that stores the log file you want to view. 2. Click the Server - Analysis tab. 3. Do one of the following: • Select Notes Log - Database - Sizes • Select Notes Log - Database - Usage 4. Double-click a Database Activity Log entry to view it. Tip If you don’t have access to the Domino Administrator, select the log file database and choose File - Database - Open. In the User Activity dialog box 1. Open the database and choose File - Database - Properties. 2. Click the i tab, and then click User Detail. Tip To track usage over a period of time, choose Copy to Clipboard to copy the summary to a document that you use to track usage statistics.

58-12 Administering the Domino System, Volume 2

Managing database activity recording in databases
Disable automatic activity recording in User Activity dialog boxes By default, Statlog reports database activity to all database User Activity dialog boxes when it runs. Even if a user disables User Activity reporting for a specific database, the next time Statlog runs, it enables recording in the dialog box again. To prevent Statlog from automatically recording activity in User Activity dialog boxes, add No_Force_Activity_Logging=1 to the NOTES.INI file. Then, you can enable activity recording per database, as needed. Because recording activity in the User Activity dialog box adds 64K to the size of each database, disabling automatic activity recording saves disk space on the server. Tip Disable automatic activity recording to improve database performance. Note If you use No_Force_Activity_Logging, Statlog still reports activity to the log file (LOG.NSF). Enable activity recording in a single database’s User Activity dialog box Even if the server administrator uses the No_Force_Activity_Logging setting in the NOTES.INI file to disable automatic activity recording in databases, you can enable recording for a single database. 1. Make sure that you have Designer or Manager access in the database ACL. 2. Open the database and choose File - Database - Properties. 3. Click the i tab, and then click User Detail. 4. Select Record Activity to enable activity recording. 5. (Optional) Select “Activity is Confidential” to allow only users with at least Designer access in the database ACL to view the activity. 6. Click OK. Disable activity recording in a single database’s User Activity dialog box Use the above procedure, but deselect Record Activity in Step 4. Disabling activity recording also removes any existing activity statistics in the User Activity dialog box.

Monitoring

Maintaining Databases 58-13

Updating database indexes and views
A view index is an internal filing system that Lotus Notes uses to build the list of documents to display in a database view or folder. View indexes should be kept up-to-date so that information in views and folders stays synchronized with document updates. You can also purge or delete view indexes to improve database performance. A full-text index is an index of the text in a database. To perform advanced searches for text in a database, users need an up-to-date full-text index that reflects the latest content of a database. You can use any of these methods to update database indexes: • • • • The Update task The Updall task Keyboard shortcuts The Database Properties box

For information on using the Database Properties box to update full-text search indexes, see the chapter “Setting Up and Managing Full-text Indexes.”

Indexer tasks: Update and Updall
The Update and Updall tasks keep view indexes and full-text indexes up-to-date.

Update
Update is loaded at server startup by default and runs continually, checking its work queue for views and folders that require updating. When a view or folder change is recorded in the queue, Update waits approximately 15 minutes before updating all view indexes in the database so that the update can include any other database changes made during the 15-minute period. After updating view indexes in a database, it then updates all databases that have full-text search indexes set for immediate or hourly updates. When Update encounters a corrupted view index or full-text index, it rebuilds the view index or full-text index in an attempt to correct the problem. This means it deletes the view index or full-text index and rebuilds it. To improve view-indexing performance, you can run multiple Update tasks if your server has adequate CPU power.

58-14 Administering the Domino System, Volume 2

Note The Update task spawns a directory indexer thread. The directory indexer runs at one-minute intervals and is dedicated to keeping Domino Directory view indexes up-to-date. The directory indexer runs against any local or remote Domino Directory or Extended Directory Catalog that a server uses for directory services.

Updall
Updall is similar to Update, but it doesn’t run continually or work from a queue; instead you run Updall as needed. You can specify options when you run Updall, but without them Updall updates any view indexes or full-text search indexes on the server that need updating. To save disk space, Updall also purges deletion stubs from databases and discards view indexes for views that have been unused for 45 days, unless the database designer has specified different criteria for discarding view indexes. Use the NOTES.INI setting Default_Index_Lifetime_Days to change when Updall discards unused view indexes. Like Update, Updall rebuilds all corrupted view indexes and full-text search indexes that it encounters. By default Updall is included in the NOTES.INI setting ServerTasksAt2, so it runs daily at 2 AM. Running Updall daily helps save disk space by purging deletion stubs and discarding unused view indexes. It also ensures that all full-text search indexes that are set for daily updates are updated. The following table compares the characteristics of Update and Updall. For Updall, the table describes default characteristics. For information on options you can use to modify some of these characteristics, see the topic “Updall options” later in this chapter.
Characteristic When it runs Runs on all databases? Refreshes views indexes? Updates full-text indexes? Update Continually after server startup No. Runs only on databases that have changed. Yes Yes. Updates full-text indexes set for immediate and hourly updates. Updall 2 AM and when you run it Yes Yes Yes. Updates all full-text indexes. Yes

Monitoring

Detects and attempts Yes to rebuild corrupted view indexes?

continued Maintaining Databases 58-15

Characteristic

Update

Updall Yes

Detects and attempts Yes to rebuild corrupted full-text indexes? Purges deletion stubs? Discards unused view indexes? No No

Yes Yes (after a view is unused for 45 days or according to a view discard option specified by a designer) Yes

Ignores “Refresh index” view property? Can customize with options?

Yes

No

Yes

Updall options
You can use any of these methods to run Updall on a server: • • Task - Start tool in the Domino Administrator — Use this method if you don’t want to use command-line options. Load Updall console command — Use this method if you’re comfortable using command-line options or if you want to run Updall directly at the server console when there is no Domino Administrator running on the server machine. Program document that runs Updall — Use this method to schedule Updall to run at particular times. Run Updall on a Win32 platform — Use this method if you are unable to run Updall at the server console. This method requires that you use the “n” prefix — for example, nupdall - R.

• •

When you use these methods, you can include options that control what Updall updates. For example, you can update all views and not update any full-text search indexes. The following tables describe the options you can use with Updall. The first column describes the option names as they appear in the Task - Start tool. The second column lists the equivalent command-line options that you use when you use a console command to run Updall and when you schedule Updall to run in a Program document.

58-16 Administering the Domino System, Volume 2

Use this syntax when you use the Load updall console command:
Load updall databasepath options

For example:
Load updall SALES.NSF -F

You can specify multiple options — for example:
Load updall -F -M

For information on Updall behavior when you don’t specify options, see the topic “Indexer tasks: Update and Updall,” earlier in this chapter. Updall - Basic options
Option in Task - Start Command-line tool option • • Index all databases Index only this database or folder databasepath For more information on databasepath, see the topic “Using a console command,” later in this chapter. Description “Only this database” updates only the specified database. To update a database in the Domino data folder, enter the file name, for example, SALES.NSF. To update databases in a folder within the data folder, specify the database path relative to the data folder, for example, DOC\README.NSF. “Index all databases” (or no database path) updates all databases on the server. Updates a specific view in a database. Use, for example, with -R to solve corruption problems.

Monitoring

Update this view only

database -T viewtitle

Updall - Update options
Option in Task - Start tool Update: All built views Update: Full text indexes Update: Full text indexes: Only those with frequency set to: Immediate Command-line Description option -V -F -H Updates built views and does not update full-text indexes. Updates full-text indexes and does not update views. Updates full-text indexes assigned “Immediate” as an update frequency.

continued

Maintaining Databases 58-17

Option in Task - Start tool Update: Full text indexes: Only those with frequency set to: Immediate or Hourly Update: Full text indexes: Only those with frequency set to: Immediate or Hourly or Daily

Command-line Description option -M Updates full-text indexes assigned “Immediate” or “Hourly” as an update frequency. Updates full-text indexes assigned “Immediate,” “Hourly,” or “Daily” as an update frequency.

-L

Updall - Rebuild options
Option in Task - Start tool Rebuild: Full-text indexes only Rebuild: All used views Command-line Description option -X Rebuilds full-text indexes and does not rebuild views. Use to rebuild full-text indexes that are corrupted. Rebuilds all used views. Using this option is resource-intensive, so use it as a last resort to solve corruption problems with a specific database. Rebuilds unused views and a full-text index in a database. Requires you to specify a database.

-R

Rebuild: Full-text indexes and additionally: All unused views

database -C

Updall - Search Site options
Option in Task - Start tool Update database configurations: Incremental Update database configurations: Full Command-line Description option -A Incrementally updates search-site database configurations for search site databases. Does a full update of search-site database configurations for search site databases.

-B

58-18 Administering the Domino System, Volume 2

Running the Updall task
Using the Task - Start tool 1. From the Domino Administrator, select the server on which to run Updall. 2. Click the Server - Status tab. 3. In the task panel on the right, click Task - Start. 4. Select “Update all.” Do not select “Update.” 5. Do one of the following: • To customize how Updall runs, click “Select advanced options,” click Start Task, specify options to customize how Updall runs, then click OK. • To run Updall without options, deselect “Select advanced options” and then click Start Task. Using a console command 1. From the Domino Administrator, select the server on which to run Updall. 2. Click the Server - Status tab. 3. Click Console. 4. Enter the following command in one of the following ways: 1) In the command line at the bottom of the console, and then press ENTER, or 2) Directly at the console on a server:
Load updall databasepath options

Monitoring

where databasepath specifies the files on which to run Updall and options are Updall command-line options. For example, enter :
Load updall SALES.NSF -F

The following table illustrates how you can use databasepath to specify databases, folders, and subfolders.
To compact Example command Files compacted DATA\SALES.NSF DATA\DEV.NSF DATA\SALES\all databases continued

Load updall Specific databases in the Domino data folder SALES.NSF,DEV.NSF

All the databases in a folder relative to the Domino data folder

Load updall SALES

Maintaining Databases 58-19

To compact

Example command

Files compacted DATA\SALES\ USER1.NSF

A specific database in a Load updall SALES\USER1.NSF folder relative to the Domino data folder

All the files specified in Load updall WEEKLY.IND DATA\SALES.NSF an IND file created in DATA\DEV.NSF where WEEKLY.IND the Domino data folder contains: DATA\SALES\ SALES.NSF USER1.NSF DEV.NSF DATA\SALES\NEW\all SALES\USER1.NSF databases
SALES\NEW

Using a Program document Use a Program document to schedule Updall to run with options at a regular time. Note that by default Updall is included in the NOTES.INI setting ServerTasksAt2, so it runs daily at 2 AM on all databases without options. For more information on Program documents, see the appendix “Server Tasks.” 1. From the Domino Administrator, click the Configuration tab. 2. Next to “Use Directory on,” select the server with the replica of the Domino Directory that you want to modify. 3. Expand Server - Programs and then click Add Program. 4. Complete these fields on the Basics tab:
Field Program name Command line Server to run on Comments Enter Updall Command line options. Don’t specify “load” before the options. Server on which to run Updall Optional comments

For more information on the available command-line options, see the topic “Updall options,” earlier in this chapter.

58-20 Administering the Domino System, Volume 2

5. Complete these fields on the Schedule tab:
Field Enabled/disabled Run at times Repeat interval of Days of week Enter Enabled Times to run Updall each day How soon to run Updall again after it completes The days to run Updall

6. Click Save and Close.

Keyboard shortcuts that update or rebuild views
This table describes the keyboard shortcuts you can use to update or rebuild views.
Shortcut F9 SHIFT+ F9 Description Updates the current view Rebuilds the current view When to use To display current information in the view To fix problems with a view To rebuild or update all views if you are unable to run the Updall task. You must wait until the process is complete, so use Updall instead if possible.

Monitoring

CTRL+SHIFT+ Rebuilds all views in a F9 database that are not built; updates all other views

Running multiple Update tasks
To improve view indexing performance, you can run multiple Update tasks. Doing this can affect server performance and is recommended primarily for multi-processor machines. On a server with multiple processors, enable a maximum of one Update task per processor. Using a Configuration settings document 1. From the Domino Administrator, click the Configuration tab. 2. Next to “Use Directory on,” select the server that stores the Domino Directory you want to modify. 3. Expand Server - Configurations. 4. Do one of the following: • Click Edit Configuration to edit an existing Configuration settings document • Click Add Configuration to create a new Configuration settings document

Maintaining Databases 58-21

5. Click the NOTES.INI Settings tab. 6. Click Set/Modify Parameters. 7. In the Item box, select Updaters. In the Value box, enter the number of Update tasks to run. Then click OK. 8. Click Save and Close. 9. Restart the server so that the setting takes effect. Using the Task - Start tool Use the Task - Start tool to run multiple Update tasks without having to shut down and restart the server. If you eventually shut down the server, you must repeat this procedure when you restart it. Each time you enter this command, the server loads another Update task. 1. From the Domino Administrator, select the server on which to run Update. 2. Click the Server - Status tab. 3. In the Tools pane on the right, click Task - Start. 4. Select “Update.” Do not select “Update all.” 5. Click Start Task. Tip You can also enter the following command at the console:
Load update

Changing the temporary folder used for view rebuilds
When Domino rebuilds views — for example, when you use updall -R or when a user opens a view whose index has been deleted — it may generate temporary files to sort the data in order to rapidly update the views; Domino deletes these files after rebuilding the views. By default, these temporary files are located in your system’s temporary folder — for example, C:\TEMP. If your system doesn’t have a temporary folder, then Domino puts the files in the Domino data folder. Depending on the amount of memory available during rebuilding, the space required in the temporary folder for each view being rebuilt is approximately two times the size of the largest view or two times the size of all the data in documents, whichever value is greater. It is recommended that you change the location of the temporary files to a different drive from the Domino data folder. Putting the temporary folder on a different drive distributes disk I/O and ensures that there is enough space to rebuild views. Domino is very conservative when estimating the amount of disk space needed for optimized view rebuilds so that it won’t spend unnecessary time sorting data only to discover that

58-22 Administering the Domino System, Volume 2

there’s inadequate disk space. Make sure that the temporary folder you specify has plenty of disk space available. To change the temporary folder used for view rebuilds, add the setting View_Rebuild_Dir to the server’s NOTES.INI file and specify a new location. For example, add:
View_Rebuild_Dir=D:\REBUILD

If Domino estimates that there’s not enough space available in the temporary folder to rebuild a specific view, Domino uses a slower method to rebuild the view and logs this message to the Miscellaneous Events view of the log file (LOG.NSF):
Warning: unable to use optimized view rebuild for view due to insufficient disk space at directory. Estimate may need x million bytes for this view. Using standard rebuild instead.

You can add the following setting to the NOTES.INI file to disable optimized view rebuilding. However, do this only as a last resort if you’ve specified a view rebuild folder and you still see the preceding message for many views. If you see the message for just a few views, don’t disable view rebuilding.
Disable_View_Rebuild_Opt=1

Monitoring

Managing view indexes
A view index is an internal filing system that Lotus Notes uses to build the list of documents to display in a database view or folder. Because a database grows when you add views and folders, you can improve database performance by occasionally purging view indexes. To purge one or more of the view indexes in a database: 1. From the Domino Administrator, click the Files tab. 2. Select the database. 3. Choose Database - Manage Views. 4. For each view index in the database you want to purge: a. Select the view index. b. Click Purge. c. Click Yes at the prompt. 5. Click Done.

Maintaining Databases 58-23

Synchronizing databases with master templates
To use a consistent design for multiple databases, database designers can associate databases or elements within databases with a master template. Designers can manually synchronize databases with a master template, but more often they rely on the Designer task to do this. When a master template design changes, the Designer task updates all databases that inherit their designs from the master template. The Designer task runs daily by default at 1 AM. The Updall task, which runs by default at 2 AM, updates the view indexes of databases changed by Designer. For a server’s Designer task to update databases, you must create a replica of the master template on each server that stores databases that inherit from the master template. After updating database designs, the Designer task also reloads the LDAP schema on a Domino server that runs the LDAP service. You can’t run the Designer task against a specific database or folder. It runs only against all databases on a server. For more information on master templates, see the book Application Development with Domino Designer. You can run the Designer task by using one of the following methods.

Running the Designer task using the Task - Start tool
1. From the Domino Administrator, select the server on which to run Designer. 2. Click the Server - Status tab. 3. In the task panel on the right, click Task - Start. 4. Select Designer and then click Start Task.

Running the Designer task using a console command
1. From the Domino Administrator, select the server on which to run the Designer task. 2. Click the Server - Status tab. 3. Click Console. 4. Enter the following command in the command line at the bottom of the console, and then press ENTER:
Load design

58-24 Administering the Domino System, Volume 2

The following table describes the command line options you can use with the Designer task.
Command line option Description -d directory name Synchronizes the databases in a directory relative to the data directory. For example, to synchronize databases in the directory DATA\SALES, specify -d SALES. Synchronizes a specific database. For example, to synchronize the database DATA\SALES.NSF, specify -f SALES.NSF. Synchronizes the databases specified by name, which can be a database, folder, or file name that contains a list of paths, each of which can be a database or a folder.

-f filename

-i name

The following table shows an example of the -i command line option.
If the file SCHEDULE where contains this SALES DEV DEV\USER1.NSF SALES is a directory and DEV is a directory then load design -i SCHEDULE is the same as this
load design -d SALES load design -d DEV load design -f DEV\USER1.NSF

Monitoring

Fixing corrupted databases
Corrupted databases don’t occur frequently when you use transaction logging. When you use transaction logging to log changes to databases, a server automatically uses the transaction log to restore and recover databases after a system failure — for example, after server failures or power failures. If a disk failure occurs, you use the transaction log along with a certified backup utility to restore and recover the databases. For information on upgrading database format, see the Upgrade Guide. The Miscellaneous Events view of the log file (LOG.NSF) records detailed messages about corrupted documents and views. These messages in the log file indicate document corruption: • • Document NTdocument number in database database name is damaged Document document number in database database name has been deleted

Maintaining Databases 58-25

The following messages indicate that Domino has rebuilt, is in the process of rebuilding, or was unable to rebuild damaged views: • • • Page format is incorrect Invalid CNO vector - position == 0 Container integrity has been lost - rebuild

For information on using the log file, see the chapter “Using Log Files.”

Ways to fix corrupted databases
If you encounter database corruption in a database, you can use any of these methods to try to fix the problem. Because corruption is much less of an issue for logged databases, these methods are primarily used for solving corruption problems in unlogged databases. • • • • • Run Fixup to fix corrupted views and documents. Run Updall to fix corrupted views and full-text indexes; if a corrupted view is the problem, try Updall before trying Fixup. Run Compact with the -c option to fix corruption problems that Fixup doesn’t correct. Press SHIFT+F9 to rebuild one view; press CTRL+SHIFT+F9 to rebuild all views in a database. Create a replica of the database.

For information on using Compact, see the chapter “Improving Database Performance.”

Using Fixup
When you restart a server, the server quickly searches for any unlogged databases that were modified but improperly closed because of a server failure, power failure, hardware failure, and so on. A few minutes after server startup is complete, the Fixup task then runs on these databases to attempt to fix any inconsistencies that resulted from partially written operations caused by a failure. When users attempt to access one of these databases and Fixup hasn’t yet run on the database, the users see the message “This database cannot be opened because a consistency check of it is in progress.” A similar Fixup process occurs when you restart a Lotus Notes client.

58-26 Administering the Domino System, Volume 2

Multiple Fixup tasks run simultaneously at server startup to reduce the time required to fix databases. The number of Fixup tasks that Domino runs by default at startup is equal to two times the number of processors available on the server. Although this default behavior should be adequate in most circumstances, you can edit the NOTES.INI file to include the Fixup_Tasks setting. The actual number of tasks run is the smaller of the configured number of tasks that can run and the number of databases that require fixing. For example, if you set Fixup_Tasks to 4 but only one database requires fixing, then only one Fixup task runs. Keep in mind that after you set up transaction logging, Fixup is not needed or used to bring databases back to a consistent state.

Ways to run Fixup manually
Use Domino Administrator to use any of these methods to run Fixup manually to fix a corrupted database. With each of these methods, you can customize how Fixup runs.

Monitoring

Run Fixup using the Fixup tool in the Files tab — Use this method to run Fixup on one or a few databases; you can easily select the databases and you don’t have to use command-line options, but you can’t use the Domino Administrator until Fixup finishes. Run Fixup using the Task - Start tool — Use this method to run Fixup on all databases; you can continue to use the Domino Administrator while Fixup runs and you don’t have to use command-line options. Run Fixup using a console command — Use this method if you want to use command-line options or to run Fixup directly at the server console when there isn’t a Domino Administrator client available. Run Fixup using a Program document — Use this method to schedule Fixup to run at particular times. Run Fixup on a Win32 platform — Use this method if you are unable to run Fixup at the server console. This method requires that you use the “n” prefix, for example, nfixup - F.

• •

Maintaining Databases 58-27

Fixup options
The following table describes the options you can use with Fixup. The first column lists the options as they appear when you run Fixup using the Fixup tool or the Task - Start tool in the Domino Administrator. The second column lists the equivalent command-line options that you use when you run Fixup using a console command or using a Program document.
Fixup options in Fixup Command-line Description tool and Task - Start tool equivalent • • Fixup all databases databasepath Fixup only this database or folder “Fixup only this database or folder” runs Fixup only on a specified database or all databases in a specified folder. To run Fixup on a database in the Domino data folder, enter the file name, for example SALES.NSF. To run Fixup on a database or databases in folders within the data folder, enter the path relative to the data folder. For example, to run Fixup on all databases in the DATA\SALES folder, specify SALES. “Fixup all databases” or no command line database path runs Fixup on all databases on the server. Note To specify databases or folders to run on using the Fixup tool, select the database(s) or folder(s). Report all processed databases to log file -